Amazon Athena DocumentDB 커넥터 - Amazon Athena
사전 조건파라미터AWS Glue에서 데이터베이스 및 테이블 설정데이터 형식 지원필수 권한성능패스스루 쿼리추가 리소스

Amazon Athena DocumentDB 커넥터

Amazon Athena DocumentDB 커넥터를 통해 Athena는 DocumentDB와 통신할 수 있고, 이로써 SQL을 사용하여 DocumentDB를 쿼리할 수 있습니다. 커넥터는 MongoDB와 호환되는 모든 엔드포인트과 함께 작동합니다.

기존의 관계형 데이터 스토어와 달리 Amazon DocumentDB 컬렉션에는 설정된 스키마가 없습니다. DocumentDB에는 메타데이터 스토어가 없습니다. DocumentDB 컬렉션의 항목마다 필드와 데이터 형식이 다를 수 있습니다.

DocumentDB 커넥터는 테이블 스키마 정보를 생성하기 위한 두 가지 메커니즘인 기본 스키마 추론과 AWS Glue Data Catalog 메타데이터를 지원합니다.

스키마 추론이 기본값입니다. 이 옵션은 컬렉션에 있는 소수의 문서를 스캔하고, 모든 필드의 통합을 형성하고, 겹치지 않는 데이터 형식을 가진 필드를 강제 변환합니다. 이 옵션은 항목이 대부분 균일한 컬렉션에 적합합니다.

더 다양한 데이터 형식이 있는 컬렉션의 경우 커넥터는 AWS Glue Data Catalog에서 메타데이터 검색을 지원합니다. 커넥터가 DocumentDB 데이터베이스 및 컬렉션 이름과 일치하는 AWS Glue 데이터베이스 및 테이블을 발견하면 해당 AWS Glue 테이블에서 스키마 정보를 가져옵니다. AWS Glue 테이블을 생성할 때 DocumentDB 컬렉션에서 액세스하려는 모든 필드의 상위 세트로 만드는 것이 좋습니다.

계정에서 Lake Formation을 활성화한 경우 AWS Serverless Application Repository에 배포한 Athena 페더레이션형 Lambda 커넥터의 IAM 역할은 Lake Formation에서 AWS Glue Data Catalog에 대한 읽기 액세스 권한을 가지고 있어야 합니다.

사전 조건

파라미터

이 섹션의 Lambda 환경 변수를 사용하여 DocumentDB 커넥터를 구성합니다.

  • spill_bucket – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다.

  • spill_prefix – (선택 사항) 기본값은 athena-federation-spill이라는 지정된 spill_bucket의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 스토리지 수명 주기를 구성하는 것이 좋습니다.

  • spill_put_request_headers – (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: {"x-amz-server-side-encryption" : "AES256"}). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 PutObject를 참조하세요.

  • kms_key_id – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 a7e63k4b-8loc-40db-a2a1-4d0en2cd8331과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다.

  • disable_spill_encryption – (선택 사항) True로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 False입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 서버 측 암호화를 사용하는 경우 성능이 향상될 수 있습니다.

  • disable_glue – (선택 사항) true로 설정된 경우 커넥터는 AWS Glue에서 보충 메타데이터 검색을 시도하지 않습니다.

  • glue_catalog – (선택 사항) 이 옵션을 사용하여 크로스 계정 AWS Glue 카탈로그를 지정합니다. 기본적으로 커넥터는 자체 AWS Glue 계정에서 메타데이터를 가져오려고 시도합니다.

  • default_docdb – 있는 경우 카탈로그 관련 환경 변수가 없을 때 사용할 DocumentDB 연결 문자열을 지정합니다.

  • disable_projection_and_casing – (선택 사항) 프로젝션과 대/소문자를 비활성화합니다. 대/소문자를 구분하는 열 이름을 사용하는 Amazon DocumentDB 테이블을 쿼리하려는 경우에 사용합니다. disable_projection_and_casing 파라미터는 다음 값을 사용하여 대/소문자 및 열 매핑의 동작을 지정합니다.

    • false – 기본 설정입니다. 프로젝션이 활성화되며, 커넥터에서는 모든 열 이름을 소문자로 예상합니다.

    • true - 프로젝션과 대/소문자 구분을 비활성화합니다. disable_projection_and_casing 파라미터를 사용할 때는 다음 사항에 유의하세요.

      • 파라미터를 사용하면 대역폭 사용량이 증가할 수 있습니다. 또한 Lambda 함수가 데이터 소스와 동일한 AWS 리전에 있지 않을 경우 대역폭 사용량이 증가하여 더 높은 표준 AWS 리전 간 전송 비용이 청구됩니다. 리전 간 전송 비용에 대한 자세한 내용은 AWS 파트너 네트워크 블로그의 서버 및 서버리스 아키텍처에 대한 AWS 데이터 전송 요금을 참조하세요.

      • 더 많은 수의 바이트가 전송되고 더 많은 수의 바이트가 더 많은 역직렬화 시간을 필요로 하기 때문에 전체 지연 시간이 늘어날 수 있습니다.

  • enable_case_insensitive_match - (선택 사항) true인 경우 Amazon DocumentDB의 스키마 및 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다. 기본값은 false입니다. 쿼리에 대문자 스키마 또는 테이블 이름이 포함된 경우에 사용합니다.

