쿼리 결과, 최근 쿼리, 출력 파일 작업

Amazon Athena는 Amazon S3에 지정된 쿼리 결과 위치에서 실행되는 각각의 쿼리에 대해 쿼리 결과 및 메타데이터 정보를 자동으로 저장합니다. 필요한 경우 이 위치의 파일에 액세스하여 해당 파일로 작업할 수 있습니다. 또한 Athena 콘솔에서 쿼리 결과 파일을 직접 다운로드할 수 있습니다.

Amazon S3 쿼리 결과 위치를 처음으로 설정하려면 Athena 콘솔을 사용하여 쿼리 결과 위치 지정 단원을 참조하세요.

실행되는 모든 쿼리에 대해 출력 파일은 자동으로 저장됩니다. 쿼리 출력 파일을 액세스하고 보려면 IAM 보안 주체(사용자 및 역할)가 쿼리 결과 위치의 Amazon S3 GetObject 작업에 대한 권한뿐 아니라 Athena GetQueryResults 작업에 대한 권한도 가지고 있어야 합니다. 쿼리 결과 위치를 암호화할 수 있습니다. 위치가 암호화되는 경우 사용자는 쿼리 결과 위치를 암호화하고 암호화 해제할 수 있는 적절한 키 권한을 가지고 있어야 합니다.

중요

쿼리 결과 위치의 Amazon S3 GetObject 작업에 대한 권한이 있는 IAM 보안 주체는 Athena GetQueryResults 작업에 대한 권한이 거부되더라도 Amazon S3에서 쿼리 결과를 검색할 수 있습니다.

쿼리 결과 위치 지정

Athena가 사용하는 쿼리 결과 위치는 작업 그룹 설정과 클라이언트 측 설정의 조합으로 결정됩니다. 클라이언트 측 설정은 쿼리를 실행하는 방식을 기반으로 합니다.

• Athena 콘솔을 사용하여 쿼리를 실행하는 경우 탐색 모음의 설정에 입력한 쿼리 결과 위치가 클라이언트 측 설정을 결정합니다.

• Athena API를 사용하여 쿼리를 실행하는 경우 StartQueryExecution 작업의 OutputLocation 파라미터가 클라이언트 측 설정을 결정합니다.

• ODBC 또는 JDBC 드라이버를 사용하여 쿼리를 실행하는 경우 연결 URL에 지정된 S3OutputLocation 속성에 따라 클라이언트 측 설정이 결정됩니다.

중요

API를 사용하거나 ODBC 또는 JDBC 드라이버를 사용하여 쿼리를 실행할 때는 콘솔 설정이 적용되지 않습니다.

각 작업 그룹 구성에는 활성화할 수 있는 Override client-side settings(클라이언트 측 설정 재정의) 옵션이 있습니다. 이 옵션을 활성화하면 해당 작업 그룹과 연결된 IAM 보안 주체가 쿼리를 실행할 때 작업 그룹 설정이 적용 가능한 클라이언트 측 설정보다 우선적으로 적용됩니다.

Athena 콘솔을 사용하여 쿼리 결과 위치 지정

쿼리를 실행하려면 먼저, Amazon S3에서 쿼리 결과 버킷 위치를 지정하거나, 버킷을 지정했고 구성이 클라이언트 설정을 재정의하는 작업 그룹을 사용해야 합니다.

Athena 콘솔을 사용하여 클라이언트 측 설정 쿼리 결과 위치를 지정하려면

1. 쿼리 결과 위치를 지정할 작업 그룹으로 전환합니다. 기본 작업 그룹의 이름은 Primary입니다.

2. 탐색 모음에서 설정을 선택합니다.

3. 탐색 모음에서 관리(Manage)를 선택합니다.

4. 설정 관리(Manage settings)에서 다음 중 하나를 수행합니다.

   • 쿼리 결과 위치(Location of query result) 상자에서 Amazon S3에서 쿼리 결과를 위해 생성한 버킷의 경로를 입력합니다. 경로 앞에 s3://를 붙입니다.

   • S3 검색(Browse S3) 아이콘을 선택하고 현재 리전에서 생성한 Amazon S3 버킷을 선택한 다음 선택(Choose)을 선택합니다.

   참고

   작업 그룹의 모든 사용자에 대해 쿼리 결과 위치를 지정하는 작업 그룹을 사용하는 경우 쿼리 결과 위치를 변경하는 옵션을 사용할 수 없습니다.