연결 문자열 지정

커넥터에서 사용하는 DocumentDB 인스턴스에 대한 DocumentDB 연결 세부 정보를 정의하는 속성을 하나 이상 제공할 수 있습니다. 이렇게 하려면 Athena에서 사용하려는 카탈로그 이름에 해당하는 Lambda 환경 변수를 설정합니다. 예를 들어, 다음 쿼리를 사용하여 Athena에서 서로 다른 2개의 DocumentDB 인스턴스를 쿼리하려고 한다고 가정해 보겠습니다.

SELECT * FROM "docdb_instance_1".database.table
SELECT * FROM "docdb_instance_2".database.table

이 두 SQL 문을 사용하려면 먼저 2개의 환경 변수 docdb_instance_1과 docdb_instance_2를 Lambda 함수에 추가해야 합니다. 각 값은 다음 형식의 DocumentDB 연결 문자열이어야 합니다.

mongodb://:@:/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0

보안 암호 사용

필요에 따라 연결 문자열 세부 정보 값의 일부 또는 전체에 대해 AWS Secrets Manager를 사용할 수 있습니다. Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 인터넷 액세스 또는 VPC 엔드포인트가 Lambda 함수에 연결된 VPC에 있어야 합니다.

${my_secret} 구문을 사용하여 연결 문자열에 Secrets Manager의 보안 암호 이름을 입력하는 경우 커넥터는 ${my_secret}을 Secrets Manager의 일반 텍스트 값으로 정확하게 바꿉니다. 보안 암호는 <username>:<password> 값을 가진 일반 텍스트 보안 암호로 저장되어야 합니다 {username:<username>,password:<password>}로 저장된 보안 암호는 연결 문자열에 제대로 전달되지 않습니다.

전체 연결 문자열에도 보안 암호를 사용할 수 있으며 보안 암호 내에서 사용자 이름과 암호를 정의할 수 있습니다.

예를 들어, docdb_instance_1에 대한 Lambda 환경 변수를 다음 값으로 설정했다고 가정해 보겠습니다.

mongodb://${docdb_instance_1_creds}@myhostname.com:123/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0

Athena Query Federation SDK는 자동으로 Secrets Manager에서 docdb_instance_1_creds라는 보안 암호를 검색하고 ${docdb_instance_1_creds} 대신 해당 값을 삽입하려고 시도합니다. ${ } 문자 조합으로 묶은 연결 문자열 부분은 Secrets Manager의 보안 암호로 해석됩니다. 커넥터가 Secrets Manager에서 찾을 수 없는 보안 암호 이름을 지정하면 커넥터가 텍스트를 바꾸지 않습니다.

AWS Glue에서 데이터베이스 및 테이블 설정

커넥터의 기본 제공 스키마 추론 기능은 제한된 수의 문서를 스캔하고 데이터 형식의 하위 세트만 지원하므로 메타데이터에 AWS Glue를 대신 사용할 수 있습니다.

Amazon DocumentDB에서 사용할 AWS Glue 테이블을 활성화하려면 보충 메타데이터를 제공할 DocumentDB 데이터베이스 및 컬렉션에 대한 AWS Glue 데이터베이스와 테이블이 있어야 합니다.

보충 메타데이터에 AWS Glue 테이블 사용

  1. AWS Glue 콘솔을 사용하여 Amazon DocumentDB 데이터베이스 이름과 동일한 이름으로 AWS Glue 데이터베이스를 생성할 수 있습니다.

  2. docdb-metadata-flag를 포함하도록 데이터베이스의 URI 속성을 설정합니다.

  3. (선택 사항) sourceTable 테이블 속성을 추가합니다. 이 속성에 따라 Amazon DocumentDB의 소스 테이블 이름이 정의됩니다. AWS Glue 테이블의 이름이 Amazon DocumentDB의 테이블 이름과 다른 경우 이 속성을 사용합니다. AWS Glue와 Amazon DocumentDB 간의 이름 지정 규칙 차이 때문에 이 작업이 필요할 수 있습니다. 예를 들어, AWS Glue 테이블 이름에는 대문자가 허용되지 않지만 Amazon DocumentDB 테이블 이름에는 대문자가 허용됩니다.

  4. (선택 사항) columnMapping 테이블 속성을 추가합니다. 이 속성은 열 이름 매핑을 정의합니다. AWS Glue 열 이름 지정 규칙으로 인해 Amazon DocumentDB 테이블의 열과 동일한 열 이름으로 AWS Glue 테이블을 생성할 수 없는 경우 이 속성을 사용합니다. Amazon DocumentDB 열 이름에는 대문자가 허용되지만 AWS Glue 열 이름에는 대문자가 허용되지 않기 때문에 이 방법이 유용할 수 있습니다.

    columnMapping 속성 값은 col1=Col1,col2=Col2 형식의 매핑 세트여야 합니다.

    참고

    열 매핑은 상위 열 이름에만 적용되고 중첩된 필드에는 적용되지 않습니다.

    AWS Glue columnMapping 테이블 속성을 추가한 후 disable_projection_and_casing Lambda 환경 변수를 제거할 수 있습니다.

  5. 이 문서에 나열된 대로 AWS Glue에 적합한 데이터 형식을 사용해야 합니다.