5. (선택 사항) View lifecycle configuration(수명 주기 구성 보기)를 선택하여 쿼리 결과 버킷에서 Amazon S3 수명 주기 규칙을 보고 구성합니다. 생성하는 Amazon S3 수명 주기 규칙은 만료 규칙 또는 전환 규칙일 수 있습니다. 만료 규칙은 일정 시간이 지나면 쿼리 결과를 자동으로 삭제합니다. 전환 규칙은 쿼리 결과를 다른 Amazon S3 스토리지 계층으로 이동합니다. 자세한 내용은 Amazon Simple Storage Service Console 사용 설명서의 버킷에서 수명 주기 구성 설정을 참조하세요.

6. (선택 사항) 예상 버킷 소유자(Expected bucket owner)에 출력 위치 버킷의 소유자가 될 것으로 예상되는 AWS 계정의 ID를 입력합니다. 이는 추가 보안 조치입니다. 버킷 소유자의 계정 ID가 여기에서 지정한 ID와 일치하지 않으면 버킷으로의 출력 시도가 실패합니다. 자세한 내용은 Amazon S3 사용 설명서의 버킷 소유자 조건을 사용하여 버킷 소유권 확인을 참조하세요.

   참고

   예상 버킷 소유자 설정은 Athena 쿼리 결과에 대해 지정한 Amazon S3 출력 위치에만 적용됩니다. 외부 Amazon S3 버킷의 데이터 소스 위치, CTAS 및 INSERT INTO 대상 테이블 위치, UNLOAD 문 출력 위치, 연합 쿼리의 유출 버킷 작업 또는 다른 계정의 테이블에 대해 실행되는 SELECT 쿼리 등의 다른 Amazon S3 위치에는 적용되지 않습니다.

7. (선택 사항) Amazon S3 저장된 쿼리 결과를 암호화하려면 쿼리 결과 암호화(Encrypt query results)를 선택하세요. Athena에서 암호화 사용에 대한 자세한 내용은 저장 중 암호화 섹션을 참조하세요.

8. (선택 사항) 쿼리 결과 버킷에 대해 ACL이 사용 설정되어 있을 때 버킷 소유자에게 쿼리 결과에 대한 전체 제어 액세스 권한을 부여하려면 버킷 소유자에게 쿼리 결과에 대한 전체 제어 할당을 선택하세요. 예를 들어, 쿼리 결과 위치가 다른 계정이 소유한 경우 쿼리 결과에 대한 소유권 및 전체 제어 권한을 다른 계정에 부여할 수 있습니다. 자세한 내용은 Amazon S3 사용자 안내서의 객체 소유권 제어 및 버킷에 대해 ACL 사용 중지를 참조하세요.

9. Save를 선택합니다.

이전에 생성한 기본 위치

이전에 Athena에서는 쿼리 결과 위치(Query result location)의 값을 지정하지 않은 상태로 쿼리를 실행하고 작업 그룹이 쿼리 결과 위치 설정을 재정의하지 않는 경우 Athena에서 기본 위치를 자동으로 생성했습니다. 기본 위치는 aws-athena-query-results-MyAcctID-MyRegion이었습니다. 여기서 MyAcctID는 쿼리를 실행한 IAM 보안 주체의 Amazon Web Services 계정 ID이고 MyRegion은 쿼리가 실행된 리전(예: us-west-1)입니다.

이제 이전에 계정이 Athena를 사용한 적이 없는 리전에서 Athena 쿼리를 실행하려면 먼저, 쿼리 결과 위치를 지정하거나, 쿼리 결과 위치 설정을 재정의하는 작업 그룹을 사용해야 합니다. Athena에서 더 이상 기본 쿼리 결과 위치를 자동으로 생성하지 않지만, 이전에 생성된 기본 aws-athena-query-results-MyAcctID-MyRegion 위치는 유효한 상태로 유지되며 계속 사용할 수 있습니다.

작업 그룹을 사용하여 쿼리 결과 위치 지정

AWS Management Console, AWS CLI 또는 Athena API를 사용하여 작업 그룹 구성에서 쿼리 결과 위치를 지정합니다.

AWS CLI를 사용할 경우 aws athena create-work-group 또는 aws athena update-work-group 명령을 실행할 때 --configuration 옵션의 OutputLocation 파라미터를 사용하여 쿼리 결과 위치를 지정합니다.

Athena 콘솔을 사용하여 작업 그룹에 대한 쿼리 결과 위치를 지정하려면

1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다.

   

2. 탐색 창에서 작업 그룹(Workgroups)을 선택합니다.

3. 작업 그룹 목록에서 편집할 작업 그룹의 링크를 선택합니다.

4. 편집(Edit)을 선택합니다.

5. 쿼리 결과 위치 및 암호화에 대해 다음 중 하나를 수행합니다.

   • 쿼리 결과 위치(Location of query result) 상자에 쿼리 결과에 대한 Amazon S3의 버킷 경로를 입력합니다. 경로 앞에 s3://를 붙입니다.

   • S3 검색(Browse S3)을 선택하고 사용하고 싶은 현재 리전에 대한 Amazon S3 버킷을 선택한 다음 선택(Choose)을 선택합니다.

6. (선택 사항) 예상 버킷 소유자(Expected bucket owner)에 출력 위치 버킷의 소유자가 될 것으로 예상되는 AWS 계정의 ID를 입력합니다. 이는 추가 보안 조치입니다. 버킷 소유자의 계정 ID가 여기에서 지정한 ID와 일치하지 않으면 버킷으로의 출력 시도가 실패합니다. 자세한 내용은 Amazon S3 사용 설명서의 버킷 소유자 조건을 사용하여 버킷 소유권 확인을 참조하세요.

   참고

   예상 버킷 소유자 설정은 Athena 쿼리 결과에 대해 지정한 Amazon S3 출력 위치에만 적용됩니다. 외부 Amazon S3 버킷의 데이터 소스 위치, CTAS 및 INSERT INTO 대상 테이블 위치, UNLOAD 문 출력 위치, 연합 쿼리의 유출 버킷 작업 또는 다른 계정의 테이블에 대해 실행되는 SELECT 쿼리 등의 다른 Amazon S3 위치에는 적용되지 않습니다.

7. (선택 사항) Amazon S3 저장된 쿼리 결과를 암호화하려면 쿼리 결과 암호화(Encrypt query results)를 선택하세요. Athena에서 암호화 사용에 대한 자세한 내용은 저장 중 암호화 섹션을 참조하세요.

8. (선택 사항) 쿼리 결과 버킷에 대해 ACL이 사용 설정되어 있을 때 버킷 소유자에게 쿼리 결과에 대한 전체 제어 액세스 권한을 부여하려면 버킷 소유자에게 쿼리 결과에 대한 전체 제어 할당을 선택하세요. 예를 들어, 쿼리 결과 위치가 다른 계정이 소유한 경우 쿼리 결과에 대한 소유권 및 전체 제어 권한을 다른 계정에 부여할 수 있습니다.

   버킷의 S3 객체 소유권 설정이 버킷 소유자 기본인 경우 버킷 소유자는 이 작업 그룹에서 작성된 모든 쿼리 결과 객체도 소유합니다. 예를 들어, 외부 계정의 작업 그룹에서 이 옵션을 활성화하고 쿼리 결과 위치를 계정의 버킷 소유자 기본의 S3 객체 소유권 설정을 가진 Amazon S3 버킷으로 설정한 경우, 외부 작업 그룹의 쿼리 결과에 대한 전체 제어 권한을 갖습니다.

   쿼리 결과 버킷의 S3 객체 소유권 설정이 버킷 소유자 시행인 경우 이 옵션은 아무 영향이 없습니다. 자세한 내용은 Amazon S3 사용자 안내서의 객체 소유권 제어 및 버킷에 대해 ACL 사용 중지를 참조하세요.