데이터 형식 지원

이 섹션에는 DocumentDB 커넥터가 스키마 추론에 사용하는 데이터 형식과 AWS Glue 메타데이터가 사용될 때의 데이터 형식이 나열되어 있습니다.

스키마 추론 데이터 형식

DocumentDB 커넥터의 스키마 추론 기능은 값을 다음 데이터 형식 중 하나에 속하는 것으로 추정하려고 시도합니다. 다음 표에는 Amazon DocumentDB, Java 및 Apache Arrow에 해당하는 데이터 형식이 나와 있습니다.

Apache Arrow Java 또는 DocDB
VARCHAR String
INT Integer
BIGINT Long
BIT 불
FLOAT4 Float
FLOAT8 Double
TIMESTAMPSEC 날짜
VARCHAR ObjectId
LIST 나열
STRUCT 문서

AWS Glue 데이터 유형

보충 메타데이터에 AWS Glue를 사용하는 경우 다음 데이터 형식을 구성할 수 있습니다. 다음 표에는 AWS Glue와 Apache Arrow의 해당 데이터 형식이 나와 있습니다.

AWS Glue Apache Arrow
int INT
bigint BIGINT
double FLOAT8
float FLOAT4
boolean BIT
이진수 VARBINARY
문자열 VARCHAR
나열 LIST
구조체 STRUCT

필수 권한

이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 athena-docdb.yaml 파일의 Policies 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다.

  • Amazon S3 쓰기 액세스 - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다.

  • Athena GetQueryExecution - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다.

  • AWS Glue Data Catalog - 스키마 정보를 가져오기 위해 DocumentDB 커넥터에 AWS Glue Data Catalog에 대한 읽기 전용 액세스 권한이 필요합니다.

  • CloudWatch Logs - 로그를 저장하기 위해 커넥터 CloudWatch Logs에 대한 액세스 권한이 필요합니다.

  • AWS Secrets Manager 읽기 액세스 - Secrets Manager에 DocumentDB 엔드포인트 세부 정보를 저장하기로 선택하는 경우, 커넥터에 해당 보안 암호에 대한 액세스 권한을 부여해야 합니다.

  • VPC 액세스 - VPC에 연결하고 DocumentDB 인스턴스와 통신할 수 있도록 VPC에 인터페이스를 연결하고 분리하는 기능이 커넥터에 필요합니다.

성능

Athena Amazon DocumentDB 커넥터는 현재 병렬 스캔을 지원하지 않지만 DocumentDB 쿼리의 일부로 조건자 푸시다운을 시도하고, DocumentDB 컬렉션의 인덱스에 대한 조건자로 인해 스캔되는 데이터가 크게 감소합니다.

쿼리에서 스캔된는 데이터를 줄이기 위해 Lambda 함수에서 조건자 푸시다운을 수행합니다. 그러나 열의 하위 세트를 선택하면 쿼리 실행 런타임이 길어지는 경우가 있습니다. LIMIT 절은 스캔되는 데이터의 양을 줄이지만 조건자를 제공하지 않으면 LIMIT 절을 포함하는 SELECT 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다.

패스스루 쿼리

Athena Amazon DocumentDB 커넥터는 패스스루 쿼리를 지원하며 NoSQL 기반입니다. Amazon DocumentDB 쿼리에 대한 자세한 내용은 Amazon DocumentDB 개발자 가이드의 쿼리를 참조하세요.

Amazon DocumentDB에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다.

SELECT * FROM TABLE(
        system.query(
            database => 'database_name',
            collection => 'collection_name',
            filter => '{query_syntax}'
        ))

다음 예제 쿼리는 TPCDS 컬렉션 내에서 example 데이터베이스를 쿼리하여 제목이 Bill of Rights인 모든 책을 필터링합니다.

SELECT * FROM TABLE(
        system.query(
            database => 'example',
            collection => 'tpcds',
            filter => '{title: "Bill of Rights"}'
        ))

추가 리소스