9. 작업 그룹의 모든 사용자가 지정한 쿼리 결과 위치를 사용하도록 요청하려면 설정(Settings) 섹션까지 아래로 스크롤하고 고객 측 설정 재정의(Override client-side settings)를 선택합니다.

10. Save changes(변경 사항 저장)를 선택합니다.

Athena 콘솔을 사용하여 쿼리 결과 파일 다운로드

쿼리를 실행한 후 즉시 쿼리 창에서 쿼리 결과 CSV 파일을 다운로드할 수 있습니다. 또한 최근 쿼리(Recent queries) 탭에서 최근 쿼리의 쿼리 결과를 다운로드할 수 있습니다.

참고

Athena 쿼리 결과 파일은 개별 사용자가 구성할 수 있는 정보가 포함된 데이터 파일입니다. 이 데이터를 읽고 분석하는 일부 프로그램은 해당 데이터의 일부를 명령으로 해석할 가능성이 있습니다(CSV 주입). 이러한 이유로 쿼리 결과 CSV 데이터를 스프레드시트 프로그램으로 가져올 때 해당 프로그램에서 보안 문제에 대한 경고가 표시될 수 있습니다. 시스템을 안전하게 유지하려면 다운로드된 쿼리 결과에서 링크나 매크로를 사용하지 않도록 설정해야 합니다.

쿼리 실행 및 쿼리 결과 다운로드

1. 쿼리 편집기에서 쿼리를 입력한 다음 실행(Run)을 선택합니다.

   쿼리 실행이 완료되면 Results(결과) 창에 쿼리 결과가 표시됩니다.

2. 쿼리 결과의 CSV 파일을 다운로드하려면 쿼리 결과 창 위에서 결과 다운로드(Download results)를 선택합니다. 사용 중인 브라우저 및 브라우저 구성에 따라 다운로드를 확인해야 할 수 있습니다.

   

이전 쿼리에 대한 쿼리 결과 파일을 다운로드하려면

1. 최근 쿼리(Recent queries)를 선택합니다.

   

2. 쿼리 상자를 사용하여 쿼리를 찾고 쿼리를 선택한 다음 결과 다운로드(Download results)를 선택합니다.

   참고

   Download results(결과 다운로드) 옵션을 사용하여 수동으로 삭제된 쿼리 결과를 검색하거나, Amazon S3 수명 주기 규칙에 의해 삭제되었거나 다른 위치로 이동된 쿼리 결과를 검색할 수 없습니다.

   

최근 쿼리 보기

Athena 콘솔을 사용하여 성공 또는 실패한 쿼리를 확인하고 실패한 쿼리에 대한 오류 세부 정보를 볼 수 있습니다. Athena는 45일 동안 쿼리 기록을 보존합니다.

Athena 콘솔에서 최근 쿼리 보기

1. https://console.aws.amazon.com/athena/에서 Athena 콘솔을 엽니다.

2. 최근 쿼리(Recent queries)를 선택합니다. 최근 쿼리(Recent queries) 탭에는 실행된 각 쿼리에 대한 정보가 표시됩니다.

3. 쿼리 편집기에서 쿼리 문을 열려면 쿼리의 실행 ID를 선택합니다.

   

4. 실패한 쿼리에 대한 세부 정보를 보려면 쿼리에 대한 실패(Failed) 링크를 선택합니다.

   

여러 개의 최근 쿼리를 CSV 파일로 다운로드

Athena 콘솔의 Recent queries(최근 쿼리) 탭을 사용하여 하나 이상의 최근 쿼리를 CSV 파일로 내보내 테이블 형식으로 볼 수 있습니다. 다운로드한 파일에는 쿼리 결과가 아니라 SQL 쿼리 문자열 자체와 쿼리에 대한 기타 정보가 들어 있습니다. 내보낸 필드에는 실행 ID, 쿼리 문자열 내용, 쿼리 시작 시간, 상태, 실행 시간, 스캔한 데이터의 양, 사용된 쿼리 엔진 버전 및 암호화 방법이 포함됩니다. 검색 상자에 입력한 조건을 사용하여 최대 500개의 최근 쿼리 또는 필터링된 쿼리를 내보낼 수 있습니다.

하나 이상의 최근 쿼리를 CSV 파일로 내보내려면

1. https://console.aws.amazon.com/athena/에서 Athena 콘솔을 엽니다.

2. 최근 쿼리(Recent queries)를 선택합니다.

3. (선택 사항) 검색 상자를 사용하여 다운로드할 최근 쿼리를 필터링합니다.

4. Download CSV를 선택합니다.

   

5. 파일 저장 프롬프트에서 Save(저장)를 선택합니다. 기본 파일 이름은 Recent Queries이며 뒤에 타임스탬프가 옵니다(예:Recent Queries 2022-12-05T16 04 27.352-08 00.csv)

최근 쿼리 표시 옵션 구성

표시할 열 및 자동 줄 바꿈과 같이 Recent queries(최근 쿼리) 탭에 대한 옵션을 구성할 수 있습니다.

Recent queries(최근 쿼리) 탭에 대한 옵션을 구성하려면

1. https://console.aws.amazon.com/athena/에서 Athena 콘솔을 엽니다.

2. 최근 쿼리(Recent queries)를 선택합니다.

3. 옵션 버튼(기어 모양 아이콘)을 선택합니다.

   

4. 기본 설정(Preferences) 대화 상자에서 페이지당 행 수, 줄 바꿈 동작 및 표시할 열을 선택합니다.

   

5. 확인을 선택합니다.

쿼리 기록을 45일 이상 유지

쿼리 기록을 45일 이상 보존하려면 쿼리 기록을 검색하여 Amazon S3와 같은 데이터 스토어에 저장할 수 있습니다. 이 프로세스를 자동화하려면 Athena 및 Amazon S3 API 작업과 CLI 명령을 사용할 수 있습니다. 다음 절차는 이러한 단계를 요약합니다.

프로그래밍 방식으로 쿼리 기록을 검색하고 저장하려면

1. Athena ListQueryExecutions API 작업 또는 list-query-executions CLI 명령을 사용하여 쿼리 ID를 검색합니다.

2. Athena GetQueryExecution API 작업 또는 get-query-execution CLI 명령을 사용하여 해당 ID를 기반으로 각 쿼리에 대한 정보를 검색합니다.

3. Amazon S3 PutObject API 작업 또는 put-object CLI 명령을 사용하여 Amazon S3에 정보를 저장합니다.

Amazon S3에서 쿼리 출력 파일 찾기

구성이 클라이언트 측 설정을 재정의하는 작업 그룹에서 쿼리가 발생하지 않는 한 쿼리 출력 파일은 다음 경로 패턴으로 Amazon S3의 하위 폴더에 저장됩니다. 작업 그룹 구성이 클라이언트 측 설정을 재정의하는 경우 쿼리는 작업 그룹에서 지정한 결과 경로를 사용합니다.

QueryResultsLocationInS3/[QueryName|Unsaved/yyyy/mm/dd/]

• QueryResultsLocationInS3는 작업 그룹 설정 또는 클라이언트 측 설정에 따라 지정된 쿼리 결과 위치입니다. 자세한 내용은 이 문서의 후반부에서 쿼리 결과 위치 지정 단원을 참조하세요.

• 다음 하위 폴더는 작업 그룹 구성에 의해 결과 경로가 재정의되지 않은 콘솔에서 실행되는 쿼리에 대해서만 생성됩니다. AWS CLI에서 실행되거나 Athena API를 사용하는 쿼리는 QueryResultsLocationInS3에 직접 저장됩니다.

  • QueryName은 결과가 저장되는 쿼리의 이름입니다. 쿼리가 실행되었지만 저장되지 않은 경우 Unsaved가 사용됩니다.

  • yyyy/mm/dd는 쿼리가 실행된 날짜입니다.

CREATE TABLE AS SELECT 쿼리와 연결된 파일은 위 패턴의 tables 하위 폴더에 저장됩니다.

쿼리 출력 파일 식별

파일은 쿼리 이름, 쿼리 ID, 쿼리가 실행된 날짜를 기반으로 Amazon S3의 쿼리 결과 위치에 저장됩니다. 각 쿼리에 대한 파일은 QueryID를 사용하여 이름 지정됩니다. QueryID는 쿼리가 실행될 때 Athena가 각 쿼리에 할당하는 고유 식별자입니다.

다음 파일 형식이 저장됩니다.

파일 유형	파일 이름 지정 패턴	설명
쿼리 결과 파일	QueryID.csv QueryID.txt	DML 쿼리 결과 파일은 CSV(쉼표로 분리된 값) 형식으로 저장됩니다. DDL 쿼리 결과는 일반 텍스트 파일로 저장됩니다. 콘솔을 사용할 경우 콘솔의 결과 창에서 또는 쿼리 기록에서 결과 파일을 다운로드할 수 있습니다. 자세한 내용은 Athena 콘솔을 사용하여 쿼리 결과 파일 다운로드 단원을 참조하세요.
쿼리 메타데이터 파일	QueryID.csv.metadata QueryID.txt.metadata	DML 및 DDL 쿼리 메타데이터 파일은 이진 형식으로 저장되며 사람이 읽을 수 없습니다. 파일 확장명은 관련된 쿼리 결과 파일과 같습니다. Athena는 GetQueryResults 작업을 사용해 쿼리 결과를 읽을 때 메타데이터를 사용합니다. 이러한 파일을 삭제할 수 있지만, 쿼리에 대한 중요한 정보가 손실될 수 있기 때문에 파일을 삭제하지 않는 것이 좋습니다.
데이터 매니페스트 파일	QueryID-manifest.csv	INSERT INTO 쿼리가 실행될 때 Athena가 Amazon S3 데이터 원본 위치에서 생성하는 파일을 추적하기 위해 데이터 매니페스트 파일이 생성됩니다. 쿼리가 실패하는 경우 매니페스트는 해당 쿼리가 작성하려고 한 파일도 추적합니다. 매니페스트는 실패한 쿼리에서 발생하는 분리된 파일을 식별하는 데 유용합니다.

AWS CLI를 사용하여 쿼리 출력 위치 및 파일 식별

AWS CLI를 사용하여 쿼리 출력 위치 및 결과 파일을 식별하려면 다음 예제처럼 aws athena get-query-execution 명령을 실행합니다. abc1234d-5efg-67hi-jklm-89n0op12qr34를 쿼리 ID로 교체합니다.

aws athena get-query-execution --query-execution-id abc1234d-5efg-67hi-jklm-89n0op12qr34

이 명령은 다음과 비슷한 출력을 반환합니다. 각 출력 파라미터에 대한 설명은 AWS CLI 명령 참조의 get-query-execution을 참조하세요.

{
    "QueryExecution": {
        "Status": {
            "SubmissionDateTime": 1565649050.175,
            "State": "SUCCEEDED",
            "CompletionDateTime": 1565649056.6229999
        },
        "Statistics": {
            "DataScannedInBytes": 5944497,
            "DataManifestLocation": "s3://aws-athena-query-results-123456789012-us-west-1/MyInsertQuery/2019/08/12/abc1234d-5efg-67hi-jklm-89n0op12qr34-manifest.csv",
            "EngineExecutionTimeInMillis": 5209
        },
        "ResultConfiguration": {
            "EncryptionConfiguration": {
                "EncryptionOption": "SSE_S3"
            },
            "OutputLocation": "s3://aws-athena-query-results-123456789012-us-west-1/MyInsertQuery/2019/08/12/abc1234d-5efg-67hi-jklm-89n0op12qr34"
        },
        "QueryExecutionId": "abc1234d-5efg-67hi-jklm-89n0op12qr34",
        "QueryExecutionContext": {},
        "Query": "INSERT INTO mydb.elb_log_backup SELECT * FROM mydb.elb_logs LIMIT 100",
        "StatementType": "DML",
        "WorkGroup": "primary"
    }
}