# 데이터 원본에 연결 Amazon Athena를 사용하여 *데이터 세트*의 다른 위치 및 형식으로 저장된 데이터를 쿼리할 수 있습니다. 이 데이터 세트는 CSV, JSON, Avro, Parquet 또는 기타 형식일 수 있습니다. 쿼리를 실행하기 위해 Athena에서 작업하는 테이블과 데이터베이스는 *메타데이터*를 기반으로 합니다. 메타데이터는 데이터 세트의 기본 데이터에 대한 데이터입니다. 해당 메타데이터가 데이터 세트를 설명하는 방법을 *스키마*라고 합니다. 예를 들어 테이블 이름, 테이블의 열 이름 및 각 열의 데이터 유형은 기본 데이터 세트를 설명하는 메타데이터로 저장된 스키마입니다. Athena에서 사용자는 메타데이터를 *데이터 카탈로그* 또는 *메타스토어*로 구성하기 위한 시스템을 호출합니다. 데이터 세트와 이를 설명하는 데이터 카탈로그의 조합을 *데이터 원본*이라고 합니다. 메타데이터와 기본 데이터 세트의 관계는 작업하는 데이터 원본 유형에 따라 달라집니다. MySQL, PostgreSQL, SQL Server와 같은 관계형 데이터 원본은 데이터 세트와 메타데이터를 밀접하게 통합합니다. 이러한 시스템에서는 데이터가 작성될 때 메타데이터가 가장 자주 작성됩니다. [Hive](https://hive.apache.org)를 사용하여 구축된 것과 같은 다른 데이터 원본을 사용하면 데이터 세트를 읽을 때 즉석에서 메타데이터를 정의할 수 있습니다. 데이터 세트는 예를 들어 CSV, JSON, Parquet 또는 Avro처럼 다양한 형식일 수 있습니다. Athena는 기본적으로 AWS Glue Data Catalog를 지원합니다. AWS Glue Data Catalog는 Amazon S3, Amazon Redshift, Amazon DynamoDB 등의 다른 데이터 세트 및 데이터 원본을 바탕으로 구축된 데이터 카탈로그입니다. 다양한 커넥터를 사용하여 Athena를 다른 데이터 원본에 연결할 수도 있습니다. **Topics** + [AWS Glue Data Catalog을 사용하여 데이터에 연결](data-sources-glue.md) + [Amazon Athena 페더레이션 쿼리 사용](federated-queries.md) + [Athena에서 Amazon DataZone 사용](datazone-using.md) + [외부 Hive 메타스토어 사용](connect-to-data-source-hive.md) + [데이터 소스 관리](data-sources-managing.md) # AWS Glue Data Catalog을 사용하여 데이터에 연결 Athena는 AWS Glue Data Catalog를 사용해 Amazon S3에 저장된 데이터에 대한 테이블 및 열 이름과 같은 메타데이터를 저장할 수 있습니다. 이 메타데이터 정보는 Athena의 쿼리 편집기에 표시되는 데이터베이스, 테이블 및 뷰가 됩니다. AWS Glue Data Catalog와 함께 Athena를 사용하는 경우 AWS Glue를 사용하여 Athena에서 쿼리할 데이터베이스와 테이블(스키마)을 생성하거나, Athena를 사용하여 스키마를 생성한 후 AWS Glue 및 관련 서비스에서 사용할 수 있습니다. AWS Glue에 대한 스키마 정보를 정의하려면 Athena 콘솔에서 양식을 사용하거나, Athena의 쿼리 편집기를 사용하거나, AWS Glue 콘솔에서 AWS Glue 크롤러를 생성할 수 있습니다. AWS Glue 크롤러는 Amazon S3의 데이터로부터 데이터베이스 및 테이블 스키마를 자동으로 추론합니다. 양식을 사용하면 더 많은 사용자 지정이 가능합니다. 직접 `CREATE TABLE` 문을 작성하려면 더 많은 노력이 필요하지만 가장 잘 제어할 수 있습니다. 자세한 내용은 [CREATE TABLE](create-table.md) 섹션을 참조하세요. ## 추가 리소스 + AWS Glue Data Catalog에 대한 자세한 내용은 *AWS Glue 개발자 안내서*의 [AWS Glue의 데이터 카탈로그 및 크롤러](https://docs.aws.amazon.com/glue/latest/dg/catalog-and-crawler.html)를 참조하세요. + AWS Glue와 Athena를 사용하여 XML 데이터를 처리하는 방법을 보여주는 설명 문서는 AWS 빅 데이터 블로그의 [Process and analyze highly nested and large XML files using AWS Glue and Amazon Athena](https://aws.amazon.com/blogs/big-data/process-and-analyze-highly-nested-and-large-xml-files-using-aws-glue-and-amazon-athena/)를 참조하세요. + AWS Glue에는 별도 요금이 적용됩니다. 자세한 내용은 [AWS Glue 요금](https://aws.amazon.com/glue/pricing)을 참조하십시오. **Topics** + [추가 리소스](#glue-additional-resources) + [Athena에 데이터 카탈로그 등록 및 사용](gdc-register.md) + [다른 계정의 데이터 카탈로그 등록](data-sources-glue-cross-account.md) + [IAM 정책으로 데이터 카탈로그에 대한 액세스 제어](datacatalogs-iam-policy.md) + [Athena 콘솔의 양식을 사용하여 AWS Glue 테이블 추가](data-sources-glue-manual-table.md) + [크롤러를 사용하여 테이블 추가](schema-crawlers.md) + [AWS Glue 파티션 인덱싱 및 필터링을 통한 쿼리 최적화](glue-best-practices-partition-index.md) + [AWS CLI를 사용하여 AWS Glue 데이터베이스 및 해당 테이블 다시 생성](glue-recreate-db-and-tables-cli.md) + [ETL 작업용 테이블 생성](schema-classifier.md) + [AWS Glue에서 CSV 데이터로 작업](schema-csv.md) + [AWS Glue에서 지리 공간 데이터 작업](schema-geospatial.md) # Athena에 데이터 카탈로그 등록 및 사용 Athena는 여러 데이터 카탈로그에 대한 탑재 및 연결을 지원합니다. + 데이터를 복사하거나 이동할 필요 없이 AWS Glue Data Catalog에 Amazon Redshift 데이터를 탑재하고 Athena에서 쿼리할 수 있습니다. 자세한 내용은 [Amazon Redshift 데이터를 AWS Glue Data Catalog으로 가져오기](https://docs.aws.amazon.com/lake-formation/latest/dg/managing-namespaces-datacatalog.html)를 참조하세요. + AWS Glue 연결을 사용하여 AWS Glue Data Catalog을 외부 데이터 소스에 연결하고, 페더레이션 카탈로그를 생성하여 Lake Formation을 사용하고 세분화된 액세스 제어를 통해 데이터에 대한 권한을 중앙에서 관리합니다. 자세한 내용은 [연결을 Glue 데이터 카탈로그로 등록](register-connection-as-gdc.md) 섹션을 참조하세요. + Amazon S3 테이블 버킷에서 카탈로그를 생성하고, Lake Formation을 사용하여 액세스 권한을 중앙에서 관리하고 테이블 버킷 내의 객체에 대한 사용자 액세스를 제한합니다. 자세한 내용은 Amazon S3 사용자 안내서의 [Amazon S3 Tables 및 테이블 버킷 작업](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables.html)을 참조하세요. **참고** Glue 카탈로그의 경우 `123412341234:my_catalog/my_child`와 같은 다중 수준 카탈로그만 등록할 수 있습니다. `123412341234:linkcontainer` 또는 `my_catalog`과 같은 단일 수준 카탈로그는 등록할 수 없습니다. 단일 수준 카탈로그는 Athena 쿼리에서 Glue 데이터 카탈로그를 직접 사용해야만 쿼리할 수 있습니다. 자세한 내용은 [Athena에서 AWS Glue 데이터 카탈로그 쿼리](gdc-register-query-the-data-source.md) 섹션을 참조하세요. **Topics** + [Athena에 Redshift 데이터 카탈로그 등록](gdc-register-rs.md) + [Athena에 페더레이션 카탈로그 등록](gdc-register-federated.md) + [Athena에서 S3 테이블 버킷 카탈로그 등록 및 테이블 쿼리](gdc-register-s3-table-bucket-cat.md) + [Athena에서 AWS Glue 데이터 카탈로그 쿼리](gdc-register-query-the-data-source.md) # Athena에 Redshift 데이터 카탈로그 등록 Athena는 Redshift 클러스터 또는 AWS Glue Data Catalog에 등록된 서버리스 네임스페이스에 저장된 데이터를 읽고 쓸 수 있습니다. 이는 중앙 집중식 보안 및 거버넌스를 제공하는 AWS Lake Formation과 함께 작동하여 여러 쿼리 엔진에서 데이터 액세스를 일관되게 관리하고 공유 Redshift 데이터에 대한 세분화된 액세스 제어를 유지합니다. ## 고려 사항 및 제한 사항 + **구체화된 뷰** - Amazon Redshift 구체화된 뷰는 Athena에서 쿼리할 수 있지만 Athena 또는 Spark를 사용하여 구체화된 뷰를 생성하는 것은 지원되지 않습니다. + Amazon Redshift 관리형 스토리지 테이블에 대한 AWS Glue Data Catalog 구성 및 작업 설정을 포함한 DDL 작업은 지원되지 않습니다. ## 사전 조건 Athena에서 AWS Glue 데이터 카탈로그를 쿼리하려면 먼저 다음 작업을 완료합니다. 1. Amazon Redshift 클러스터 또는 서버리스 네임스페이스를 생성하고 AWS Glue Data Catalog에 등록합니다. 자세한 내용은 Amazon Redshift 관리 안내서의 [AWS Glue Data Catalog에 클러스터 등록](https://docs.aws.amazon.com/redshift/latest/mgmt/register-cluster.html) 또는 [AWS Glue Data Catalog에 네임스페이스 등록](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless_datasharing-register-namespace.html)을 참조하세요. 1. 등록된 네임스페이스에서 AWS Lake Formation에 데이터 카탈로그를 생성합니다. 자세한 내용은 AWS Lake Formation 개발자 안내서의 [Amazon Redshift 페더레이션 카탈로그 생성](https://docs.aws.amazon.com/lake-formation/latest/dg/create-ns-catalog.html)을 참조하세요. 1. (선택 사항) Lake Formation을 사용하여 카탈로그에서 세분화된 액세스 제어를 설정합니다. 자세한 내용은 AWS Lake Formation 개발자 안내서의 [AWS Glue Data Catalog으로 데이터 가져오기](https://docs.aws.amazon.com/lake-formation/latest/dg/bring-your-data-overview.html)를 참조하세요. ## Athena 콘솔에 Redshift 데이터 카탈로그 등록 Athena 콘솔에 Redshift 데이터 카탈로그를 등록하려면 다음 단계를 수행합니다. 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/)에서 Athena 콘솔을 엽니다. 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 **데이터 소스 생성**을 선택합니다. 1. **데이터 소스 선택**에서 **Amazon S3 - AWS Glue Data Catalog**을 선택합니다. 1. **AWS Glue Data Catalog** 섹션의 **데이터 소스 계정**에서 **이 계정의 AWS Glue Data Catalog**을 선택합니다. 1. **테이블 생성 또는 카탈로그 등록**에서 **새 AWS Glue 카탈로그 등록**을 선택합니다. 1. **데이터 소스 세부 정보** 섹션의 **데이터 소스 이름**에 SQL 쿼리에서 데이터 소스를 지정하는 데 사용할 이름을 입력하거나 생성된 기본 이름을 사용합니다. 1. **카탈로그**에서 **찾아보기**를 선택하여 동일한 계정의 AWS Glue 카탈로그 목록을 검색합니다. 기존 카탈로그가 보이지 않는 경우 [AWS Glue 콘솔](https://console.aws.amazon.com/glue/)에서 카탈로그를 생성합니다. 1. **AWS Glue 카탈로그 찾아보기** 대화 상자에서 사용할 카탈로그를 선택한 다음 **선택하기**를 선택합니다. 1. (선택 사항) **태그**에 데이터 소스와 연결할 키/값 페어를 입력합니다. 1. **다음**을 선택합니다. 1. **검토 및 생성** 페이지에서 입력한 정보가 정확한지 확인한 다음 **데이터 소스 생성**을 선택합니다. # Athena에 페더레이션 카탈로그 등록 페더레이션된 데이터 소스에 대한 연결을 생성한 후 페더레이션된 데이터 카탈로그로 등록하여 데이터 검색을 간소화하고, Lake Formation을 사용하여 세분화된 권한으로 데이터 액세스를 관리할 수 있습니다. 자세한 내용은 [연결을 Glue 데이터 카탈로그로 등록](register-connection-as-gdc.md) 섹션을 참조하세요. ## 고려 사항 및 제한 사항 + DDL 작업은 페더레이션 카탈로그에서 지원되지 않습니다. + 다음 커넥터를 등록하여 AWS Glue와 통합하고 세분화된 액세스 제어를 수행할 수 있습니다. + [Azure Data Lake Storage](connectors-adls-gen2.md) + [Azure Synapse](connectors-azure-synapse.md) + [BigQuery](connectors-bigquery.md) + [CMDB](connectors-cmdb.md) + [Db2](connectors-ibm-db2.md) + [Db2 iSeries](connectors-ibm-db2-as400.md) + [documentdb](connectors-docdb.md) + [DynamoDB](connectors-dynamodb.md) + [Google Cloud Storage](connectors-gcs.md) + [HBase](connectors-hbase.md) + [MySQL](connectors-mysql.md) + [OpenSearch](connectors-opensearch.md) + [Oracle](connectors-oracle.md) + [PostgreSQL](connectors-postgresql.md) + [Redshift](connectors-redshift.md) + [SAP HANA](connectors-sap-hana.md) + [Snowflake](connectors-snowflake.md) + [SQL Server](connectors-microsoft-sql-server.md) + [Timestream](connectors-timestream.md) + [TPC-DS](connectors-tpcds.md) + Glue 연결 페더레이션을 위한 리소스 링크를 생성할 때 [리소스 링크](https://docs.aws.amazon.com/lake-formation/latest/dg/create-resource-link-database.html)의 이름은 생산자의 데이터베이스 이름과 동일해야 합니다. + 현재는 데이터 소스가 대소문자를 구분하지 않더라도 소문자 테이블 및 열 이름만 인식됩니다. # Athena에서 S3 테이블 버킷 카탈로그 등록 및 테이블 쿼리 S3 테이블 버킷은 Apache Iceberg 테이블에 테이블 형식 데이터를 저장하기 위해 특별히 구축된 Amazon S3의 버킷 유형입니다. 테이블 버킷은 압축, 스냅샷 관리, 폐영역 회수와 같은 테이블 관리 작업을 자동화하여 쿼리 성능을 지속적으로 최적화하고 비용을 최소화합니다. 이제 막 시작하는 단계이든 Iceberg 환경에 수천 개의 테이블이 있든, 테이블 버킷은 모든 규모에서 데이터 레이크를 단순화합니다. 자세한 내용은 [테이블 버킷](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets.html)을 참조하세요. ## 고려 사항 및 제한 사항 + Iceberg 테이블에서 지원되는 모든 DDL 작업은 S3 테이블에서 지원되지만 다음과 같은 예외가 있습니다. + `ALTER TABLE RENAME`, `CREATE VIEW`, `ALTER DATABASE`는 지원되지 않습니다. + `OPTIMIZE` 및 `VACUUM` - S3에서 압축 및 스냅샷 관리를 관리할 수 있습니다. 자세한 내용은 [S3 Tables 유지 관리 설명서](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-maintenance.html)를 참조하세요. + Athena 데이터 소스로 등록된 S3 Tables의 DDL 쿼리는 지원되지 않습니다. + 쿼리 결과 재사용은 지원되지 않습니다. + SSE-KMS, CSE KMS 암호화가 활성화된 작업 그룹에서는 S3 Tables에서 `INSERT`, `UPDATE`, `DELETE` 또는 `MERGE` 같은 쓰기 작업을 실행할 수 없습니다. + S3 요청자 지불 옵션이 활성화된 작업 그룹에서는 S3 Tables에서 DML 작업을 실행할 수 없습니다. ## Athena에서 S3 Tables 쿼리 **Athena에서 S3 Tables를 쿼리하기 전에 다음 사전 조건 단계 완료** 1. S3 테이블 버킷을 생성합니다. 자세한 내용은 Amazon Simple Storage Service 사용 설명서의 [테이블 버킷 생성](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets-create.html)을 참조하세요. 1. 테이블 버킷과 AWS Glue Data Catalog의 통합이 성공적으로 완료되었는지 확인하세요. 필요한 권한 및 설정 단계는 AWS Glue 개발자 안내서의 [S3 Tables 통합에 대한 사전 조건](https://docs.aws.amazon.com/glue/latest/dg/s3tables-catalog-prerequisites.html)과 [Glue Data Catalog와 S3 Tables 통합 활성화](https://docs.aws.amazon.com/glue/latest/dg/enable-s3-tables-catalog-integration.html)를 참조하세요. 1. Athena를 사용하여 쿼리를 실행하는 데 사용하는 위탁자에 대해 다음 방법 중 하나를 사용하여 S3 테이블 카탈로그에 대한 권한을 부여하세요. **옵션 1: IAM 권한 사용** IAM 액세스 제어를 사용하는 경우 위탁자는 AWS Glue Data Catalog 리소스와 Amazon S3 Tables 리소스 모두에 대한 권한이 필요합니다. 다음 목록에는 Athena에서 S3 Tables에 대해 지원되는 DDL 또는 DML 작업을 수행하는 데 필요한 모든 `s3tables` 권한이 포함되어 있습니다. + `s3tables:GetTableBucket` + `s3tables:GetNamespace` + `s3tables:GetTable` + `s3tables:GetTableData` + `s3tables:PutTableData` + `s3tables:ListNamespaces` + `s3tables:ListTables` + `s3tables:DeleteNamespace` + `s3tables:DeleteTable` + `s3tables:CreateNamespace` + `s3tables:CreateTable` + `s3tables:UpdateTableMetadataLocation` 특정 S3 테이블 버킷과 S3 테이블 리소스에 이러한 권한을 적용하거나 리소스로 `*`를 사용하여 계정의 모든 테이블 버킷과 테이블에 대한 액세스 권한을 부여할 수 있습니다. 이러한 권한을 [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html) 관리형 정책과 결합하여 모든 기능을 활성화할 수 있습니다. **옵션 2: Lake Formation 권한 사용** 또는 세분화된 액세스 제어를 활성화하려면 Lake Formation 콘솔이나 AWS CLI를 통해 S3 테이블 카탈로그에 대한 Lake Formation 권한을 부여할 수 있습니다. 이를 위해서는 S3 테이블 버킷을 Lake Formation 데이터 위치로 등록해야 합니다. 자세한 내용은 Lake Formation 개발자 안내서의 [AWS Glue Data Catalog에서 Amazon S3 Tables 카탈로그 생성](https://docs.aws.amazon.com/lake-formation/latest/dg/create-s3-tables-catalog.html)을 참조하세요. ------ #### [ AWS Management Console ] 1. [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/)에서 AWS Lake Formation 콘솔을 열고 데이터 레이크 관리자로 로그인합니다. 데이터 레이크 관리자 생성 방법에 대한 자세한 내용은 [데이터 레이크 관리자 생성](https://docs.aws.amazon.com/lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)을 참조하세요. 1. 탐색 창에서 **데이터 권한**을 선택한 다음 **권한 부여**를 선택합니다. 1. **권한 부여** 페이지의 **보안 주체**에서 Athena에서 쿼리를 제출하는 데 사용할 보안 주체를 선택합니다. 1. **LF 태그 또는 카탈로그 리소스**에서 **명명된 데이터 카탈로그 리소스**를 선택합니다. 1. **카탈로그**에서 테이블 버킷의 통합에서 생성한 글루 데이터 카탈로그를 선택합니다. 예: **:s3tablescatalog/*amzn-s3-demo-bucket* 1. **카탈로그 권한**에서 **슈퍼**를 선택합니다. 1. **권한 부여**를 선택합니다. ------ #### [ AWS CLI ] Lake Formation 데이터 레이크 관리자 역할을 사용하여 다음 명령을 실행하여 Athena에서 쿼리를 제출하는 데 사용하는 위탁자에 대한 액세스 권한을 부여합니다. ``` aws lakeformation grant-permissions \ --region \ --cli-input-json \ '{ "Principal": { "DataLakePrincipalIdentifier": ":role/ExampleRole>" }, "Resource": { "Catalog": { "Id":":s3tablescatalog/amzn-s3-demo-bucket" } }, "Permissions": ["ALL"] }' ``` ------ **S3 Tables에 대한 쿼리 제출** 1. 위의 부여된 사용자/역할을 사용하여 Athena에서 `CREATE DATABASE` 쿼리를 제출합니다. 이 예제에서 `s3tablescatalog`는 통합에서 생성된 상위 Glue Data Catalog이며, ` s3tablescatalog/amzn-s3-demo-bucket`는 각 S3 테이블 버킷에 대해 생성된 하위 Glue Data Catalog입니다. 쿼리하는 두 가지 방법이 있습니다. ------ #### [ Option 1 ] 콘솔 또는 AWS CLI에서 직접 하위 Glue Data Catalog(`s3tablescatalog/amzn-s3-demo-bucket`)를 지정합니다. **AWS Management Console 사용** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/)에서 Athena 콘솔을 엽니다. 1. 왼쪽 탐색 창의 **데이터 소스 이름**에서 **AwsDataCatalog**를 선택합니다. 1. **카탈로그**에서 **s3tablescatalog/*amzn-s3-demo-bucket***을 선택합니다. 1. 쿼리 편집기에 `CREATE DATABASE test_namespace`와 같은 쿼리를 입력합니다. **AWS CLI 사용** 다음 명령을 실행합니다. ``` aws athena start-query-execution \ --query-string 'CREATE DATABASE `test_namespace`' \ --query-execution-context '{"Catalog": "s3tablescatalog/amzn-s3-demo-bucket"}' \ --work-group "primary" ``` ------ #### [ Option 2 ] Athena 콘솔의 하위 Glue Data Catalog에서 Athena 데이터 카탈로그를 생성하고 쿼리에서 카탈로그로 지정합니다. 자세한 내용은 [S3 테이블 버킷 카탈로그를 Athena 데이터 소스로 등록](#gdc-register-s3-table-console-steps) 섹션을 참조하세요. ------ 1. 이전 단계에서 생성한 데이터베이스로 `CREATE TABLE`를 사용하여 테이블을 생성합니다. 다음 예제는 `s3tablescatalog/amzn-s3-demo-bucket` Glue 카탈로그에서 이전에 생성한 *`test_namespace`* 데이터베이스에 테이블을 생성합니다. ------ #### [ AWS Management Console ] 1. 왼쪽 탐색 창의 **데이터 소스 이름**에서 **AwsDataCatalog**를 선택합니다. 1. **카탈로그**에서 **s3tablescatalog/*amzn-s3-demo-bucket***을 선택합니다. 1. **데이터베이스**에서 **test\$1namespace**를 선택합니다. 1. 쿼리 편집기에서 다음 쿼리를 실행합니다. ``` CREATE TABLE daily_sales ( sale_date date, product_category string, sales_amount double) PARTITIONED BY (month(sale_date)) TBLPROPERTIES ('table_type' = 'iceberg') ``` ------ #### [ AWS CLI ] 다음 명령을 실행합니다. ``` aws athena start-query-execution \ --query-string "CREATE TABLE daily_sales ( sale_date date, product_category string, sales_amount double) PARTITIONED BY (month(sale_date)) TBLPROPERTIES ('table_type' = 'iceberg')" \ --query-execution-context '{"Catalog": "s3tablescatalog/amzn-s3-demo-bucket", "Database":"test_namespace"}' \ --work-group "primary" ``` ------ 1. 이전 단계에서 생성한 테이블에 데이터를 삽입합니다. ------ #### [ AWS Management Console ] 1. 왼쪽 탐색 창의 **데이터 소스 이름**에서 **AwsDataCatalog**를 선택합니다. 1. **카탈로그**에서 **s3tablescatalog/*amzn-s3-demo-bucket***을 선택합니다. 1. **데이터베이스**에서 **test\$1namespace**를 선택합니다. 1. 쿼리 편집기에서 다음 쿼리를 실행합니다. ``` INSERT INTO daily_sales VALUES (DATE '2024-01-15', 'Laptop', 900.00), (DATE '2024-01-15', 'Monitor', 250.00), (DATE '2024-01-16', 'Laptop', 1350.00), (DATE '2024-02-01', 'Monitor', 300.00); ``` ------ #### [ AWS CLI ] 다음 명령을 실행합니다. ``` aws athena start-query-execution \ --query-string "INSERT INTO \"s3tablescatalog/amzn-s3-demo-bucket\".test_namespace.daily_sales VALUES (DATE '2024-01-15', 'Laptop', 900.00), (DATE '2024-01-15', 'Monitor', 250.00), (DATE '2024-01-16', 'Laptop', 1350.00), (DATE '2024-02-01', 'Monitor', 300.00)"\ --work-group "primary" ``` ------ 1. 테이블에 데이터를 삽입한 후 데이터를 쿼리할 수 있습니다. ------ #### [ AWS Management Console ] 1. 왼쪽 탐색 창의 **데이터 소스 이름**에서 **AwsDataCatalog**를 선택합니다. 1. **카탈로그**에서 **s3tablescatalog/*amzn-s3-demo-bucket***을 선택합니다. 1. **데이터베이스**에서 **test\$1namespace**를 선택합니다. 1. 쿼리 편집기에서 다음 쿼리를 실행합니다. ``` SELECT product_category, COUNT(*) AS units_sold, SUM(sales_amount) AS total_revenue, AVG(sales_amount) AS average_price FROM daily_sales WHERE sale_date BETWEEN DATE '2024-02-01' AND DATE '2024-02-29' GROUP BY product_category ORDER BY total_revenue DESC ``` ------ #### [ AWS CLI ] 다음 명령을 실행합니다. ``` aws athena start-query-execution \ --query-string "SELECT product_category, COUNT(*) AS units_sold, SUM(sales_amount) AS total_revenue, AVG(sales_amount) AS average_price FROM \"s3tablescatalog/amzn-s3-demo-bucket\".test_namespace.daily_sales WHERE sale_date BETWEEN DATE '2024-02-01' AND DATE '2024-02-29' GROUP BY product_category ORDER BY total_revenue DESC"\ --work-group "primary" ``` ------ ## Athena에서 S3 Tables 생성 Athena는 `CREATE DATABASE` 문을 사용하여 Athena에서 생성된 기존 S3 테이블 네임스페이스 또는 네임스페이스에서 테이블 생성을 지원합니다. Athena에서 S3 테이블을 생성하려면 다음 예제와 같이 `LOCATION`을 지정하지 않는다는 점을 제외하고 [일반 Iceberg 테이블을 생성](querying-iceberg-creating-tables.md)할 때와 구문이 동일합니다. ``` CREATE TABLE [db_name.]table_name (col_name data_type [COMMENT col_comment] [, ...] ) [PARTITIONED BY (col_name | transform, ... )] [TBLPROPERTIES ([, property_name=property_value] )] ``` CREATE TABLE AS SELECT(CTAS) 문을 사용하여 S3 Table을 생성할 수도 있습니다. 자세한 내용은 [S3 Table용 CTAS](#ctas-s3-tables) 섹션을 참조하세요. ## S3 테이블 버킷 카탈로그를 Athena 데이터 소스로 등록 Athena 콘솔에 S3 테이블 버킷 카탈로그를 등록하려면 다음 단계를 수행합니다. 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/)에서 Athena 콘솔을 엽니다. 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 **데이터 소스 생성**을 선택합니다. 1. **데이터 소스 선택**에서 **Amazon S3 - AWS Glue Data Catalog**을 선택합니다. 1. **AWS Glue Data Catalog** 섹션의 **데이터 소스 계정**에서 **이 계정의 AWS Glue Data Catalog**을 선택합니다. 1. **테이블 생성 또는 카탈로그 등록**에서 **새 AWS Glue 카탈로그 등록**을 선택합니다. 1. **데이터 소스 세부 정보** 섹션의 **데이터 소스 이름**에 SQL 쿼리에서 데이터 소스를 지정하는 데 사용할 이름을 입력하거나 생성된 기본 이름을 사용합니다. 1. **카탈로그**에서 **찾아보기**를 선택하여 동일한 계정의 AWS Glue 카탈로그 목록을 검색합니다. 기존 카탈로그가 보이지 않는 경우 [AWS Glue 콘솔](https://console.aws.amazon.com/glue/)에서 카탈로그를 생성합니다. 1. **AWS Glue 카탈로그 찾아보기** 대화 상자에서 사용할 카탈로그를 선택한 다음 **선택하기**를 선택합니다. 1. (선택 사항) **태그**에 데이터 소스와 연결할 키/값 페어를 입력합니다. 1. **다음**을 선택합니다. 1. **검토 및 생성** 페이지에서 입력한 정보가 정확한지 확인한 다음 **데이터 소스 생성**을 선택합니다. ## S3 Table용 CTAS Amazon Athena는 이제 S3 Table에 대해 CREATE TABLE AS SELECT(CTAS) 작업을 지원합니다. 이 기능을 사용하면 SELECT 쿼리의 결과를 기반으로 새 S3 Table을 생성할 수 있습니다. S3 Table용 CTAS 쿼리를 생성할 때는 표준 Athena 테이블과 비교하여 몇 가지 중요한 차이점이 있습니다. + S3 Table이 자체 스토리지 위치를 자동으로 관리하므로 위치 속성을 생략해야 합니다. + `table_type` 속성의 기본값은 `ICEBERG`이므로 쿼리에서 명시적으로 지정할 필요가 없습니다. + 형식을 지정하지 않으면 시스템이 자동으로 `PARQUET`을 데이터 기본 형식으로 사용합니다. + 다른 모든 속성은 일반 Iceberg 테이블과 동일한 구문을 따릅니다. CTAS를 사용하여 S3 Table을 생성하기 전에 IAM 또는 AWS Lake Formation에 필요한 권한이 구성되어 있는지 확인합니다. 특히 S3 Tables 카탈로그에서 테이블을 생성할 수 있는 권한이 필요합니다. 이러한 권한이 없으면 CTAS 작업이 실패합니다. **참고** CTAS 쿼리가 실패하면 쿼리를 다시 실행하기 전에 [S3 Tables API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-delete.html)를 사용하여 테이블을 삭제해야 할 수 있습니다. Athena `DROP TABLE` 문을 사용해서는 쿼리에서 부분적으로 생성된 테이블을 제거할 수 없습니다. **예제** ``` CREATE TABLE "s3tablescatalog/amzn-s3-demo-bucket"."namespace"."s3-table-name" WITH ( format = 'PARQUET' ) AS SELECT * FROM source_table; ``` # Athena에서 AWS Glue 데이터 카탈로그 쿼리 Athena에서 데이터 카탈로그를 쿼리하려면 다음 중 하나를 수행합니다. + Athena에서 카탈로그를 데이터 소스로 등록한 다음 데이터 소스 이름을 사용하여 카탈로그를 쿼리합니다. 이 사용에서 다음 쿼리는 동등합니다. ``` SELECT * FROM my_data_source.my_database.my_table ``` + Athena 데이터 소스로 등록되지 않은 카탈로그를 쿼리하는 경우 다음 예제와 같이 `SELECT` 쿼리에서 카탈로그에 대한 전체 경로를 제공할 수 있습니다. ``` SELECT * FROM "my_catalog/my_subcatalog".my_database.my_table ``` + AWS Management Console을 통해서도 이 작업을 수행할 수 있습니다. 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/)에서 Athena 콘솔을 엽니다. 1. 쿼리 편집기의 **데이터 소스**에서 **AwsDataCatalog**를 선택합니다. 1. **카탈로그**에서 사용할 카탈로그의 이름을 선택합니다. 1. **데이터베이스**에서 쿼리하려는 테이블이 포함된 데이터베이스를 선택합니다. 1. `SELECT * FROM my_table`와 같은 쿼리를 입력한 다음 **실행**을 선택합니다. # 다른 계정의 데이터 카탈로그 등록 Athena의 계정 간 AWS Glue 카탈로그 기능을 사용해 자신의 계정이 아닌 다른 계정의 AWS Glue 카탈로그를 등록할 수 있습니다. AWS Glue에 요구되는 IAM 권한을 구성하고 카탈로그를 Athena `DataCatalog` 리소스로 등록하면 Athena를 사용해 계정 간 쿼리를 실행할 수 있습니다. 필요한 권한 구성에 대한 자세한 내용은 [AWS Glue 데이터 카탈로그에 대한 크로스 계정 액세스 구성](security-iam-cross-account-glue-catalog-access.md) 단원을 참조하세요. 다음 절차는 Athena를 사용하여 자신의 계정이 아닌 Amazon Web Services 계정의 AWS Glue Data Catalog를 데이터 소스로 구성하는 방법을 보여줍니다. ## 콘솔에서 등록 1. [AWS Glue 데이터 카탈로그에 대한 크로스 계정 액세스 구성](security-iam-cross-account-glue-catalog-access.md)의 단계에 따라 다른 계정의 데이터 카탈로그를 쿼리할 권한이 있는지 확인합니다. 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. **데이터 소스 및 카탈로그**를 선택합니다. 1. 오른쪽 위에서 **데이터 소스 생성(Create data source)**을 선택합니다. 1. **데이터 소스 선택(Choose a data source)**페이지에서 **데이터 소스(Data sources)**에 **S3 - AWS Glue Data Catalog**를 선택하고 **다음(Next)**을 선택합니다. 1. **데이터 소스 세부 정보 입력(Enter data source details)** 페이지의 **AWS Glue Data Catalog** 섹션에서 **AWS Glue Data Catalog 선택(Choose an AWS Glue Data Catalog)**에 **다른 계정의 AWS Glue Data Catalog(AWS Glue Data Catalog in another account)**를 선택합니다. 1. **데이터 세트 세부 정보(Dataset details)**에 다음 정보를 입력합니다. + **데이터 소스 이름(Data source name)** – 다른 계정의 데이터 카탈로그를 참조할 때 SQL 쿼리에 사용할 이름을 입력합니다. + **설명(Description)** - (선택 사항) 다른 계정의 데이터 카탈로그에 대한 설명을 입력합니다. + **카탈로그 ID(Catalog ID)** - 데이터 카탈로그가 속한 계정의 Amazon Web Services 계정 ID(12자리)를 입력합니다. Amazon Web Services 계정 ID는 카탈로그 ID입니다. 1. (선택 사항) **태그(Tags)**에 데이터 소스와 연결할 키-값 페어를 입력합니다. 태그에 대한 자세한 내용은 [Athena 리소스 태깅](tags.md) 섹션을 참조하세요. 1. **다음**을 선택합니다. 1. **검토 및 생성(Review and create)** 페이지에서 제공한 정보를 검토한 다음 **데이터 소스 생성(Create data source)**을 선택합니다. **데이터 소스 세부 정보(Data source details)** 페이지는 등록한 데이터 카탈로그에 대한 데이터베이스 및 태그를 나열합니다. 1. **데이터 소스 및 카탈로그**를 선택합니다. 등록한 데이터 카탈로그가 **데이터 소스 이름(Data source name)** 열에 나열됩니다. 1. 새 데이터 카탈로그에 대한 정보를 보거나 편집하려면 카탈로그를 선택한 다음 **작업(Actions)**, **편집(Edit)**을 선택합니다. 1. 새 데이터 카탈로그를 삭제하려면 카탈로그를 선택한 다음 **작업(Actions)**, **삭제(Delete)**를 선택합니다. ## API 작업을 사용하여 등록 1. 다음 `CreateDataCatalog` 요청 본문은 계정 간 액세스를 위한 AWS Glue 카탈로그를 등록합니다. ``` # Example CreateDataCatalog request to register a cross-account Glue catalog: { "Description": "Cross-account Glue catalog", "Name": "ownerCatalog", "Parameters": {"catalog-id" : "" # Owner's account ID }, "Type": "GLUE" } ``` 1. 다음 샘플 코드는 Java 클라이언트를 사용하여 `DataCatalog` 객체를 생성합니다. ``` # Sample code to create the DataCatalog through Java client CreateDataCatalogRequest request = new CreateDataCatalogRequest() .withName("ownerCatalog") .withType(DataCatalogType.GLUE) .withParameters(ImmutableMap.of("catalog-id", "")); athenaClient.createDataCatalog(request); ``` 이 단계가 끝나면 [ListDataCatalogs](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDataCatalogs.html) API 작업을 호출할 때 차용자에게 *`ownerCatalog`*가 표시되어야 합니다. ## AWS CLI를 사용하여 등록 다음 예제 CLI 명령을 사용하여 다른 계정에서 AWS Glue Data Catalog를 등록합니다. ``` aws athena create-data-catalog \ --name cross_account_catalog \ --type GLUE \ --description "Cross Account Catalog" \ --parameters catalog-id= ``` 자세한 내용은 *AWS 빅 데이터 블로그*의 [Query cross-account AWS Glue Data Catalogs using Amazon Athena](https://aws.amazon.com/blogs/big-data/query-cross-account-aws-glue-data-catalogs-using-amazon-athena/)를 참조하세요. # IAM 정책으로 데이터 카탈로그에 대한 액세스 제어 데이터 카탈로그에 대한 액세스를 제어하기 위해 리소스 수준 IAM 권한이나 자격 증명 기반 IAM 정책을 사용합니다. 다음은 Athena용 절차입니다. IAM용 정보는 이 단원 끝부분에 나와 있는 링크를 참조하세요. JSON 데이터 카탈로그 정책 예제에 대한 자세한 내용은 [데이터 카탈로그 예제 정책](datacatalogs-example-policies.md) 단원을 참조하세요. **IAM 콘솔에서 시각적 편집기를 사용하려면 데이터 카탈로그 정책을 만듭니다.** 1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)에서 IAM 콘솔을 엽니다. 1. 왼쪽 탐색 창에서 **정책**을 선택한 후 **정책 생성**을 선택합니다. 1. **시각적 편집기**(Visual editor) 탭에서 **서비스 선택**(Choose a service)을 선택합니다. 그런 다음 Athena를 선택하여 정책에 추가합니다. 1. **작업 선택**(Select actions)을 선택한 후 정책에 추가할 작업을 선택합니다. 시각적 편집기에 Athena에서 사용할 수 있는 작업이 표시됩니다. 자세한 내용은 *서비스 권한 부여 참조*에서 [Amazon Athena에 사용되는 작업, 리소스 및 조건 키](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html)를 참조하세요. 1. **작업 추가**(add actions)를 선택하여 특정 작업을 입력하거나 와일드카드(\$1)를 사용하여 여러 개의 작업을 지정합니다. 기본적으로 사용자가 생성하는 정책은 사용자가 선택하는 작업을 허용합니다. Athena의 `datacatalog` 리소스에 대해 리소스 수준 권한을 지원하는 작업을 하나 이상 선택하면 편집기에 `datacatalog` 리소스가 나열됩니다. 1. **리소스**를 선택하여 정책에 대한 특정 데이터 카탈로그를 지정합니다. JSON 데이터 카탈로그 정책 예제는 [데이터 카탈로그 예제 정책](datacatalogs-example-policies.md) 단원을 참조하세요. 1. 다음과 같이 `datacatalog` 리소스를 지정합니다. ``` arn:aws:athena:::datacatalog/ ``` 1. **정책 검토**(Review policy)를 선택한 후 생성하려는 정책에 대한 **이름**(Name)과 **설명**(Description)(선택 사항)을 입력합니다. 정책 요약을 검토하여 의도한 권한을 부여했는지 확인합니다. 1. **정책 생성**(Create policy)을 선택하고 새로운 정책을 저장합니다. 1. 사용자, 그룹 또는 역할에 이 자격 증명 기반 정책을 연결하고 사용자, 그룹 또는 역할이 액세스할 수 있는 `datacatalog` 리소스를 지정합니다. 자세한 내용은 *서비스 권한 부여 참조*와 *IAM 사용 설명서*에서 다음 주제를 참조하세요. + [Amazon Athena에 사용되는 작업, 리소스 및 조건 키](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html) + [시각적 편집기를 사용하여 정책 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor) + [IAM 정책 추가 및 제거](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) + [리소스에 대한 액세스 제어](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#access_controlling-resources) JSON 데이터 카탈로그 정책 예제는 [데이터 카탈로그 예제 정책](datacatalogs-example-policies.md) 단원을 참조하세요. AWS Glue 권한 및 AWS Glue 크롤러 권한에 대한 자세한 내용은 *AWS Glue 개발자 안내서*의 [AWS Glue에 대한 IAM 권한 설정](https://docs.aws.amazon.com/glue/latest/dg/getting-started-access.html) 및 [크롤러 사전 조건](https://docs.aws.amazon.com/glue/latest/dg/crawler-prereqs.html)을 참조하세요. Amazon Athena 작업의 전체 목록은 [Amazon Athena API 참조](https://docs.aws.amazon.com/athena/latest/APIReference/)의 API 작업 이름을 참조하세요. # 데이터 카탈로그 예제 정책 이 단원에서는 데이터 카탈로그에 다양한 작업을 허용하는 데 사용할 수 있는 예제 정책을 설명합니다. 데이터 카탈로그는 Athena에서 관리하는 IAM 리소스입니다. 따라서 해당 데이터 카탈로그 정책에서 `datacatalog`를 입력으로 받는 작업을 사용할 경우 다음과 같이 데이터 카탈로그의 ARN을 지정해야 합니다. ``` "Resource": [arn:aws:athena:::datacatalog/] ``` ``은 데이터 카탈로그의 이름입니다. 예를 들어 다음과 같이 `test_datacatalog`라는 데이터 카탈로그를 리소스로 지정할 수 있습니다. ``` "Resource": ["arn:aws:athena:us-east-1:123456789012:datacatalog/test_datacatalog"] ``` Amazon Athena 작업의 전체 목록은 [Amazon Athena API 참조](https://docs.aws.amazon.com/athena/latest/APIReference/)의 API 작업 이름을 참조하세요. IAM 정책에 대한 자세한 내용은 *IAM 사용 설명서*의 [시각적 편집기로 정책 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor)을 참조하세요. IAM 정책을 생성하는 방법에 대한 자세한 내용은 [IAM 정책으로 데이터 카탈로그에 대한 액세스 제어](datacatalogs-iam-policy.md) 단원을 참조하세요. + [Example Policy for Full Access to All Data Catalogs](#datacatalog-policy-full-access-to-all-data-catalogs) + [Example Policy for Full Access to a Specified Data Catalog](#datacatalog-policy-full-access-to-a-specified-catalog) + [Example Policy for Querying a Specified Data Catalog](#datacatalog-policy-querying-a-specified-data-catalog) + [Example Policy for Management Operations on a Specified Data Catalog](#datacatalog-policy-management-operations-on-a-specified-catalog) + [Example Policy for Listing Data Catalogs](#datacatalog-policy-listing-data-catalogs) + [Example Policy for Metadata Operations on Data Catalogs](#datacatalog-policy-metadata-operations) **Example 모든 데이터 카탈로그에 대해 전체 액세스를 허용하는 정책의 예** 다음 정책은 계정에 있는 모든 데이터 카탈로그 리소스에 대해 전체 액세스를 허용합니다. 해당 계정에서 다른 모든 사용자에 대해 데이터 카탈로그를 관리해야 하는 사용자에게 이 정책을 사용하는 것이 좋습니다. **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "athena:*" ], "Resource":[ "*" ] } ] } ``` **Example 지정된 데이터 카탈로그에 대해 전체 액세스를 허용하는 정책의 예** 다음 정책은 `datacatalogA`라는 하나의 특정 데이터 카탈로그 리소스에 대해 전체 액세스를 허용합니다. 이 정책은 특정 데이터 카탈로그에 대해 전체 제어 권한을 가진 사용자에게 사용할 수 있습니다. **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "athena:ListDataCatalogs", "athena:ListWorkGroups", "athena:GetDatabase", "athena:ListDatabases", "athena:ListTableMetadata", "athena:GetTableMetadata" ], "Resource":"*" }, { "Effect":"Allow", "Action":[ "athena:StartQueryExecution", "athena:GetQueryResults", "athena:DeleteNamedQuery", "athena:GetNamedQuery", "athena:ListQueryExecutions", "athena:StopQueryExecution", "athena:GetQueryResultsStream", "athena:ListNamedQueries", "athena:CreateNamedQuery", "athena:GetQueryExecution", "athena:BatchGetNamedQuery", "athena:BatchGetQueryExecution", "athena:DeleteWorkGroup", "athena:UpdateWorkGroup", "athena:GetWorkGroup", "athena:CreateWorkGroup" ], "Resource":[ "arn:aws:athena:us-east-1:123456789012:workgroup/*" ] }, { "Effect":"Allow", "Action":[ "athena:CreateDataCatalog", "athena:DeleteDataCatalog", "athena:GetDataCatalog", "athena:GetDatabase", "athena:GetTableMetadata", "athena:ListDatabases", "athena:ListTableMetadata", "athena:UpdateDataCatalog" ], "Resource":"arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA" } ] } ``` **Example 지정된 데이터 카탈로그 쿼리에 대한 정책의 예** 다음 정책은 지정된 `datacatalogA`에서 사용자가 쿼리를 실행하도록 허용합니다. 사용자는 데이터 카탈로그에 대해 업데이트나 삭제 등의 관리 작업을 수행할 수 없습니다. **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "athena:StartQueryExecution" ], "Resource":[ "arn:aws:athena:us-east-1:123456789012:workgroup/*" ] }, { "Effect":"Allow", "Action":[ "athena:GetDataCatalog" ], "Resource":[ "arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA" ] } ] } ``` **Example 지정된 데이터 카탈로그의 관리 작업을 위한 정책의 예** 다음 정책은 사용자가 `datacatalogA` 데이터 카탈로그를 만들고, 삭제하고, 세부 정보를 조회하고, 업데이트할 수 있도록 허용합니다. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:CreateDataCatalog", "athena:GetDataCatalog", "athena:DeleteDataCatalog", "athena:UpdateDataCatalog" ], "Resource": [ "arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA" ] } ] } ``` **Example 데이터 카탈로그 목록 조회에 대한 정책의 예** 다음 정책은 모든 사용자가 모든 데이터 카탈로그의 목록을 조회할 수 있도록 허용합니다. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:ListDataCatalogs" ], "Resource": "*" } ] } ``` **Example 데이터 카탈로그 메타데이터 작업에 대한 정책의 예** 다음 정책은 데이터 카탈로그에 대한 메타데이터 작업을 허용합니다. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:GetDatabase", "athena:GetTableMetadata", "athena:ListDatabases", "athena:ListTableMetadata" ], "Resource": "*" } ] } ``` # Athena 콘솔의 양식을 사용하여 AWS Glue 테이블 추가 다음 절차에서는 Athena 콘솔을 사용하여 **S3 버킷 데이터에서 테이블 생성(Create Table From S3 bucket data)** 양식을 사용하여 테이블을 추가하는 방법을 보여줍니다. **테이블 추가 및 양식을 사용하여 스키마 정보 입력** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 쿼리 편집기에서 **테이블 및 뷰(Tables and views)** 옆에 있는 **생성(Create)**을 선택한 다음 **S3 버킷 데이터(S3 bucket data)**를 선택합니다. 1. **S3 버킷 데이터에서 테이블 생성(Create Table From S3 bucket data)** 양식에서 **테이블 이름(Table name)**에 테이블 이름을 입력합니다. Athena에서 데이터베이스 이름, 테이블 이름 및 열 이름에 사용할 수 있는 문자에 대한 자세한 내용은 [이름 데이터베이스, 테이블 및 열](tables-databases-columns-names.md) 섹션을 참조하세요. 1. **데이터베이스 구성(Database configuration)**에서 기존 데이터베이스를 선택하거나 새 데이터베이스를 생성합니다. 1. **입력 데이터 세트 위치(Location of Input Data Set)**에는 처리할 데이터 세트가 들어 있는 폴더의 Amazon S3 경로를 지정합니다. 경로에 파일 이름을 포함하지 마세요. 지정하는 폴더에 있는 파일을 Athena에서 모두 스캔합니다. 데이터가 이미 파티셔닝된 경우(예: s3://amzn-s3-demo-bucket/logs/year=2004/month=12/day=11/), 기본 경로만 입력합니다(예: s3://amzn-s3-demo-bucket/logs/). 1. **Data Format**(데이터 형식)의 경우 다음과 같은 옵션 중에서 선택합니다. + **Table type**(테이블 유형)에서 **Apache Hive**, **Apache Iceberg** 또는 **Delta Lake**를 선택합니다. Athena에서는 Apache Hive 테이블 유형을 기본값으로 사용합니다. Athena의 Apache Iceberg 테이블 쿼리에 대한 내용은 [Apache Iceberg 테이블 쿼리](querying-iceberg.md) 단원을 참조하세요. Athena의 Delta Lake 테이블 사용에 대한 내용은 [Linux Foundation Delta Lake 테이블 쿼리](delta-lake-tables.md) 단원을 참조하세요. + **File format**(파일 형식)의 경우 데이터가 들어 있는 파일 또는 로그 형식을 선택합니다. + **사용자 지정 구분 기호가 있는 텍스트 파일** 옵션의 경우 **필드 종결자**(즉, 열 구분 기호)를 지정합니다. 선택 사항으로, 배열 유형의 끝을 표시하는 **Collection terminator**(컬렉션 종결자) 또는 맵 데이터 유형의 끝을 표시하는 **Collection terminator**(컬렉션 종결자)를 지정할 수 있습니다. + **SerDe library**(SerDe 라이브러리) – SerDe(serializer-deserializer) 라이브러리에서는 Athena에서 특정 데이터 형식의 테이블을 생성할 수 있도록 구문을 분석합니다. 대다수 형식에 기본 SerDe 라이브러리가 선택되어 있습니다. 다음과 같은 형식의 경우 요구 사항에 따라 라이브러리를 선택합니다. + **Apache Web Logs**(Apache 웹 로그) – **RegexSerDe** 또는 **GrokSerDe** 라이브러리를 선택합니다. RegexSerDe의 경우 **Regex definition**(정규식 정의) 상자에 정규 표현식을 입력합니다. GrokSerDe의 경우 `input.format` SerDe 속성에 대해 이름이 지정된 일련의 정규 표현식을 입력합니다. 이름이 지정된 정규 표현식은 정규 표현식보다 읽고 유지 관리하기 쉽습니다. 자세한 내용은 [Amazon S3에 저장된 Apache 로그 쿼리](querying-apache-logs.md) 섹션을 참조하세요. + **CSV** – 쉼표로 구분된 데이터에 큰따옴표로 묶인 값이 없거나 `java.sql.Timestamp` 형식을 사용하는 경우 **LazySimpleSerDe**를 선택합니다. 데이터에 따옴표가 있거나 `TIMESTAMP`에 UNIX 숫자 형식을 사용하는(예:`1564610311`) 경우 **OpenCSVSerDe**를 선택합니다. 자세한 내용은 [CSV, TSV, 사용자 지정 구분 기호로 구분된 파일에 대한 Lazy Simple SerDe](lazy-simple-serde.md) 및 [CSV 처리를 위한 Open CSV SerDe](csv-serde.md) 섹션을 참조하세요. + **JSON** – **OpenX** 또는 **Hive** JSON SerDe 라이브러리를 선택합니다. 두 형식 모두 각 JSON 문서가 한 줄의 텍스트에 있으며 해당 필드가 줄 바꿈 문자로 구분되지 않을 것으로 예상합니다. OpenX SerDe에서는 몇 가지 추가 속성을 제공합니다. 이러한 속성에 대한 자세한 내용은 [OpenX JSON SerDe](openx-json-serde.md) 단원을 참조하십시오. Hive SerDe에 대한 내용은 [Hive JSON SerDe](hive-json-serde.md) 섹션을 참조하세요. Athena의 SerDe 라이브러리 사용에 대한 자세한 내용은 [데이터에 적합한 SerDe 선택](supported-serdes.md) 섹션을 참조하세요. 1. **SerDe properties**(SerDe 속성)의 경우 사용 중인 SerDe 라이브러리와 자신의 요구 사항에 따라 속성과 값을 추가, 편집 또는 제거합니다. + SerDe 속성을 추가하려면 **Add SerDe property**(SerDe 속성 추가)를 선택합니다. + **Name**(이름) 필드에 속성의 이름을 입력합니다. + **Value**(값) 필드에 속성 값을 입력합니다. + SerDe 속성을 제거하려면 **Remove**(제거)를 선택합니다. 1. **Table properties**(테이블 속성)의 경우 자신의 요구 사항에 따라 테이블 속성을 선택하거나 편집합니다. + **Write compression**(쓰기 압축)의 경우 압축 옵션을 선택합니다. 쓰기 압축 옵션과 사용 가능한 압축 옵션의 가용성은 데이터 형식에 따라 다릅니다. 자세한 내용은 [Athena에서 압축 사용](compression-formats.md) 섹션을 참조하세요. + **Encryption**(암호화)의 경우 Amazon S3에서 기본 데이터가 암호화되어 있으면 **Encrypted data set**(암호화된 데이터 세트)를 선택합니다. 이 옵션을 통해 `CREATE TABLE` 명령문의 `has_encrypted_data` 테이블 속성이 true로 설정됩니다. 1. **Column details**(열 세부 정보)의 경우 테이블에 추가할 열의 이름과 데이터 유형을 입력합니다. + 열을 한 번에 하나씩 추가하려면 **열 추가**를 선택합니다. + 열을 빠르게 추가하려면 **열 일괄 추가**를 선택합니다. 텍스트 상자에 쉼표로 구분된 열 목록을 *column\$1name* *data\$1type*, *column\$1name* *data\$1type*[, ...], 형식으로 입력한 다음 **추가(Add)**를 선택합니다. 1. (선택 사항) **파티션 세부 정보(Partition details)**에 대해 하나 이상의 열 이름과 데이터 형식을 추가합니다. 파티셔닝은 열 값을 기준으로 관련 데이터가 함께 유지되므로 쿼리당 스캔되는 데이터의 양을 줄이는 데 도움이 될 수 있습니다. 파티셔닝에 대한 자세한 내용은 [데이터 파티셔닝](partitions.md) 섹션을 참조하세요. 1. (선택 사항) **Bucketing**(버킷팅) 경우 함께 그룹화하려는 행이 있는 하나 이상의 열을 지정한 다음에 해당 행을 여러 버킷에 넣을 수 있습니다. 이렇게 하면 버킷 열 값을 지정할 때 읽으려는 버킷만 쿼리할 수 있습니다. + **Buckets**(버킷)의 경우 고유 값(예: 프라이머리 키)이 많이 있고 쿼리의 데이터 필터링에 자주 사용되는 열을 하나 이상 선택합니다. + **Number of buckets**(버킷 수)의 경우 파일의 최적 크기가 허용되는 숫자를 입력합니다. 자세한 내용은 AWS 빅 데이터 블로그의 [Top 10 Performance Tuning Tips for Amazon Athena](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)(Amazon Athena의 성능 튜닝을 위한 10가지 팁)를 참조하세요. + 버킷된 열을 지정하기 위해 `CREATE TABLE` 명령문에서는 다음과 같은 구문을 사용합니다. ``` CLUSTERED BY (bucketed_columns) INTO number_of_buckets BUCKETS ``` **참고** **Iceberg** 테이블 유형에는 **Bucketing**(버킷팅) 옵션을 사용할 수 없습니다. 1. **미리 보기 테이블 쿼리(Preview table query)** 상자에는 양식에 입력한 정보로 생성된 `CREATE TABLE` 문이 표시됩니다. 미리 보기 문은 직접 편집할 수 없습니다. 명령문을 변경하려면 미리 보기 위의 양식 필드를 수정하거나 양식을 사용하지 않고 쿼리 편집기에서 [직접 명령문을 생성](creating-tables-how-to.md#to-create-a-table-using-hive-ddl)합니다. 1. **테이블 생성(Create table)**을 선택하여 쿼리 편집기에서 생성된 문을 실행하고 테이블을 생성합니다. # 크롤러를 사용하여 테이블 추가 AWS Glue 크롤러는 데이터 집합의 스키마를 검색하고 AWS Glue 데이터 카탈로그에 테이블로 등록하는 데 도움이 됩니다. 크롤러는 데이터를 살펴보고 스키마를 결정합니다. 뿐만 아니라 파티션도 찾고 등록할 수 있습니다. 자세한 내용은 *AWS Glue 개발자 안내서*의 [크롤러 정의](https://docs.aws.amazon.com/glue/latest/dg/add-crawler.html)를 참조하세요. 성공적으로 크롤링된 데이터의 테이블은 Athena에서 쿼리할 수 있습니다. **참고** Athena는 AWS Glue 크롤러에 지정한 [제외 패턴](https://docs.aws.amazon.com/glue/latest/dg/define-crawler.html#crawler-data-stores-exclude)을 인식하지 못합니다. 예를 들어 `.csv` 및 `.json` 파일이 모두 포함된 Amazon S3 버킷이 있는데 `.json` 파일을 크롤러에서 제외한다면 Athena는 두 파일 그룹을 모두 쿼리합니다. 이 문제를 방지하려면 제외할 파일을 다른 위치에 배치하면 됩니다. ## AWS Glue 크롤러 생성 Athena 콘솔에서 크롤러를 시작한 다음 통합된 방식으로 AWS Glue 콘솔을 사용하여 크롤러를 생성할 수 있습니다. 크롤러를 생성할 때 크롤링할 Amazon S3의 데이터 위치를 지정합니다. **Athena 콘솔에서 시작하여 AWS Glue에서 크롤러 생성** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 쿼리 편집기에서 **테이블 및 뷰(Tables and views)** 옆에 있는 **생성(Create)**을 선택한 다음 **AWS Glue 크롤러(Glue crawler)**를 선택합니다. 1. **AWS Glue** 콘솔의 **크롤러 추가** 페이지에서 단계에 따라 크롤러를 생성합니다. 자세한 내용은 이 설명서의 [AWS Glue 크롤러 사용](#schema-crawlers)과 *AWS Glue 개발자 안내서*의 [AWS Glue Data Catalog 채우기](https://docs.aws.amazon.com/glue/latest/dg/populate-catalog-methods.html)를 참조하세요. **참고** Athena는 AWS Glue 크롤러에 지정한 [제외 패턴](https://docs.aws.amazon.com/glue/latest/dg/define-crawler.html#crawler-data-stores-exclude)을 인식하지 못합니다. 예를 들어 `.csv` 및 `.json` 파일이 모두 포함된 Amazon S3 버킷이 있는데 `.json` 파일을 크롤러에서 제외한다면 Athena는 두 파일 그룹을 모두 쿼리합니다. 이 문제를 방지하려면 제외할 파일을 다른 위치에 배치하면 됩니다. 크롤링 후 AWS Glue 크롤러는 Apache Hive, Presto 및 Spark 등 다른 외부 기술과 호환되도록 특정 테이블 메타데이터를 자동으로 할당합니다. 경우에 따라 크롤러가 메타데이터 속성을 잘못 할당할 수 있습니다. Athena를 사용하여 테이블을 쿼리하기 전에 AWS Glue의 속성을 수동으로 수정하세요. 자세한 내용은 *AWS Glue 개발자 안내서*의 [테이블 세부 정보 보기 및 편집](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html#console-tables-details)을 참조하세요. CSV 파일에 각 데이터 필드를 묶는 인용 부호가 있으면 `serializationLib` 속성이 잘못되어 AWS Glue이(가) 메타데이터를 잘못 할당할 수 있습니다. 자세한 내용은 [따옴표로 묶은 CSV 데이터 취급](schema-csv.md#schema-csv-quotes) 섹션을 참조하세요. # 크롤러에 여러 데이터 원본 사용 AWS Glue 크롤러가 Amazon S3를 스캔하고 여러 디렉터리를 발견하면 휴리스틱을 사용하여 테이블의 루트가 디렉터리 구조에서 어디에 있는지, 어떤 디렉터리가 테이블의 파티션인지 파악합니다. 간혹 둘 이상의 디렉터리에서 발견된 스키마가 유사한 경우, 크롤러가 이를 별도의 테이블 대신 파티션으로 처리할 수 있습니다. 크롤러가 개별 테이블을 찾도록 돕는 한 가지 방법은, 각 테이블의 루트 디렉터리를 크롤러의 데이터 저장소로 추가하는 것입니다. Amazon S3에 있는 다음 파티션이 한 예입니다. ``` s3://amzn-s3-demo-bucket/folder1/table1/partition1/file.txt s3://amzn-s3-demo-bucket/folder1/table1/partition2/file.txt s3://amzn-s3-demo-bucket/folder1/table1/partition3/file.txt s3://amzn-s3-demo-bucket/folder1/table2/partition4/file.txt s3://amzn-s3-demo-bucket/folder1/table2/partition5/file.txt ``` `table1`과 `table2`의 스키마가 비슷하고 AWS Glue에서 하나의 데이터 원본이 `s3://amzn-s3-demo-bucket/folder1/`으로 설정된 경우, 크롤러는 두 개의 파티션 열(`table1`과 `table2`가 포함된 파티션 열과 `partition1`부터 `partition5`까지 포함하는 두 번째 파티션 열)로 구성된 하나의 테이블을 만들 수 있습니다. AWS Glue 크롤러가 의도대로 두 개의 개별 테이블을 생성하게 하려면 크롤러가 다음 절차처럼 두 개의 데이터 원본(`s3://amzn-s3-demo-bucket/folder1/table1/`, `s3://amzn-s3-demo-bucket/folder1/table2`)으로 구성되도록 설정합니다. **AWS Glue에서 기존 크롤러에 S3 데이터 스토어를 추가하려면** 1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)에서 AWS Glue 콘솔을 엽니다. 1. 탐색 창에서 **크롤러(Crawlers)**를 선택합니다. 1. 크롤러 링크를 선택한 다음 **편집(Edit)**을 선택합니다. 1. **2단계: 데이터 소스 및 분류자 선택(Step 2: Choose data sources and classifiers)**에서 **편집(Edit)**을 선택합니다. 1. **데이터 소스 및 카탈로그**에서 **데이터 소스 추가**를 선택합니다. 1. **데이터 소스 추가(Add a data source)** 대화 상자의 **S3 경로(S3 path)**에서 **찾아보기(Browse)**를 선택합니다. 1. 사용할 버킷을 선택한 다음 **선택(Choose)**을 선택합니다. 추가한 데이터 소스가 **데이터 소스(Data sources)** 목록에 표시됩니다. 1. **다음**을 선택합니다. 1. **보안 설정 구성** 페이지에서 크롤러에 대한 IAM 역할을 생성 또는 선택한 다음 **다음(Next)**을 선택합니다. 1. S3 경로가 후행 슬래시로 끝나는지 확인한 다음 **S3 데이터 소스 추가(Add an S3 data source)**를 선택합니다. 1. **출력 및 예약 설정** 페이지의 **출력 구성(Output configuration)**에서 대상 데이터베이스를 선택합니다. 1. **다음**을 선택합니다. 1. **검토 및 업데이트** 페이지에서 선택한 항목을 검토합니다. 단계를 편집하려면 **편집(Edit)**을 선택합니다. 1. **업데이트**를 선택합니다. # AWS Glue Data Catalog와 Amazon S3의 동기화를 유지할 수 있도록 크롤러 예약 AWS Glue 크롤러는 일정 또는 필요에 따라 실행되도록 설정할 수 있습니다. 자세한 내용은 *AWS Glue 개발자 안내서*의 [크롤러와 작업을 위한 시간 기반 일정](https://docs.aws.amazon.com/glue/latest/dg/monitor-data-warehouse-schedule.html)을 참조하세요. 정해진 시간에 분할된 테이블에 수신되는 데이터가 있는 경우 AWS Glue 크롤러가 일정에 따라 테이블 파티션을 검색하고 업데이트하도록 설정할 수 있습니다. 그러면 상당한 시간과 비용이 들 수 있는 `MSCK REPAIR` 명령을 실행하거나 수동으로 `ALTER TABLE ADD PARTITION` 명령을 실행할 필요가 없습니다. 자세한 내용은 *AWS Glue 개발자 안내서*의 [테이블 파티션](https://docs.aws.amazon.com/glue/latest/dg/tables-described.html#tables-partition)을 참조하세요. # AWS Glue 파티션 인덱싱 및 필터링을 통한 쿼리 최적화 Athena는 분할된 테이블을 쿼리할 때 사용 가능한 테이블 파티션을 검색하고 쿼리와 관련된 하위 집합으로 필터링합니다. 새 데이터와 파티션이 추가되면 파티션을 처리하는 데 더 많은 시간이 필요하며 쿼리 런타임이 늘어날 수 있습니다. 시간이 지남에 따라 확장되는 파티션이 많은 테이블이 있는 경우 AWS Glue 파티션 인덱싱 및 필터링을 고려하세요. 파티션 처리를 최적화하고 고도로 분할된 테이블에서 쿼리 성능을 향상시키기 위해 Athena는 파티션 인덱싱을 사용합니다. 테이블의 속성에서 파티션 필터링을 설정하는 과정은 두 단계로 이루어집니다. 1. AWS Glue에서 파티션 인덱스 생성 1. 테이블에 대해 파티션 필터링 사용 설정 ## 파티션 인덱스 생성 AWS Glue에서 파티션 인덱스를 생성하는 단계는 AWS Glue 개발자 안내서의 [파티션 인덱스 작업](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)을 참조하세요. AWS Glue의 파티션 인덱스에 대한 제한 사항은 해당 페이지의 [파티션 인덱스 정보](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html#partition-index-1) 섹션을 참조하세요. ## 파티션 필터링 사용 설정 테이블에 대해 파티션 필터링을 사용 설정하려면 AWS Glue에서 새 테이블 속성을 설정해야 합니다. AWS Glue에서 테이블 속성을 설정하는 방법에 대한 단계는 [파티션 프로젝션 설정](https://docs.aws.amazon.com/athena/latest/ug/partition-projection-setting-up.html) 페이지를 참조하세요. AWS Glue에서 테이블 세부 정보를 편집할 때 **테이블 속성(Table properties)** 섹션에 다음 키-값 페어를 추가합니다. + **키(Key)**에서 `partition_filtering.enabled`를 추가합니다. + **값(Value)**에 `true`를 추가합니다. `partition_filtering.enabled` 값을 `false`로 설정하여 언제든지 이 테이블에서 파티션 프로젝션을 비활성화할 수 있습니다. 위의 단계를 완료한 후 Athena 콘솔로 돌아가서 데이터를 쿼리할 수 있습니다. 파티션 인덱싱 및 필터링 사용에 대한 자세한 내용은 *AWS 빅 데이터 블로그*의 [Improve Amazon Athena query performance using AWS Glue Data Catalog partition indexes](https://aws.amazon.com/blogs/big-data/improve-amazon-athena-query-performance-using-aws-glue-data-catalog-partition-indexes/)를 참조하세요. # AWS CLI를 사용하여 AWS Glue 데이터베이스 및 해당 테이블 다시 생성 AWS Glue 데이터베이스 이름을 직접 바꿀 수는 없지만 해당 정의를 복사하고 정의를 수정하며 해당 정의를 사용하여 데이터베이스를 다른 이름으로 다시 생성할 수는 있습니다. 마찬가지로 이전 데이터베이스의 테이블 정의를 복사하고 정의를 수정하며 수정된 정의를 사용하여 새 데이터베이스에서 테이블을 다시 생성할 수 있습니다. **참고** 제시된 방법에서는 테이블 파티셔닝을 복사하지 않습니다. 다음 Windows용 절차에서는 JSON 출력을 위해 AWS CLI가 구성되어 있다고 가정합니다. AWS CLI에서 기본 출력 형식을 변경하려면 `aws configure`를 실행합니다. **AWS CLI를 사용하여 AWS Glue 데이터베이스를 복사하려면** 1. 명령 프롬프트에서 다음 AWS CLI 명령을 실행하여 복사하려는 AWS Glue 데이터베이스의 정의를 검색합니다. ``` aws glue get-database --name database_name ``` `get-database` 명령에 대한 자세한 내용은 [get-database](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-database.html)를 참조하세요. 1. 새 데이터베이스 이름(예:`new_database_name.json`)을 사용하는 데스크톱의 파일에 JSON 출력을 저장합니다. 1. 텍스트 편집기에서 `new_database_name.json` 파일을 엽니다. 1. JSON 파일에서 다음 단계를 수행합니다. 1. 외부 `{ "Database":` 항목과 파일 끝에 있는 해당하는 중괄호(`}`)를 제거합니다. 1. `Name` 항목을 새 데이터베이스 이름으로 변경합니다. 1. `CatalogId` 필드를 제거합니다. 1. 파일을 저장합니다. 1. 명령 프롬프트에서 다음 AWS CLI 명령을 실행하여 수정된 데이터베이스 정의 파일을 사용해 새 이름으로 데이터베이스를 생성합니다. ``` aws glue create-database --database-input "file://~/Desktop\new_database_name.json" ``` `create-database` 명령에 대한 자세한 내용은 [create-database](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/create-database.html)를 참조하세요. 파일에서 AWS CLI 파라미터 로드에 대한 자세한 내용은 *AWS Command Line Interface 사용 설명서*의 [파일에서 AWS CLI 파라미터 로드](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html)를 참조하세요. 1. AWS Glue에서 새 데이터베이스가 생성되었는지 확인하려면 다음 명령을 실행합니다. ``` aws glue get-database --name new_database_name ``` 이제 새 데이터베이스에 복사하려는 테이블의 정의를 가져와서 정의를 수정하고 수정된 정의를 사용하여 새 데이터베이스에서 테이블을 다시 생성할 준비가 되었습니다. 이 절차에서는 테이블 이름을 변경하지 않습니다. **AWS CLI를 사용하여 AWS Glue 테이블을 복사하려면** 1. 명령 프롬프트에서 다음 AWS CLI 명령을 실행합니다. ``` aws glue get-table --database-name database_name --name table_name ``` `get-table` 명령에 대한 자세한 내용은 [get-table](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-table.html)을 참조하세요. 1. 테이블 이름(예: *table\$1name*.json)을 사용하는 Windows 데스크톱의 파일에 JSON 출력을 저장합니다. 1. 텍스트 편집기에서 파일을 엽니다. 1. JSON 파일에서 외부 `{"Table": ` 항목과 파일 끝에 있는 해당하는 중괄호(`}`)를 제거합니다. 1. JSON 파일에서 다음 항목과 해당 값을 제거합니다. + `DatabaseName` - `create-table` CLI 명령에서 `--database-name` 파라미터를 사용하므로 이 항목은 필요하지 않습니다. + `CreateTime` + `UpdateTime` + `CreatedBy` + `IsRegisteredWithLakeFormation` + `CatalogId` + `VersionId` 1. 테이블 정의 파일을 저장합니다. 1. 명령 프롬프트에서 다음 AWS CLI 명령을 실행하여 새 데이터베이스에서 테이블을 다시 생성합니다. ``` aws glue create-table --database-name new_database_name --table-input "file://~/Desktop\table_name.json" ``` `create-table` 명령에 대한 자세한 내용은 [create-table](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/create-table.html)을 참조하세요. 이제 테이블이 AWS Glue에서 새 데이터베이스에 나타나고 Athena에서 해당 테이블을 쿼리할 수 있습니다. 1. 단계를 반복하여 AWS Glue의 새 데이터베이스에 각각의 추가 테이블을 복사합니다. # ETL 작업용 테이블 생성 Athena를 사용하여 AWS Glue에서 ETL 작업에 사용할 수 있는 테이블을 생성할 수 있습니다. AWS Glue 작업은 ETL 작업을 수행합니다. AWS Glue 작업은 소스에서 데이터를 추출하고 데이터를 변환한 다음 대상으로 로드하는 스크립트를 실행합니다. 자세한 내용은 *AWS Glue 개발자 안내서*의 [AWS Glue에 작업 작성](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)을 참조하세요. ## AWS Glue ETL 작업을 위한 Athena 테이블 생성 Athena에서 생성한 테이블에는 데이터 형식을 식별하는 `classification`이라는 테이블 속성이 추가되어야 합니다. 그러면 AWS Glue이(가) ETL 작업에 이 테이블을 사용할 수 있습니다. 분류 값은 `avro`, `csv`, `json`, `orc`, `parquet` 또는 `xml`일 수 있습니다. Athena에서의 `CREATE TABLE` 문 예제는 다음과 같습니다. ``` CREATE EXTERNAL TABLE sampleTable ( column1 INT, column2 INT ) STORED AS PARQUET TBLPROPERTIES ( 'classification'='parquet') ``` 테이블을 만들 때 `classification` 테이블 속성을 추가하지 않았다면 AWS Glue 콘솔을 사용하여 추가할 수 있습니다. **AWS Glue 콘솔을 사용하여 분류 테이블 속성을 추가하려면** 1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)에서 AWS Glue 콘솔을 엽니다. 1. 콘솔 탐색 창에서 **테이블(Tables)**을 선택합니다. 1. 편집할 테이블 링크를 선택한 다음 **작업(Actions)**, **테이블 편집(Edit table)**을 선택합니다. 1. 아래로 스크롤하여 **테이블 속성** 섹션을 찾습니다. 1. **추가**를 선택합니다. 1. **키**에 **classification**를 입력합니다. 1. **값(Value)**에 데이터 유형(예:**json**)을 입력합니다. 1. **저장(Save)**을 선택합니다. 입력한 데이터 유형이 **테이블 세부 정보(Table details)** 섹션에서 테이블의 **분류(Classification)** 필드에 표시됩니다. 자세한 내용은 *AWS Glue 개발자 안내서*에서 [테이블 관련 작업](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html)을 참조하세요. ## ETL 작업을 사용하여 쿼리 성능 최적화 AWS Glue 작업은 Athena에서 쿼리 성능을 최적화하는 형식으로 데이터를 변환하는 데 도움이 됩니다. 데이터 형식은 Athena의 쿼리 성능 및 쿼리 비용에 큰 영향을 줍니다. AWS Glue는 Parquet 및 ORC 데이터 형식으로의 쓰기를 지원합니다. 이 기능을 사용하여 데이터를 Athena에서 사용할 수 있도록 변환할 수 있습니다. Parquet 및 ORC 사용과 Athena의 성능 개선을 위한 다른 방법에 대한 자세한 내용은 [Amazon Athena를 위한 유용한 성능 튜닝 팁 10가지](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)를 참조하세요. **참고** AWS Glue ETL 작업에서 생성한 `SMALLINT` 및 `TINYINT` 데이터 유형을 Athena가 읽지 못하게 될 가능성을 줄이려면 데이터를 ORC로 변환하는 ETL 작업을 생성할 때 `SMALLINT` 및 `TINYINT`를 `INT`로 변환합니다. ## ETL을 위한 AWS Glue 작업 자동화 트리거를 기반으로 AWS Glue ETL 작업이 자동으로 실행되도록 구성할 수 있습니다. AWS 외부의 데이터가 Athena에서 쿼리하기에 최적화되지 않은 형식으로 Amazon S3 버킷에 푸시되는 동안에는 이 기능이 이상적입니다. 자세한 내용은 *AWS Glue 개발자 안내서*의 [AWS Glue 작업 트리거](https://docs.aws.amazon.com/glue/latest/dg/trigger-job.html)를 참조하세요. # AWS Glue에서 CSV 데이터로 작업 이 페이지에서는 AWS Glue를 사용하여 각 열의 데이터 값을 따옴표로 묶은 CSV 파일 또는 헤더 값이 포함된 CSV 파일에서 스키마를 만드는 방법을 설명합니다. ## 따옴표로 묶은 CSV 데이터 취급 다음 예시처럼 데이터 필드를 큰따옴표로 묶은 CSV 파일이 있다고 가정해 보겠습니다. ``` "John","Doe","123-555-1231","John said \"hello\"" "Jane","Doe","123-555-9876","Jane said \"hello\"" ``` 따옴표로 묶인 값을 가진 CSV 파일에서 생성된 테이블에 대해 Athena에서 쿼리를 실행하려면 OpenCSVSerDe를 사용하기 위해 AWS Glue에서 테이블 속성을 수정해야 합니다. OpenCSV SerDe에 대한 자세한 내용은 [CSV 처리를 위한 Open CSV SerDe](csv-serde.md) 단원을 참조하세요. **AWS Glue 콘솔에서 테이블 속성을 편집하려면** 1. AWS Glue 콘솔 탐색 창에서 **테이블**을 선택합니다. 1. 편집할 테이블 링크를 선택한 다음 **작업(Actions)**, **테이블 편집(Edit table)**을 선택합니다. 1. **테이블 편집** 페이지에서 다음과 같이 변경합니다. + **직렬화 라이브러리(Serialization lib)**에 `org.apache.hadoop.hive.serde2.OpenCSVSerde`를 입력합니다. + **Serde 파라미터(Serde parameters)**에서 `escapeChar`, `quoteChar`, `separatorChar` 키에 다음 값을 입력합니다. + `escapeChar`에 백슬래시(**\$1**)를 입력합니다. + `quoteChar`에 큰따옴표(**"**)를 입력합니다. + `separatorChar`에 쉼표(**,**)를 입력합니다. 1. **Save**(저장)를 선택합니다. 자세한 내용은 *AWS Glue 개발자 안내서*의 [테이블 세부 정보 보기 및 편집](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html#console-tables-details)을 참조하세요. 프로그래밍 방식으로 AWS Glue 테이블 속성을 업데이트할 수도 있습니다. 다음 JSON 예제처럼 AWS Glue [UpdateTable](https://docs.aws.amazon.com/glue/latest/webapi/API_UpdateTable.html) API 작업 또는 [update-table](https://docs.aws.amazon.com/cli/latest/reference/glue/update-table.html) AWS CLI 명령을 사용해 테이블 정의의 `SerDeInfo` 블록을 수정합니다. ``` "SerDeInfo": { "name": "", "serializationLib": "org.apache.hadoop.hive.serde2.OpenCSVSerde", "parameters": { "separatorChar": "," "quoteChar": "\"" "escapeChar": "\\" } }, ``` ## 헤더가 포함된 CSV 파일 취급 다음 예제와 같이 `CREATE TABLE` 문으로 Athena에서 테이블을 정의할 때 `skip.header.line.count` 테이블 속성을 사용하여 CSV 데이터의 헤더를 무시할 수 있습니다. ``` ... STORED AS TEXTFILE LOCATION 's3://amzn-s3-demo-bucket/csvdata_folder/'; TBLPROPERTIES ("skip.header.line.count"="1") ``` 또는 헤더 정보가 Athena 쿼리 결과에 포함되지 않도록 미리 CSV 헤더를 제거할 수 있습니다. 한 가지 방법은 추출, 변환 및 로드(ETL) 작업을 수행하는 AWS Glue 작업을 사용하는 것입니다. AWS Glue에서 PySpark Python 언어의 확장 언어를 사용하여 스크립트를 작성할 수 있습니다. 자세한 내용은 *AWS Glue 개발자 안내서*의 [AWS Glue에 작업 작성](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)을 참조하세요. 다음 예는 `from_options`를 사용하여 동적 프레임을 작성하고 `writeHeader` 형식 옵션을 false로 설정하여 헤더 정보를 제거하는 AWS Glue 스크립트의 함수를 보여줍니다. ``` glueContext.write_dynamic_frame.from_options(frame = applymapping1, connection_type = "s3", connection_options = {"path": "s3://amzn-s3-demo-bucket/MYTABLEDATA/"}, format = "csv", format_options = {"writeHeader": False}, transformation_ctx = "datasink2") ``` # AWS Glue에서 지리 공간 데이터 작업 AWS Glue는 기본적으로 WKT(Well-known Text), WKB(Well-Known Binary) 또는 기타 PostGIS 데이터 형식을 지원하지 않습니다. AWS Glue 분류자는 지리 공간 데이터를 구문 분석하며, CSV의 경우 `varchar`와 같이 해당 형식에 지원되는 데이터 형식을 사용하여 분류합니다. 다른 AWS Glue 테이블과 마찬가지로 Athena가 이러한 데이터 형식을 그대로 구문 분석할 수 있게 하려면 지리 공간 데이터에서 생성된 테이블의 속성을 업데이트해야 할 수 있습니다. 자세한 내용은 [크롤러를 사용하여 테이블 추가](schema-crawlers.md) 및 [AWS Glue에서 CSV 데이터로 작업](schema-csv.md) 단원을 참조하세요. Athena에서 AWS Glue 테이블의 일부 지리 공간 데이터 형식을 그대로 구문 분석하지 못할 수 있습니다. Athena에서 지리 공간 데이터 작업에 대한 자세한 내용은 [공간 데이터 쿼리](querying-geospatial-data.md) 단원을 참조하세요. # Amazon Athena 페더레이션 쿼리 사용 Amazon S3 외의 원본에 데이터가 있는 경우 Athena 연합 쿼리를 사용하여 데이터를 제자리에 쿼리하거나 여러 데이터 원본에서 데이터를 추출하여 Amazon S3에 저장하는 파이프라인을 구축할 수 있습니다. Athena 연합 쿼리를 사용하면 관계형, 비관계형, 객체 및 사용자 지정 데이터 원본에 저장된 데이터에 대해 SQL 쿼리를 실행할 수 있습니다. Athena는 연합 쿼리를 실행하기 위해 AWS Lambda에서 실행되는 *데이터 원본 커넥터*를 사용합니다. 데이터 원본 커넥터는 대상 데이터 원본과 Athena 간에 변환할 수 있는 코드입니다. 커넥터는 Athena의 쿼리 엔진 확장으로 생각할 수 있습니다. 사전 구축된 Athena 데이터 원본 커넥터는 Amazon CloudWatch Logs, Amazon DynamoDB, Amazon DocumentDB, Amazon RDS, JDBC 호환 관계형 데이터베이스(Apache 2.0 라이선스에 따른 MySQL, PostgreSQL 등)와 같은 데이터 원본을 위한 것입니다. Athena Query Federation SDK를 사용하여 사용자 지정 커넥터를 작성할 수도 있습니다. 데이터 원본 커넥터를 선택 및 구성하여 계정에 배포하려면 Athena 및 Lambda 콘솔 또는 AWS Serverless Application Repository을 사용할 수 있습니다. 데이터 원본 커넥터를 배포한 후 커넥터는 SQL 쿼리에서 지정할 수 있는 카탈로그와 연결됩니다. 여러 카탈로그의 SQL 문을 결합하고 단일 쿼리로 여러 데이터 원본에 적용할 수 있습니다. 데이터 원본에 대해 쿼리가 제출되면, Athena는 해당 커넥터를 호출하여 읽어야 하는 테이블의 일부를 식별하고, 병렬화를 관리하며, 필터 조건자를 푸시다운합니다. 쿼리를 제출하는 사용자를 기반으로 커넥터는 특정 데이터 요소에 대한 액세스를 제공하거나 제한할 수 있습니다. 커넥터는 쿼리에서 요청한 데이터를 반환하기 위한 형식으로 Apache Arrow를 사용합니다. 이렇게 하면 커넥터가 C, C\$1\$1, Java, Python, Rust 같은 언어로 구현될 수 있습니다. 커넥터는 Lambda에서 처리되므로 Lambda에서 액세스할 수 있는 클라우드 또는 온프레미스의 모든 데이터 원본에서 데이터에 액세스하는 데 사용할 수 있습니다. 사용자 고유의 데이터 원본 커넥터를 작성하려면 Athena Query Federation SDK를 사용하여 Amazon Athena가 제공 및 유지 관리하는 사전 구축된 커넥터 중 하나를 사용자 지정할 수 있습니다. [GitHub 리포지토리](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors)에서 소스 코드의 복사본을 수정한 다음 [Connector publish tool](https://github.com/awslabs/aws-athena-query-federation/wiki/Connector_Publish_Tool)(커넥터 게시 도구)를 사용하여 자체 AWS Serverless Application Repository 패키지를 만들 수 있습니다. **참고** 타사 개발자가 Athena Query Federation SDK를 사용하여 데이터 원본 커넥터를 작성한 경우도 있을 수 있습니다. 이러한 데이터 원본 커넥터와 관련한 지원 또는 라이선스 문제는 커넥터 공급업체에 문의하세요. 이러한 커넥터는 AWS에서 테스트 또는 지원되지 않습니다. Athena에서 작성 및 테스트한 데이터 원본 커넥터 목록은 [사용 가능한 데이터 소스 커넥터](connectors-available.md) 섹션을 참조하세요. 사용자 고유의 데이터 원본 커넥터 작성에 대한 자세한 내용은 GitHub의 [Athena 커넥터 예제](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-example)를 참조하세요. ## 고려 사항 및 제한 사항 + **엔진 버전** - Athena 페더레이션 쿼리는 Athena 엔진 버전 2 이상에서만 지원됩니다. Athena 엔진 버전에 대한 자세한 내용은 [Athena 엔진 버전 관리](engine-versions.md) 단원을 참조하세요. + **보기** - 페더레이션된 데이터 소스에서 보기를 생성하고 쿼리할 수 있습니다. 페더레이션된 보기는 기본 데이터 소스가 아닌 AWS Glue에 저장됩니다. 자세한 내용은 [페더레이션 뷰 쿼리](running-federated-queries.md#running-federated-queries-federated-views) 섹션을 참조하세요. + **구분 식별자** - 구분 식별자(인용 식별자로도 불림)는 큰 따옴표(")로 시작해서 끝납니다. 현재 Athena의 페더레이션 쿼리에는 구분된 식별자가 지원되지 않습니다. + **쓰기 작업** - [INSERT INTO](insert-into.md) 같은 쓰기 작업은 지원되지 않습니다. 이를 실행하려고 하면 이 작업은 현재 외부 카탈로그에서 지원되지 않습니다(This operation is currently not supported for external catalogs)라는 오류 메시지가 표시될 수 있습니다. + **요금** – 요금 정보는 [Amazon Athena 요금](https://aws.amazon.com/athena/pricing/)을 참조하세요. + **JDBC 드라이버** - JDBC 드라이버와 함께 연합 쿼리나 [외부 Hive 메타스토어](connect-to-data-source-hive.md)를 사용하려면 JDBC 연결 문자열에 `MetadataRetrievalMethod=ProxyAPI`를 포함해야 합니다. JDBC 드라이버에 대한 자세한 내용은 [JDBC로 Amazon Athena에 연결](connect-with-jdbc.md) 섹션을 참조하세요. + **Secrets Manager** – AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager에 대해 Amazon VPC 프라이빗 엔드포인트를 구성해야 합니다. 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [Secrets Manager VPC 프라이빗 엔드포인트 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)을 참조하세요. ## 필요한 권한 데이터 원본 커넥터가 올바르게 작동하려면 다음 리소스에 액세스해야 할 수 있습니다. 사전 구축된 커넥터를 사용하는 경우 커넥터의 정보를 확인하여 VPC를 올바르게 구성했는지 확인합니다. 또한 쿼리를 실행하고 커넥터를 만드는 IAM 보안 주체에게 필요한 작업에 대한 권한이 있는지 확인합니다. 자세한 내용은 [Athena 페더레이션 쿼리에 대한 액세스 허용: 정책 예제](federated-query-iam-access.md) 단원을 참조하세요. + **Amazon S3** – 쿼리 결과를 Amazon S3의 Athena 쿼리 결과 위치에 작성하는 것 외에도 데이터 커넥터는 Amazon S3의 유출 버킷에 작성합니다. 이 Amazon S3 위치에 대한 연결 및 권한이 필요합니다. 각 커넥터 및 [S3 수명 주기 구성](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)에 대해 디스크로 유출 암호화를 사용하여 더 이상 필요하지 않은 유출된 데이터를 만료시키는 것이 좋습니다. + **Athena** – 데이터 원본은 쿼리 상태를 확인하고 오버스캔을 방지하기 위해 Athena와 양방향으로 연결해야 합니다. + **AWS Glue Data Catalog** – 커넥터가 보충 또는 기본 메타데이터에 데이터 카탈로그를 사용하는 경우 연결 및 권한이 필요합니다. + **Amazon ECR** – 데이터 소스 커넥터 Lambda 함수는 Amazon ECR 리포지토리의 Amazon ECR 이미지를 사용합니다. 커넥터를 배포하는 사용자는 `ecr:BatchGetImage` 및 `ecr:GetDownloadUrlForLayer` 권한이 있어야 합니다. 자세한 내용은 *AWS Lambda 개발자 안내서*의 [Amazon ECR 권한](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html#gettingstarted-images-permissions) 섹션을 참조하세요. ## 비디오 Athena 연합 쿼리 사용에 대해 자세히 알아보려면 다음 동영상을 시청하세요. **동영상: Analyze Results of Federated Query in Amazon Athena in Quick** 다음 동영상은 Quick에서 Athena 연합 쿼리의 결과를 분석하는 방법을 보여줍니다. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/HyM5d0TmwAQ/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/HyM5d0TmwAQ) **동영상: 게임 분석 파이프라인** 다음 동영상은 Amazon Athena 연합 쿼리를 사용하여 게임 및 서비스의 원격 측정 데이터를 수집, 저장, 분석하기 위해 확장형 서버리스 데이터 파이프라인을 배포하는 방법을 보여줍니다. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/xcS-flUMVbs/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/xcS-flUMVbs) # 사용 가능한 데이터 소스 커넥터 이 섹션에는 Athena 외부의 다양한 데이터 원본을 쿼리하는 데 사용할 수 있는 사전 구축된 Amazon S3 데이터 원본 커넥터가 나열되어 있습니다. Athena 쿼리에서 커넥터를 사용하려면 커넥터를 구성하여 계정에 배포합니다. ## 고려 사항 및 제한 사항 + 일부 사전 구축된 커넥터는 커넥터를 사용하기 전에 VPC 및 보안 그룹 생성을 요구합니다. VPC 생성에 대한 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md)을 참조하세요. + AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager에 대해 Amazon VPC 프라이빗 엔드포인트를 구성해야 합니다. 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [Secrets Manager VPC 프라이빗 엔드포인트 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)을 참조하세요. + 조건자 푸시다운을 지원하지 않는 커넥터의 경우 조건자를 포함하는 쿼리는 실행하는 데 시간이 더 오래 걸립니다. 작은 데이터 세트의 경우 매우 적은 양의 데이터가 스캔되고 쿼리에는 평균 약 2분 정도 걸립니다. 그러나 대규모 데이터 세트의 경우 많은 쿼리가 시간 초과될 수 있습니다. + 일부 페더레이션된 데이터 소스는 Athena와는 다른 용어를 사용하여 데이터 객체를 참조합니다. 자세한 내용은 [페더레이션 테이블 이름 한정자 이해](tables-qualifiers.md) 섹션을 참조하세요. + 데이터베이스 또는 데이터 소스 공급자의 업그레이드를 기반으로 커넥터를 정기적으로 업데이트합니다. 지원 종료 기간에 도달한 데이터 소스는 지원되지 않습니다. + 테이블을 나열할 때 페이지 매김을 지원하지 않는 커넥터의 경우 데이터베이스에 테이블과 메타데이터가 많으면 웹 서비스 시간이 초과될 수 있습니다. 다음 커넥터는 테이블 나열을 위한 페이지 매김 지원을 제공합니다. + documentdb + DynamoDB + MySQL + OpenSearch + Oracle + PostgreSQL + Redshift + SQL Server ## Federation SDK의 대소문자 해석기 모드 Federation SDK는 스키마 및 테이블 이름에 대해 다음과 같은 표준화된 대소문자 해석기 모드를 지원합니다. + `NONE` - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. + `LOWER` - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. + `UPPER` - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + `ANNOTATION` -이 모드는 이전 버전과의 호환성을 위해서만 유지되며 기존 Snowflake 및 SAP HANA 커넥터에서만 지원됩니다. + `CASE_INSENSITIVE_SEARCH` - 스키마 및 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다. ## 대소문자 해석기 모드에 대한 커넥터 지원 ### 기본 모드 지원 모든 JDBC 커넥터는 다음 기본 모드를 지원합니다. + `NONE` + `LOWER` + `UPPER` ### 주석 모드 지원 다음 커넥터만 `ANNOTATION` 모드를 지원합니다. + Snowflake + SAP HANA **참고** ANNOTATION 대신 CASE\$1INSENSITIVE\$1SEARCH를 사용하는 것이 좋습니다. ### 대소문자를 구분하지 않는 검색 지원 다음 커넥터는 `CASE_INSENSITIVE_SEARCH`를 지원합니다. + DataLake Gen2 + Snowflake + Oracle + Synapse + MySQL + PostgreSQL + Redshift + ClickHouse + SQL Server + DB2 ## 대소문자 해석기 제한 사항 대소문자 해석기 모드를 사용할 때는 다음 제한 사항에 유의하세요. + `LOWER` 모드를 사용할 때 스키마 이름과 스키마 내의 모든 테이블은 소문자여야 합니다. + `UPPER` 모드를 사용할 때 스키마 이름과 스키마 내의 모든 테이블은 대문자여야 합니다. + `CASE_INSENSITIVE_SEARCH` 사용 시 + 스키마 이름은 고유해야 합니다. + 스키마 내의 테이블 이름은 고유해야 합니다(예: "Apple"과 "APPLE"을 동시에 사용할 수 없음). + Glue 통합 제한 사항: + Glue는 소문자 이름만 지원합니다. + Lambda 함수를 GlueDataCatalog/LakeFormation에 등록할 때는 `NONE` 또는 `LOWER` 모드만 작동합니다. ## 추가 정보 + Athena 데이터 원본 커넥터 배포에 대한 자세한 내용은 [Amazon Athena 페더레이션 쿼리 사용](federated-queries.md) 단원을 참조하세요. + Athena 데이터 소스 커넥터를 사용하는 쿼리에 대한 자세한 내용은 [페더레이션 쿼리 실행](running-federated-queries.md) 섹션을 참조하세요. **Topics** + [고려 사항 및 제한 사항](#connectors-available-considerations) + [Federation SDK의 대소문자 해석기 모드](#case-resolver-modes) + [대소문자 해석기 모드에 대한 커넥터 지원](#connector-support-matrix) + [대소문자 해석기 제한 사항](#case-resolver-limitations) + [추가 정보](#connectors-available-additional-resources) + [Azure 데이터 레이크 스토리지](connectors-adls-gen2.md) + [Azure Synapse](connectors-azure-synapse.md) + [Cloudera Hive](connectors-cloudera-hive.md) + [Cloudera Impala](connectors-cloudera-impala.md) + [CloudWatch](connectors-cloudwatch.md) + [CloudWatch 지표](connectors-cwmetrics.md) + [CMDB](connectors-cmdb.md) + [Db2](connectors-ibm-db2.md) + [Db2 iSeries](connectors-ibm-db2-as400.md) + [DocumentDB](connectors-docdb.md) + [DynamoDB](connectors-dynamodb.md) + [Google BigQuery](connectors-bigquery.md) + [Google Cloud Storage](connectors-gcs.md) + [HBase](connectors-hbase.md) + [Hortonworks](connectors-hortonworks.md) + [Kafka](connectors-kafka.md) + [MSK](connectors-msk.md) + [MySQL](connectors-mysql.md) + [Neptune](connectors-neptune.md) + [OpenSearch](connectors-opensearch.md) + [Oracle](connectors-oracle.md) + [PostgreSQL](connectors-postgresql.md) + [Redis OSS](connectors-redis.md) + [Redshift](connectors-redshift.md) + [SAP HANA](connectors-sap-hana.md) + [Snowflake](connectors-snowflake.md) + [SQL Server](connectors-microsoft-sql-server.md) + [Teradata](connectors-teradata.md) + [Timestream](connectors-timestream.md) + [TPC-DS](connectors-tpcds.md) + [Vertica](connectors-vertica.md) **참고** [AthenaJdbcConnector](https://serverlessrepo.aws.amazon.com/applications/us-east-1/292517598671/AthenaJdbcConnector)(최신 버전 2022.4.1)는 더 이상 사용되지 않습니다. 대신 [MySQL](connectors-mysql.md), [Redshift](connectors-redshift.md) 또는 [PostgreSQL](connectors-postgresql.md)용 커넥터와 같은 데이터베이스 관련 커넥터를 사용하세요. # Amazon Athena Azure Data Lake Storage(ADLS) Gen2 커넥터 [Azure Data Lake Storage(ADLS) Gen2](https://docs.microsoft.com/en-us/azure/databricks/data/data-sources/azure/adls-gen2/)용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 ADLS에 저장된 데이터에 대해 SQL 쿼리를 실행할 수 있습니다. Athena는 데이터 레이크에 저장된 파일에 직접 액세스할 수 없습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. + **워크플로** - 커넥터는 `com.microsoft.sqlserver.jdbc.SQLServerDriver` 드라이버를 사용하는 JDBC 인터페이스를 구현합니다. 커넥터는 쿼리를 Azure Synapse 엔진으로 전달하고, 이 엔진에서 데이터 레이크에 액세스합니다. + **데이터 처리 및 S3** - 일반적으로 Lambda 커넥터는 Amazon S3로 전송하지 않고 직접 데이터를 쿼리합니다. 그러나 Lambda 함수에서 반환된 데이터가 Lambda 한도를 초과하면 Athena가 초과분을 읽을 수 있도록 사용자가 지정한 Amazon S3 유출 버킷에 데이터가 기록됩니다. + **AAD 인증** - AAD는 Azure Synapse 커넥터의 인증 방법으로 사용할 수 있습니다. AAD를 사용하려면 커넥터가 사용하는 JDBC 연결 문자열에 URL 파라미터 `authentication=ActiveDirectoryServicePrincipal`, `AADSecurePrincipalId`, `AADSecurePrincipalSecret`을 포함해야 합니다. 이러한 파라미터는 직접 또는 Secrets Manager에 의해 전달될 수 있습니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 필터 조건의 날짜 및 타임스탬프 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다. ## 용어 다음은 Azure Data Lake Storage Gen2 커넥터와 관련된 용어입니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Azure Data Lake Storage Gen2 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Azure Data Lake Storage Gen2 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Azure Data Lake Storage Gen2 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type DATALAKEGEN2 ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Azure Data Lake Storage Gen2 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Azure Data Lake Storage Gen2 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` datalakegentwo://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | DataLakeGen2MuxCompositeHandler | | 메타데이터 핸들러 | DataLakeGen2MuxMetadataHandler | | 레코드 핸들러 | DataLakeGen2MuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mydatalakegentwocatalog인 경우 환경 변수 이름은 mydatalakegentwocatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `datalakegentwo1`(기본값)과 `datalakegentwo2`라는 2개의 데이터베이스 인스턴스를 지원하는 DataLakeGen2 MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | datalakegentwo://jdbc:sqlserver://adlsgentwo1.hostname:port;databaseName=database\$1name;\$1\$1secret1\$1name\$1 | | datalakegentwo\$1catalog1\$1connection\$1string | datalakegentwo://jdbc:sqlserver://adlsgentwo1.hostname:port;databaseName=database\$1name;\$1\$1secret1\$1name\$1 | | datalakegentwo\$1catalog2\$1connection\$1string | datalakegentwo://jdbc:sqlserver://adlsgentwo2.hostname:port;databaseName=database\$1name;\$1\$1secret2\$1name\$1 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${secret1_name}`입니다. ``` datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=database_name;${secret1_name} ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=database_name;user=user_name;password=password ``` #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Azure Data Lake Storage Gen2 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | DataLakeGen2CompositeHandler | | 메타데이터 핸들러 | DataLakeGen2MetadataHandler | | 레코드 핸들러 | DataLakeGen2RecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Azure Data Lake Storage Gen2 인스턴스에 대한 속성 예제입니다. **** | 속성 | 값 | | --- | --- | | default | datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 ADLS Gen2와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | ADLS Gen2 | 화살표 | | --- | --- | | bit | TINYINT | | tinyint | SMALLINT | | smallint | SMALLINT | | int | INT | | bigint | BIGINT | | decimal | DECIMAL | | numeric | FLOAT8 | | smallmoney | FLOAT8 | | money | DECIMAL | | float[24] | FLOAT4 | | float[53] | FLOAT8 | | real | FLOAT4 | | datetime | Date(MILLISECOND) | | datetime2 | Date(MILLISECOND) | | smalldatetime | Date(MILLISECOND) | | 날짜 | Date(DAY) | | 시간 | VARCHAR | | datetimeoffset | Date(MILLISECOND) | | char[n] | VARCHAR | | varchar[n/max] | VARCHAR | ## 파티션 및 분할 Azure Data Lake Storage Gen2는 데이터 파일 저장을 위해 Hadoop 호환 Gen2 blob 스토리지를 사용합니다. 이러한 파일의 데이터는 Azure Synapse 엔진에서 쿼리됩니다. Azure Synapse 엔진은 파일 시스템에 저장된 Gen2 데이터를 외부 테이블로 처리합니다. 파티션은 데이터 형식에 따라 구현됩니다. 데이터가 이미 Gen 2 스토리지 시스템 내에서 분할되고 배포된 경우 커넥터는 데이터를 단일 분할로 검색합니다. ## 성능 Azure Data Lake Storage Gen2 커넥터는 한 번에 여러 쿼리를 실행할 경우 쿼리 성능이 느려지고 제한이 적용될 수 있습니다. 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Azure Data Lake Storage Gen2 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Azure Data Lake Storage Gen2 커넥터는 이러한 표현식을 결합하고 Azure Data Lake Storage Gen2로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Azure Data Lake Storage Gen2 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 패스스루 쿼리 Azure Data Lake Storage Gen2 커넥터는 [패스스루](federated-query-passthrough.md) 쿼리를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Azure Data Lake Storage Gen2에서 패스스루 쿼리를 사용하려면 다음 구문을 사용할 수 있습니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Azure Data Lake Storage Gen2에 있는 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Azure Data Lake Storage Gen2 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-datalakegen2)를 참조하세요. # Amazon Athena Azure Synapse 커넥터 [Azure Synapse Analytics](https://docs.microsoft.com/en-us/azure/synapse-analytics/overview-what-is)용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 JDBC를 사용하여 Azure Synapse 데이터베이스에 대해 SQL 쿼리를 실행할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 필터 조건에서 `Date` 및 `Timestamp` 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다. + `Real` 및 `Float` 형식의 음수 값을 검색하려면 `<=` 또는 `>=` 연산자를 사용합니다. + `binary`, `varbinary`, `image` 및 `rowversion` 데이터 형식은 지원되지 않습니다. ## 용어 다음 용어는 Synapse 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Synapse 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Synapse 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Synapse 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type SYNAPSE ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Synapse 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Synapse 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결(권장) #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` synapse://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | SynapseMuxCompositeHandler | | 메타데이터 핸들러 | SynapseMuxMetadataHandler | | 레코드 핸들러 | SynapseMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mysynapsecatalog인 경우 환경 변수 이름은 mysynapsecatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `synapse1`(기본값)과 `synapse2`라는 2개의 데이터베이스 인스턴스를 지원하는 Synapse MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 | | synapse\$1catalog1\$1connection\$1string | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 | | synapse\$1catalog2\$1connection\$1string | synapse://jdbc:synapse://synapse2.hostname:port;databaseName=;\$1\$1secret2\$1name\$1 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 \$1\$1secret\$1name\$1입니다. ``` synapse://jdbc:synapse://hostname:port;databaseName=;${secret_name} ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` synapse://jdbc:synapse://hostname:port;databaseName=;user=;password= ``` #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Synapse 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | SynapseCompositeHandler | | 메타데이터 핸들러 | SynapseMetadataHandler | | 레코드 핸들러 | SynapseRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Synapse 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | synapse://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 | #### Active Directory 인증 구성 Amazon Athena Azure Synapse 커넥터는 Microsoft Active Directory 인증을 지원합니다. 시작하기 전에 먼저 Microsoft Azure 포털에서 관리 사용자를 구성한 다음 AWS Secrets Manager를 사용하여 보안 암호를 생성해야 합니다. **Active Directory 관리 사용자를 설정하려면** 1. 관리자 권한이 있는 계정을 사용하여 Microsoft Azure 포털([https://portal.azure.com/](https://portal.azure.com/))에 로그인합니다. 1. 검색 상자에 **Azure Synapse Analytics**를 입력한 다음 **Azure Synapse Analytics**를 선택합니다. ![\[Azure Synapse Analytics를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-azure-synapse-1.png) 1. 왼쪽의 메뉴를 엽니다. ![\[Azure 포털 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-azure-synapse-2.png) 1. 탐색 창에서 **Azure Active Directory**를 선택합니다. 1. **Set admin** 탭에서 **Active Directory admin**을 새 사용자 또는 기존 사용자로 설정합니다. ![\[Set admin 탭 사용\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-azure-synapse-3.png) 1. AWS Secrets Manager에 관리 사용자 이름과 암호 보안 인증을 저장합니다. Secrets Manager에서 보안 암호를 생성하는 방법에 대한 자세한 내용은 [AWS Secrets Manager 보안 암호 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)을 참조하세요. **Secrets Manager에서 보안 암호를 보려면** 1. [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)에서 Secrets Manager 콘솔을 엽니다. 1. 탐색 창에서 **Secrets**(보안 암호)를 선택합니다. 1. **Secrets**(보안 암호) 페이지에서 보안 암호에 대한 링크를 선택합니다. 1. 보안 암호에 대한 세부 정보 페이지에서 **Retrieve secret value**(보안 암호 값 검색)를 선택합니다. ![\[AWS Secrets Manager에서 보안 암호를 확인합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-azure-synapse-4.png) ##### 연결 문자열 수정 커넥터에 대해 Active Directory 인증을 활성화하려면 다음 구문을 사용하여 연결 문자열을 수정합니다. ``` synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryPassword;{secret_name} ``` ##### ActiveDirectoryServicePrincipal 사용 Amazon Athena Azure Synapse 커넥터는 `ActiveDirectoryServicePrincipal`도 지원합니다. 이를 활성화하려면 다음과 같이 연결 문자열을 수정합니다. ``` synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryServicePrincipal;{secret_name} ``` `secret_name`의 경우 애플리케이션 또는 클라이언트 ID를 사용자 이름으로, 암호에 서비스 보안 주체 ID의 암호를 지정합니다. #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 Synapse와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | Synapse | 화살표 | | --- | --- | | bit | TINYINT | | tinyint | SMALLINT | | smallint | SMALLINT | | int | INT | | bigint | BIGINT | | decimal | DECIMAL | | numeric | FLOAT8 | | smallmoney | FLOAT8 | | money | DECIMAL | | float[24] | FLOAT4 | | float[53] | FLOAT8 | | real | FLOAT4 | | datetime | Date(MILLISECOND) | | datetime2 | Date(MILLISECOND) | | smalldatetime | Date(MILLISECOND) | | 날짜 | Date(DAY) | | 시간 | VARCHAR | | datetimeoffset | Date(MILLISECOND) | | char[n] | VARCHAR | | varchar[n/max] | VARCHAR | | nchar[n] | VARCHAR | | nvarchar[n/max] | VARCHAR | ## 파티션 및 분할 파티션은 `varchar` 형식의 단일 파티션 열로 표시됩니다. Synapse는 범위 파티셔닝을 지원하므로 파티셔닝은 Synapse 메타데이터 테이블에서 파티션 열과 파티션 범위를 추출하여 구현됩니다. 이러한 범위 값은 분할을 생성하는 데 사용됩니다. ## 성능 열 하위 집합을 선택하면 쿼리 런타임이 크게 느려집니다. 이 커넥터는 동시성으로 인해 상당한 제한을 나타냅니다. 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Synapse 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Synapse 커넥터는 이러한 표현식을 결합하고 Synapse로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Synapse 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 패스스루 쿼리 Synapse 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Synapse에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Synapse의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 + Quick 및 Amazon Athena 페더레이션 쿼리를 사용하여 Microsoft Azure Synapse 데이터베이스에 저장된 데이터에 대한 시각화와 대시보드를 작성하는 방법을 설명하는 문서는 *AWS Big Data Blog*의 [Perform multi-cloud analytics using Quick, Amazon Athena Federated Query, and Microsoft Azure Synapse](https://aws.amazon.com/blogs/business-intelligence/perform-multi-cloud-analytics-using-amazon-quicksight-amazon-athena-federated-query-and-microsoft-azure-synapse/)를 참조하세요. + 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Synapse 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/pom.xml) 파일을 참조하세요. + 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-synapse)를 참조하세요. # Amazon Athena Cloudera Hive 커넥터 Cloudera Hive용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 [Cloudera Hive](https://www.cloudera.com/products/open-source/apache-hadoop/apache-hive.html) Hadoop 배포에 대해 SQL 쿼리를 실행할 수 있습니다. 커넥터는 Athena SQL 쿼리를 동일한 HiveQL 구문으로 변환합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. + 이 커넥터를 사용하기 전에 VPC와 보안 그룹을 설정합니다. 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. ## 용어 다음 용어는 Cloudera Hive 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Cloudera Hive 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Cloudera Hive 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Cloudera Hive 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type CLOUDERAHIVE ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Cloudera Hive 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Cloudera Hive 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` hive://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | HiveMuxCompositeHandler | | 메타데이터 핸들러 | HiveMuxMetadataHandler | | 레코드 핸들러 | HiveMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 myhivecatalog인 경우 환경 변수 이름은 myhivecatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `hive1`(기본값)과 `hive2`라는 2개의 데이터베이스 인스턴스를 지원하는 Hive MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | hive://jdbc:hive2://hive1:10000/default;\$1\$1Test/RDS/hive1\$1 | | hive2\$1catalog1\$1connection\$1string | hive://jdbc:hive2://hive1:10000/default;\$1\$1Test/RDS/hive1\$1 | | hive2\$1catalog2\$1connection\$1string | hive://jdbc:hive2://hive2:10000/default;UID=sample&PWD=sample | ##### 보안 인증 정보 제공 JDBC 연결 문자열에서 데이터베이스에 대한 사용자 이름과 암호를 제공하려면 Cloudera Hive 커넥터에 AWS Secrets Manager 보안 암호가 필요합니다. AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Lambda 함수에 연결된 VPC에 Secrets Manager에 연결할 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) 가 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력합니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/RDS/hive1}`입니다. ``` hive://jdbc:hive2://hive1:10000/default;...&${Test/RDS/hive1}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` hive://jdbc:hive2://hive1:10000/default;...&UID=sample2&PWD=sample2&... ``` 현재 Cloudera Hive 커넥터는 `UID` 및 `PWD` JDBC 속성을 인식합니다. #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Cloudera Hive 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | HiveCompositeHandler | | 메타데이터 핸들러 | HiveMetadataHandler | | 레코드 핸들러 | HiveRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Cloudera Hive 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | 기본값 | hive://jdbc:hive2://hive1:10000/default;secret=\$1\$1Test/RDS/hive1\$1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC, Cloudera Hive 및 Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | Cloudera Hive | 화살표 | | --- | --- | --- | | 부울 | 부울 | Bit | | Integer | TINYINT | Tiny | | Short | SMALLINT | Smallint | | Integer | INT | 정수 | | Long | BIGINT | Bigint | | 실수 | float4 | Float4 | | 배정밀도 실수 | float8 | Float8 | | 날짜 | 날짜 | DateDay | | 타임스탬프 | timestamp | DateMilli | | 문자열 | VARCHAR | Varchar | | 바이트 | bytes | Varbinary | | BigDecimal | 10진수 | 10진수 | | ARRAY | 해당 사항 없음(참고 사항 참조) | List | **참고** 현재 Cloudera Hive는 집계 유형 `ARRAY`, `MAP`, `STRUCT` 또는 `UNIONTYPE`을 지원하지 않습니다. 집계 유형의 열은 SQL에서 `VARCHAR` 열로 처리됩니다. ## 파티션 및 분할 파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다. ## 성능 Cloudera Hive는 정적 파티션을 지원합니다. Athena Cloudera Hive 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 정적 파티셔닝을 사용하는 것이 좋습니다. Cloudera Hive 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. Athena Cloudera Hive 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Cloudera Hive 커넥터는 이러한 표현식을 결합하고 Cloudera Hive로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Cloudera Hive 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 패스스루 쿼리 Cloudera Hive 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Cloudera Hive에서 패스스루 쿼리를 사용하려면 다음 구문을 사용할 수 있습니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Cloudera Hive의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Cloudera Hive 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudera-hive)를 참조하세요. # Amazon Athena Cloudera Impala 커넥터 Amazon Athena Cloudera Impala 커넥터를 사용하면 Amazon Athena가 [Cloudera Impala](https://docs.cloudera.com/cdw-runtime/cloud/impala-overview/topics/impala-overview.html) 배포에 대해 SQL 쿼리를 실행할 수 있습니다. 커넥터는 Athena SQL 쿼리를 동일한 Impala 구문으로 변환합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. + 이 커넥터를 사용하기 전에 VPC와 보안 그룹을 설정합니다. 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. ## 용어 다음 용어는 Cloudera Impala 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Cloudera Impala 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Cloudera Impala 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Cloudera Impala 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type CLOUDERAIMPALA ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Cloudera Impala 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Cloudera Impala 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 Impala 클러스터에 연결합니다. ``` impala://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | ImpalaMuxCompositeHandler | | 메타데이터 핸들러 | ImpalaMuxMetadataHandler | | 레코드 핸들러 | ImpalaMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. Athena 카탈로그에 대한 Impala 클러스터 연결 문자열입니다. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 myimpalacatalog인 경우 환경 변수 이름은 myimpalacatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `impala1`(기본값)과 `impala2`라는 2개의 데이터베이스 인스턴스를 지원하는 Impala MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | impala://jdbc:impala://some.impala.host.name:21050/?\$1\$1Test/impala1\$1 | | impala\$1catalog1\$1connection\$1string | impala://jdbc:impala://someother.impala.host.name:21050/?\$1\$1Test/impala1\$1 | | impala\$1catalog2\$1connection\$1string | impala://jdbc:impala://another.impala.host.name:21050/?UID=sample&PWD=sample | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/impala1host}`입니다. ``` impala://jdbc:impala://Impala1host:21050/?...&${Test/impala1host}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` impala://jdbc:impala://Impala1host:21050/?...&UID=sample2&PWD=sample2&... ``` 현재 Cloudera Impala는 `UID` 및 `PWD` JDBC 속성을 인식합니다. #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Cloudera Impala 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | ImpalaCompositeHandler | | 메타데이터 핸들러 | ImpalaMetadataHandler | | 레코드 핸들러 | ImpalaRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Cloudera Impala 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | impala://jdbc:impala://Impala1host:21050/?secret=\$1\$1Test/impala1host\$1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC, Cloudera Impala 및 Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | Cloudera Impala | 화살표 | | --- | --- | --- | | 부울 | 부울 | Bit | | Integer | TINYINT | Tiny | | Short | SMALLINT | Smallint | | Integer | INT | 정수 | | Long | BIGINT | Bigint | | 실수 | float4 | Float4 | | 배정밀도 실수 | float8 | Float8 | | 날짜 | 날짜 | DateDay | | 타임스탬프 | timestamp | DateMilli | | 문자열 | VARCHAR | Varchar | | 바이트 | bytes | Varbinary | | BigDecimal | 10진수 | 10진수 | | ARRAY | 해당 사항 없음(참고 사항 참조) | List | **참고** 현재 Cloudera Impala는 집계 유형 `ARRAY`, `MAP`, `STRUCT` 또는 `UNIONTYPE`을 지원하지 않습니다. 집계 유형의 열은 SQL에서 `VARCHAR` 열로 처리됩니다. ## 파티션 및 분할 파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다. ## 성능 Cloudera Impala는 정적 파티션을 지원합니다. Athena Cloudera Impala 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 정적 파티셔닝을 사용하는 것이 좋습니다. Cloudera Impala 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. Athena Cloudera Impala 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Cloudera Impala 커넥터는 이러한 표현식을 결합하고 Cloudera Impala로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Cloudera Impala 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 패스스루 쿼리 Cloudera Impala 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Cloudera Impala에서 패스스루 쿼리를 사용하려면 다음 구문을 사용할 수 있습니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Cloudera Impala의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Cloudera Impala 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudera-impala)를 참조하세요. # Amazon Athena CloudWatch 커넥터 Amazon Athena CloudWatch 커넥터를 통해 Amazon Athena는 CloudWatch와 통신할 수 있고, 이로써 SQL을 사용하여 로그 데이터를 쿼리할 수 있습니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. 커넥터는 LoggRoups를 스키마로 매핑하고 각 LogStream을 테이블로 매핑합니다. 또한 커넥터는 LogGroup에 모든 LogStream을 포함하는 특별 `all_log_streams` 뷰도 매핑합니다. 이 뷰를 사용하면 각 LogStream을 개별적으로 검색하는 대신 LogGroup의 모든 로그를 한 번에 쿼리할 수 있습니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 CloudWatch 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 CloudWatch 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 CloudWatch 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type CLOUDWATCH ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 CloudWatch 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 CloudWatch 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. 또한 커넥터는 [Amazon Athena Query Federation SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) `ThrottlingInvoker` 생성자를 통해 CloudWatch의 조절 이벤트를 처리하기 위한 [AIMD 정체 제어](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)를 지원합니다. 다음 선택적 환경 변수를 설정하여 기본 제한 동작을 조정할 수 있습니다. + **throttle\$1initial\$1delay\$1ms** – 첫 번째 혼잡 이벤트 이후에 적용된 초기 호출 지연입니다. 기본값은 10밀리초입니다. + **throttle\$1max\$1delay\$1ms** – 호출 간의 최대 지연입니다. TPS를 1000ms로 나누어 도출할 수 있습니다. 기본값은 1,000밀리초입니다. + **throttle\$1decrease\$1factor** – Athena가 호출 속도를 줄이는 비율입니다. 기본값은 0.5입니다. + **throttle\$1increase\$1ms** – Athena가 호출 지연을 줄이는 속도입니다. 기본값은 10밀리초입니다. ## 데이터베이스 및 테이블 Athena CloudWatch 커넥터는 LoggRoups를 스키마 즉, 데이터베이스로 매핑하고 각 LogStream을 테이블로 매핑합니다. 또한 커넥터는 LogGroup에 모든 LogStream을 포함하는 특별 `all_log_streams` 뷰도 매핑합니다. 이 뷰를 사용하면 각 LogStream을 개별적으로 검색하는 대신 LogGroup의 모든 로그를 한 번에 쿼리할 수 있습니다. Athena CloudWatch 커넥터에 의해 매핑된 모든 테이블에는 다음 스키마가 있습니다. 이 스키마는 CloudWatch Logs에서 제공하는 필드와 일치합니다. + **log\$1stream** – 행이 출처인 LogStream의 이름을 포함하는 `VARCHAR`입니다. + **time** – 로그 라인이 생성된 시점의 epoch 시간을 포함하는 `INT64`입니다. + **message** – 로그 메시지를 포함하는 `VARCHAR`입니다. **예제** 다음 예제에서는 지정된 LogStream에 대해 `SELECT` 쿼리를 수행하는 방법을 보여줍니다. ``` SELECT * FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."log_stream_name" LIMIT 100 ``` 다음 예제에서는 `all_log_streams` 보기를 사용하여 지정된 LogGroup의 모든 LogStreams에 대해 쿼리를 수행하는 방법을 보여줍니다. ``` SELECT * FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."all_log_streams" LIMIT 100 ``` ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-cloudwatch.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch/athena-cloudwatch.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. + **CloudWatch Logs 읽기/쓰기** – 커넥터는 이 권한을 사용하여 로그 데이터를 읽고 진단 로그를 작성합니다. ## 성능 Athena CloudWatch 커넥터는 쿼리에 필요한 로그 스트림 스캔을 병렬화하여 CloudWatch에 대한 쿼리를 최적화하려고 시도합니다. 특정 기간 필터에 대해 조건자 푸시다운은 Lambda 함수와 CloudWatch Logs 내에서 모두 수행됩니다. 최상의 성능을 얻으려면 로그 그룹 이름과 로그 스트림 이름에 소문자만 사용합니다. 대/소문자를 혼합하여 사용하면 커넥터에서 대소문자를 구분하지 않고 검색하므로 더욱 컴퓨팅 집약적입니다. **참고** CloudWatch 커넥터는 대문자 데이터베이스 이름을 지원하지 않습니다. ## 패스스루 쿼리 CloudWatch 커넥터는 [CloudWatch Logs Insights 쿼리 구문](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)을 사용하는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. CloudWatch Logs Insights에 대한 자세한 내용은 Amazon CloudWatch Logs 사용 설명서에서 [CloudWatch Logs Insights를 사용하여 로그 데이터 분석하기](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html)를 참조하세요. CloudWatch에서 패스스루 쿼리를 생성하려면 다음 구문을 사용하세요. ``` SELECT * FROM TABLE( system.query( STARTTIME => 'start_time', ENDTIME => 'end_time', QUERYSTRING => 'query_string', LOGGROUPNAMES => 'log_group-names', LIMIT => 'max_number_of_results' )) ``` 다음 예제 CloudWatch 패스스루 쿼리는 필드가 1000이 아닐 때 `duration` 필드를 필터링합니다. ``` SELECT * FROM TABLE( system.query( STARTTIME => '1710918615308', ENDTIME => '1710918615972', QUERYSTRING => 'fields @duration | filter @duration != 1000', LOGGROUPNAMES => '/aws/lambda/cloudwatch-test-1', LIMIT => '2' )) ``` ## 라이선스 정보 Amazon Athena CloudWatch 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch)를 참조하세요. # Amazon Athena CloudWatch 지표 커넥터 Amazon Athena CloudWatch 지표 커넥터를 사용하면 Amazon Athena에서 SQL로 CloudWatch 지표 데이터를 쿼리할 수 있습니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. Athena 자체에서 CloudWatch에 쿼리 지표를 게시하는 방법에 대한 자세한 내용은 [CloudWatch 및 EventBridge를 사용하여 쿼리 모니터링 및 비용 제어](workgroups-control-limits.md) 섹션을 참조하세요. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 CloudWatch Metrics 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 CloudWatch Metrics 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 CloudWatch Metrics 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type CLOUDWATCHMETRICS ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 CloudWatch Metrics 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 CloudWatch Metrics 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. 또한 커넥터는 [Amazon Athena Query Federation SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) `ThrottlingInvoker` 생성자를 통해 CloudWatch의 조절 이벤트를 처리하기 위한 [AIMD 정체 제어](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)를 지원합니다. 다음 선택적 환경 변수를 설정하여 기본 제한 동작을 조정할 수 있습니다. + **throttle\$1initial\$1delay\$1ms** – 첫 번째 혼잡 이벤트 이후에 적용된 초기 호출 지연입니다. 기본값은 10밀리초입니다. + **throttle\$1max\$1delay\$1ms** – 호출 간의 최대 지연입니다. TPS를 1000ms로 나누어 도출할 수 있습니다. 기본값은 1,000밀리초입니다. + **throttle\$1decrease\$1factor** – Athena가 호출 속도를 줄이는 비율입니다. 기본값은 0.5입니다. + **throttle\$1increase\$1ms** – Athena가 호출 지연을 줄이는 속도입니다. 기본값은 10밀리초입니다. ## 데이터베이스 및 테이블 Athena CloudWatch 지표 커넥터는 네임스페이스, 차원, 지표 및 지표 값을 `default`라는 단일 스키마의 두 테이블에 매핑합니다. ### 지표 테이블 `metrics` 테이블에는 네임스페이스, 세트 및 이름의 조합으로 고유하게 정의된 사용 가능한 지표가 포함됩니다. `metrics` 테이블에는 다음 열이 있습니다. + **namespace** – 네임스페이스를 포함하는 `VARCHAR`입니다. + **metric\$1name** – 지표 이름을 포함하는 `VARCHAR`입니다. + **dimensions** – `dim_name (VARCHAR)` 및 `dim_value (VARCHAR)`로 구성된 `STRUCT` 객체의 `LIST`입니다. + **statistic** – 지표에 사용할 수 있는 `VARCH` 통계의 `LIST`입니다(예: `p90`, `AVERAGE` 등). ### metric\$1samples 테이블 `metric_samples` 테이블에는 `metrics` 테이블의 각 지표에 대해 사용 가능한 지표 샘플이 포함되어 있습니다. `metric_samples` 테이블에는 다음 열이 있습니다. + **namespace** – 네임스페이스를 포함하는 `VARCHAR`입니다. + **metric\$1name** – 지표 이름을 포함하는 `VARCHAR`입니다. + **dimensions** – `dim_name (VARCHAR)` 및 `dim_value (VARCHAR)`로 구성된 `STRUCT` 객체의 `LIST`입니다. + **dim\$1name** – 단일 차원 이름을 쉽게 필터링하는 데 사용할 수 있는 `VARCHAR` 편의 필드입니다. + **dim\$1value** – 단일 차원 값을 쉽게 필터링하는 데 사용할 수 있는 `VARCHAR` 편의 필드입니다. + **period** – 지표의 '기간'을 초 단위로 나타내는 `INT` 필드입니다(예: 60초 지표). + **timestamp** – 지표 샘플의 epoch 시간(초)을 나타내는 `BIGINT` 필드입니다. + **value** – 샘플 값을 포함하는 `FLOAT8` 필드입니다. + **statistic** – 샘플의 통계 유형을 포함하는 `VARCHAR`입니다(예: `AVERAGE` 또는 `p90`). ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-cloudwatch-metrics.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch-metrics/athena-cloudwatch-metrics.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. + **CloudWatch 지표 읽기 전용** – 커넥터는 이 권한을 사용하여 지표 데이터를 쿼리합니다. + **CloudWatch Logs 쓰기** - 커넥터는 이 액세스 권한을 사용하여 진단 로그를 작성합니다. ## 성능 Athena CloudWatch 지표 커넥터는 쿼리에 필요한 로그 스트림 스캔을 병렬화하여 CloudWatch 지표에 대한 쿼리를 최적화하려고 시도합니다. 특정 기간, 지표, 네임스페이스 및 차원 필터에 대해 조건자 푸시다운은 Lambda 함수와 CloudWatch Logs 내에서 모두 수행됩니다. ## 라이선스 정보 Amazon Athena CloudWatch 지표 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch-metrics)를 참조하세요. # Amazon Athena AWS CMDB 커넥터 Amazon Athena AWS CMDB 커넥터를 통해 Athena는 다양한 AWS 서비스와 통신할 수 있고, 이로써 SQL을 사용하여 쿼리할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md)을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 AWS CMDB 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 AWS CMDB 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 AWS CMDB 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type CMDB ``` **Lambda 환경 속성** **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 AWS CMDB 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 AWS CMDB 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. **Lambda 환경 속성** + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **default\$1ec2\$1image\$1owner** – (선택 사항) 설정하면 [Amazon Machine Image(AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)를 필터링하는 기본 Amazon EC2 이미지 소유자를 제어합니다. 이 값을 설정하지 않고 EC2 이미지 테이블에 대한 쿼리에 소유자 필터가 포함되어 있지 않으면 결과에 모든 공개 이미지가 포함됩니다. ## 데이터베이스 및 테이블 Athena AWS CMDB 커넥터를 통해 AWS 리소스 인벤토리를 쿼리하는 데 다음 데이터베이스와 테이블을 사용할 수 있습니다. 각 테이블에서 사용 가능한 열에 대한 자세한 내용을 보려면 Athena 콘솔 또는 API를 사용하여 `DESCRIBE database.table` 문을 실행합니다. + **ec2** – 이 데이터베이스는 다음을 비롯한 Amazon EC2 관련 리소스를 포함합니다. + **ebs\$1volumes** – Amazon EBS 볼륨의 세부 정보를 포함합니다. + **ec2\$1instances** – EC2 인스턴스의 세부 정보를 포함합니다. + **ec2\$1images** – EC2 인스턴스 이미지의 세부 정보를 포함합니다. + **routing\$1tables** – VPC 라우팅 테이블의 세부 정보를 포함합니다. + **security\$1groups** – 보안 그룹의 세부 정보를 포함합니다. + **subnets** – VPC 서브넷의 세부 정보를 포함합니다. + **vpcs** – VPC의 세부 정보를 포함합니다. + **emr** – 이 데이터베이스는 다음을 비롯한 Amazon EMR 관련 리소스를 포함합니다. + **emr\$1clusters** – EMR 클러스터의 세부 정보를 포함합니다. + **rds** – 이 데이터베이스는 다음을 비롯한 Amazon RDS 관련 리소스를 포함합니다. + **rds\$1instances** – RDS 인스턴스의 세부 정보를 포함합니다. + **s3** – 이 데이터베이스는 다음을 비롯한 RDS 관련 리소스를 포함합니다. + **buckets** – Amazon S3 버킷의 세부 정보를 포함합니다. + **objects** – 콘텐츠를 제외한 Amazon S3 객체의 세부 정보를 포함합니다. ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-aws-cmdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-aws-cmdb/athena-aws-cmdb.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. + **S3 List** – 커넥터는 이 권한을 사용하여 Amazon S3 버킷 및 객체를 나열합니다. + **EC2 Describe** – 커넥터는 이 권한을 사용하여 Amazon EC2 인스턴스, 보안 그룹, VPC 및 Amazon EBS 볼륨과 같은 리소스를 설명합니다. + **EMR Describe/List** – 커넥터는 이 권한을 사용하여 EMR 클러스터를 설명합니다. + **RDS Describe** – 커넥터는 이 권한을 사용하여 RDS 인스턴스를 설명합니다. ## 성능 현재 Athena AWS CMDB 커넥터는 병렬 스캔을 지원하지 않습니다. 조건자 푸시다운은 Lambda 함수 내에서 수행됩니다. 가능한 경우 부분 조건자는 쿼리 중인 서비스로 푸시됩니다. 예를 들어, 특정 Amazon EC2 인스턴스의 세부 정보에 대한 쿼리는 특정 인스턴스 ID로 EC2 API를 호출하여 대상 설명 작업을 실행합니다. ## 라이선스 정보 Amazon Athena AWS CMDB 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-aws-cmdb)를 참조하세요. # Amazon Athena IBM Db2 커넥터 Db2용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 JDBC를 사용하여 IBM Db2 데이터베이스에 대해 SQL 쿼리를 실행할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. + 이 커넥터를 사용하기 전에 VPC와 보안 그룹을 설정합니다. 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 필터 조건의 날짜 및 타임스탬프 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다. ## 용어 다음 용어는 Db2 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Db2 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Db2 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Db2 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type DB2 ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Db2 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Db2 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` dbtwo://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | Db2MuxCompositeHandler | | 메타데이터 핸들러 | Db2MuxMetadataHandler | | 레코드 핸들러 | Db2MuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mydbtwocatalog인 경우 환경 변수 이름은 mydbtwocatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `dbtwo1`(기본값)과 `dbtwo2`라는 2개의 데이터베이스 인스턴스를 지원하는 Db2 MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | dbtwo://jdbc:db2://dbtwo1.hostname:port/database\$1name:\$1\$1secret1\$1name\$1 | | dbtwo\$1catalog1\$1connection\$1string | dbtwo://jdbc:db2://dbtwo1.hostname:port/database\$1name:\$1\$1secret1\$1name\$1 | | dbtwo\$1catalog2\$1connection\$1string | dbtwo://jdbc:db2://dbtwo2.hostname:port/database\$1name:\$1\$1secret2\$1name\$1 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${secret_name}`입니다. ``` dbtwo://jdbc:db2://hostname:port/database_name:${secret_name} ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` dbtwo://jdbc:db2://hostname:port/database_name:user=user_name;password=password; ``` #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Db2 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | Db2CompositeHandler | | 메타데이터 핸들러 | Db2MetadataHandler | | 레코드 핸들러 | Db2RecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Db2 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | dbtwo://jdbc:db2://hostname:port/database\$1name:\$1\$1secret\$1name\$1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC와 Arrow의 해당 데이터 형식이 나와 있습니다. **** | Db2 | 화살표 | | --- | --- | | CHAR | VARCHAR | | VARCHAR | VARCHAR | | DATE | DATEDAY | | TIME | VARCHAR | | TIMESTAMP | DATEMILLI | | DATETIME | DATEMILLI | | BOOLEAN | BOOL | | SMALLINT | SMALLINT | | INTEGER | INT | | BIGINT | BIGINT | | DECIMAL | DECIMAL | | REAL | FLOAT8 | | DOUBLE | FLOAT8 | | DECFLOAT | FLOAT8 | ## 파티션 및 분할 파티션은 하나 이상의 `varchar` 형식 파티션 열로 표시됩니다. Db2 커넥터는 다음 조직 체계를 사용하여 파티션을 생성합니다. + 해시별 배포 + 범위별 파티션 + 차원별 구성 커넥터는 하나 이상의 Db2 메타데이터 테이블에서 파티션 수, 열 이름과 같은 파티션 세부 정보를 검색합니다. 분할은 식별된 파티션 수를 기준으로 생성됩니다. ## 성능 Athena Db2 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Db2 커넥터는 이러한 표현식을 결합하고 Db2로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Db2 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 패스스루 쿼리 Db2 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Db2에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Db2의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Db2 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-db2)를 참조하세요. # Amazon Athena IBM Db2 AS/400(Db2 iSeries) 커넥터 Db2 AS/400용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 JDBC를 사용하여 IBM Db2 AS/400(Db2 iSeries) 데이터베이스에 대해 SQL 쿼리를 실행할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. + 이 커넥터를 사용하기 전에 VPC와 보안 그룹을 설정합니다. 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 필터 조건의 날짜 및 타임스탬프 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다. ## 용어 다음 용어는 Db2 AS/400 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Db2 AS/400 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Db2 AS/400 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Db2 AS/400 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type DB2AS400 ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Db2 AS/400 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Db2 AS/400 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` db2as400://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | Db2MuxCompositeHandler | | 메타데이터 핸들러 | Db2MuxMetadataHandler | | 레코드 핸들러 | Db2MuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mydb2as400catalog인 경우 환경 변수 이름은 mydb2as400catalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `db2as4001`(기본값)과 `db2as4002`라는 2개의 데이터베이스 인스턴스를 지원하는 Db2 MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | db2as400://jdbc:as400://;;:\$1\$1\$1; | | db2as400\$1catalog1\$1connection\$1string | db2as400://jdbc:as400://db2as4001.hostname/:\$1\$1secret1\$1name\$1 | | db2as400\$1catalog2\$1connection\$1string | db2as400://jdbc:as400://db2as4002.hostname/:\$1\$1secret2\$1name\$1 | | db2as400\$1catalog3\$1connection\$1string | db2as400://jdbc:as400://;user=;password=;; | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${secret_name}`입니다. ``` db2as400://jdbc:as400://;;:${}; ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` db2as400://jdbc:as400://;user=;password=;; ``` #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Db2 AS/400 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | Db2CompositeHandler | | 메타데이터 핸들러 | Db2MetadataHandler | | 레코드 핸들러 | Db2RecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Db2 AS/400 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | db2as400://jdbc:as400://;;:\$1\$1\$1; | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | Db2 AS/400 | 화살표 | | --- | --- | | CHAR | VARCHAR | | VARCHAR | VARCHAR | | DATE | DATEDAY | | TIME | VARCHAR | | TIMESTAMP | DATEMILLI | | DATETIME | DATEMILLI | | BOOLEAN | BOOL | | SMALLINT | SMALLINT | | INTEGER | INT | | BIGINT | BIGINT | | DECIMAL | DECIMAL | | REAL | FLOAT8 | | DOUBLE | FLOAT8 | | DECFLOAT | FLOAT8 | ## 파티션 및 분할 파티션은 하나 이상의 `varchar` 형식 파티션 열로 표시됩니다. Db2 AS/400 커넥터는 다음 구성 체계를 사용하여 파티션을 생성합니다. + 해시별 배포 + 범위별 파티션 + 차원별 구성 커넥터는 하나 이상의 Db2 AS/400 메타데이터 테이블에서 파티션 수, 열 이름과 같은 파티션 세부 정보를 검색합니다. 분할은 식별된 파티션 수를 기준으로 생성됩니다. ## 성능 성능 개선을 위해 다음 예제와 같이 조건자 푸시다운을 사용하여 Athena에서 쿼리합니다. ``` SELECT * FROM "lambda:".""."" WHERE integercol = 2147483647 ``` ``` SELECT * FROM "lambda: ".""."" WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878' ``` ## 패스스루 쿼리 Db2 AS/400 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Db2 AS/400에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Db2 AS/400의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Db2 AS/400 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-db2-as400)를 참조하세요. # 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에 대한 읽기 액세스 권한을 가지고 있어야 합니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 DocumentDB 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 DocumentDB 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 DocumentDB 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type DOCUMENTDB ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 DocumentDB 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 DocumentDB 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **disable\$1glue** – (선택 사항) true로 설정된 경우 커넥터는 AWS Glue에서 보충 메타데이터 검색을 시도하지 않습니다. + **glue\$1catalog** – (선택 사항) 이 옵션을 사용하여 [크로스 계정 AWS Glue 카탈로그](data-sources-glue-cross-account.md)를 지정합니다. 기본적으로 커넥터는 자체 AWS Glue 계정에서 메타데이터를 가져오려고 시도합니다. + **default\$1docdb** – 있는 경우 카탈로그 관련 환경 변수가 없을 때 사용할 DocumentDB 연결 문자열을 지정합니다. + **disable\$1projection\$1and\$1casing** – (선택 사항) 프로젝션과 대/소문자를 비활성화합니다. 대/소문자를 구분하는 열 이름을 사용하는 Amazon DocumentDB 테이블을 쿼리하려는 경우에 사용합니다. `disable_projection_and_casing` 파라미터는 다음 값을 사용하여 대/소문자 및 열 매핑의 동작을 지정합니다. + **false** – 기본 설정입니다. 프로젝션이 활성화되며, 커넥터에서는 모든 열 이름을 소문자로 예상합니다. + **true** - 프로젝션과 대/소문자 구분을 비활성화합니다. `disable_projection_and_casing` 파라미터를 사용할 때는 다음 사항에 유의하세요. + 파라미터를 사용하면 대역폭 사용량이 증가할 수 있습니다. 또한 Lambda 함수가 데이터 소스와 동일한 AWS 리전에 있지 않을 경우 대역폭 사용량이 증가하여 더 높은 표준 AWS 리전 간 전송 비용이 청구됩니다. 리전 간 전송 비용에 대한 자세한 내용은 AWS 파트너 네트워크 블로그의 [서버 및 서버리스 아키텍처에 대한 AWS 데이터 전송 요금](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)을 참조하세요. + 더 많은 수의 바이트가 전송되고 더 많은 수의 바이트가 더 많은 역직렬화 시간을 필요로 하기 때문에 전체 지연 시간이 늘어날 수 있습니다. + **enable\$1case\$1insensitive\$1match** - (선택 사항) `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 연결을 위한 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) 또는 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)가 Lambda 함수에 연결된 VPC에 있어야 합니다. `${my_secret}` 구문을 사용하여 연결 문자열에 Secrets Manager의 보안 암호 이름을 입력하는 경우 커넥터는 `${my_secret}`을 Secrets Manager의 일반 텍스트 값으로 정확하게 바꿉니다. 보안 암호는 `:` 값을 가진 일반 텍스트 보안 암호로 저장되어야 합니다 `{username:,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에서 찾을 수 없는 보안 암호 이름을 지정하면 커넥터가 텍스트를 바꾸지 않습니다. ## 보충 메타데이터 검색 보충 메타데이터를 검색하려면 다음 단계에 따라 Glue 데이터베이스 및 테이블을 구성합니다. ### Glue 데이터베이스 설정 1. DocumentDB 컬렉션과 이름이 동일한 Glue 데이터베이스를 생성합니다. 1. 위치 URI 필드에 `docdb-metadata-flag`를 입력합니다. ### Glue 테이블 구성 Glue 테이블에 다음 파라미터를 추가합니다. + `docdb-metadata-flag = true` + `columnMapping = apple=APPLE` 이 예제에서 `apple`은 Glue의 소문자 열 이름을 나타내고 `APPLE`은 DocumentDB 컬렉션의 실제 대소문자 구분 열 이름을 나타냅니다. ### 메타데이터 검색 확인 1. 쿼리를 실행합니다. 1. Lambda 함수의 CloudWatch 로그에서 메타데이터 검색이 성공했는지 확인합니다. 검색이 성공하면 다음 로그 항목이 표시됩니다. ``` doGetTable: Retrieved schema for table[TableName{schemaName=test, tableName=profiles}] from AWS Glue. ``` **참고** 테이블에 이미 `columnMapping` 필드가 구성되어 있는 경우 테이블 속성에 `docdb-metadata-flag = true` 파라미터를 추가하기만 하면 됩니다. ## AWS Glue에서 데이터베이스 및 테이블 설정 커넥터의 기본 제공 스키마 추론 기능은 제한된 수의 문서를 스캔하고 데이터 형식의 하위 세트만 지원하므로 메타데이터에 AWS Glue를 대신 사용할 수 있습니다. Amazon DocumentDB에서 사용할 AWS Glue 테이블을 활성화하려면 보충 메타데이터를 제공할 DocumentDB 데이터베이스 및 컬렉션에 대한 AWS Glue 데이터베이스와 테이블이 있어야 합니다. **보충 메타데이터에 AWS Glue 테이블 사용** 1. AWS Glue 콘솔을 사용하여 Amazon DocumentDB 데이터베이스 이름과 동일한 이름으로 AWS Glue 데이터베이스를 생성할 수 있습니다. 1. **docdb-metadata-flag**를 포함하도록 데이터베이스의 URI 속성을 설정합니다. 1. (선택 사항) **sourceTable** 테이블 속성을 추가합니다. 이 속성에 따라 Amazon DocumentDB의 소스 테이블 이름이 정의됩니다. AWS Glue 테이블의 이름이 Amazon DocumentDB의 테이블 이름과 다른 경우 이 속성을 사용합니다. AWS Glue와 Amazon DocumentDB 간의 이름 지정 규칙 차이 때문에 이 작업이 필요할 수 있습니다. 예를 들어, AWS Glue 테이블 이름에는 대문자가 허용되지 않지만 Amazon DocumentDB 테이블 이름에는 대문자가 허용됩니다. 1. (선택 사항) **columnMapping** 테이블 속성을 추가합니다. 이 속성은 열 이름 매핑을 정의합니다. AWS Glue 열 이름 지정 규칙으로 인해 Amazon DocumentDB 테이블의 열과 동일한 열 이름으로 AWS Glue 테이블을 생성할 수 없는 경우 이 속성을 사용합니다. Amazon DocumentDB 열 이름에는 대문자가 허용되지만 AWS Glue 열 이름에는 대문자가 허용되지 않기 때문에 이 방법이 유용할 수 있습니다. `columnMapping` 속성 값은 `col1=Col1,col2=Col2` 형식의 매핑 세트여야 합니다. **참고** 열 매핑은 상위 열 이름에만 적용되고 중첩된 필드에는 적용되지 않습니다. AWS Glue `columnMapping` 테이블 속성을 추가한 후 `disable_projection_and_casing` Lambda 환경 변수를 제거할 수 있습니다. 1. 이 문서에 나열된 대로 AWS Glue에 적합한 데이터 형식을 사용해야 합니다. ## 데이터 형식 지원 이 섹션에는 DocumentDB 커넥터가 스키마 추론에 사용하는 데이터 형식과 AWS Glue 메타데이터가 사용될 때의 데이터 형식이 나열되어 있습니다. ### 스키마 추론 데이터 형식 DocumentDB 커넥터의 스키마 추론 기능은 값을 다음 데이터 형식 중 하나에 속하는 것으로 추정하려고 시도합니다. 다음 표에는 Amazon DocumentDB, Java 및 Apache Arrow에 해당하는 데이터 형식이 나와 있습니다. **** | Apache Arrow | Java 또는 DocDB | | --- | --- | | VARCHAR | 문자열 | | INT | Integer | | BIGINT | Long | | BIT | 부울 | | FLOAT4 | Float | | FLOAT8 | 배정밀도 실수 | | TIMESTAMPSEC | 날짜 | | VARCHAR | ObjectId | | LIST | List | | STRUCT | 문서 | ### AWS Glue 데이터 유형 보충 메타데이터에 AWS Glue를 사용하는 경우 다음 데이터 형식을 구성할 수 있습니다. 다음 표에는 AWS Glue와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | AWS Glue | Apache Arrow | | --- | --- | | int | INT | | bigint | BIGINT | | double | FLOAT8 | | 실수 | FLOAT4 | | 부울 | BIT | | 이진수 | VARBINARY | | 문자열 | VARCHAR | | List | LIST | | 구조체 | STRUCT | ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-docdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-docdb/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 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원하며 NoSQL 기반입니다. Amazon DocumentDB 쿼리에 대한 자세한 내용은 **Amazon DocumentDB 개발자 가이드의 [쿼리](https://docs.aws.amazon.com/documentdb/latest/developerguide/querying.html)를 참조하세요. 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"}' )) ``` ## 추가 리소스 + [Amazon Athena 페더레이션 쿼리](federated-queries.md)를 사용하여 MongoDB 데이터베이스를 [Quick](https://aws.amazon.com/quicksight/)에 연결해 대시보드와 시각화를 생성하는 방법에 대한 문서는 *AWS Big Data Blog*의 [Visualize MongoDB data from Quick using Amazon Athena Federated Query](https://aws.amazon.com/blogs/big-data/visualize-mongodb-data-from-amazon-quicksight-using-amazon-athena-federated-query/)를 참조하세요. + 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-docdb)를 참조하세요. # Amazon Athena DynamoDB 커넥터 Amazon DynamoDB 커넥터를 통해 Amazon Athena는 DynamoDB와 통신할 수 있고, 이로써 SQL을 사용하여 테이블을 쿼리할 수 있습니다. [INSERT INTO](insert-into.md) 같은 쓰기 작업은 지원되지 않습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. 계정에서 Lake Formation을 활성화한 경우 AWS Serverless Application Repository에 배포한 Athena 페더레이션형 Lambda 커넥터의 IAM 역할은 Lake Formation에서 AWS Glue Data Catalog에 대한 읽기 액세스 권한을 가지고 있어야 합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 DynamoDB 연결을 Glue Catalog 및 Lake Formation으로 마이그레이션하면 소문자 테이블과 열 이름만 인식됩니다. ## 파라미터 이 섹션의 파라미터를 사용하여 DynamoDB 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 DynamoDB 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 DynamoDB 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type DYNAMODB ``` **Lambda 환경 속성** **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 DynamoDB 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 DynamoDB 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. **Lambda 환경 속성** + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **disable\$1glue** – (선택 사항) true로 설정된 경우 커넥터는 AWS Glue에서 보충 메타데이터 검색을 시도하지 않습니다. + **glue\$1catalog** – (선택 사항) 이 옵션을 사용하여 [크로스 계정 AWS Glue 카탈로그](data-sources-glue-cross-account.md)를 지정합니다. 기본적으로 커넥터는 자체 AWS Glue 계정에서 메타데이터를 가져오려고 시도합니다. + **disable\$1projection\$1and\$1casing** – (선택 사항) 프로젝션과 대/소문자를 비활성화합니다. 열 이름에 대/소문자가 있는 DynamoDB 테이블을 쿼리하고 AWS Glue 테이블에 `columnMapping` 속성을 지정하지 않으려는 경우 사용합니다. `disable_projection_and_casing` 파라미터는 다음 값을 사용하여 대/소문자 및 열 매핑의 동작을 지정합니다. + **auto**(자동) - 이전에 지원되지 않는 형식이 감지되고 테이블에 열 이름 매핑이 설정되지 않은 경우 프로젝션과 대/소문자를 비활성화합니다. 이것이 기본 설정입니다. + **always**(항상) - 프로젝션과 대/소문자를 무조건 비활성화합니다. 이는 DynamoDB 열 이름에 대/소문자가 있지만 열 이름 매핑을 지정하지 않으려는 경우에 유용합니다. `disable_projection_and_casing` 파라미터를 사용할 때는 다음 사항에 유의하세요. + 파라미터를 사용하면 대역폭 사용량이 증가할 수 있습니다. 또한 Lambda 함수가 데이터 소스와 동일한 AWS 리전에 있지 않을 경우 대역폭 사용량이 증가하여 더 높은 표준 AWS 리전 간 전송 비용이 청구됩니다. 리전 간 전송 비용에 대한 자세한 내용은 AWS 파트너 네트워크 블로그의 [서버 및 서버리스 아키텍처에 대한 AWS 데이터 전송 요금](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)을 참조하세요. + 더 많은 수의 바이트가 전송되고 더 많은 수의 바이트가 더 많은 역직렬화 시간을 필요로 하기 때문에 전체 지연 시간이 늘어날 수 있습니다. ## AWS Glue에서 데이터베이스 및 테이블 설정 커넥터의 기본 제공 스키마 추론 기능이 제한되어 있으므로 메타데이터에 AWS Glue를 사용할 수 있습니다. 이렇게 하려면 AWS Glue에 데이터베이스와 테이블이 있어야 합니다. DynamoDB에서 사용할 수 있도록 하려면 해당 속성을 편집해야 합니다. **AWS Glue 콘솔에서 데이터베이스 속성을 편집하려면 다음을 수행하세요.** 1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)에서 AWS Glue 콘솔을 엽니다. 1. 탐색 창에서 **데이터 카탈로그**를 확장하고 **데이터베이스**를 선택합니다. **Databases**(데이터베이스) 페이지에서 기존 데이터베이스를 편집하거나 **Add database**(데이터베이스 추가)를 선택하여 데이터베이스를 생성할 수 있습니다. 1. 데이터베이스 목록에서 편집하려는 데이터베이스의 링크를 선택합니다. 1. **편집**을 선택합니다. 1. **데이터베이스 업데이트** 페이지에서 **데이터베이스 설정** 아래의 **위치**에 문자열 **dynamo-db-flag**를 추가합니다. 이 키워드는 Athena DynamoDB 커넥터가 보충 메타데이터에 사용하고 `default` 이외의 AWS Glue 데이터베이스에 필요한 테이블이 데이터베이스에 포함되어 있음을 나타냅니다. `dynamo-db-flag` 속성은 데이터베이스가 많은 계정에서 데이터베이스를 필터링하는 데 유용합니다. 1. **Update Database**(데이터베이스 업데이트)를 선택합니다. **AWS Glue 콘솔에서 테이블 속성을 편집하려면** 1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)에서 AWS Glue 콘솔을 엽니다. 1. 탐색 창에서 **데이터 카탈로그**를 확장하고 **테이블**을 선택합니다. 1. **테이블** 페이지의 테이블 목록에서 편집하려는 테이블의 연결된 이름을 선택합니다. 1. **Actions**(작업), **Edit table**(테이블 편집)을 선택합니다. 1. **Edit table**(테이블 편집) 페이지의 **Table properties**(테이블 속성) 섹션에서 필요에 따라 다음 테이블 속성을 추가합니다. AWS Glue DynamoDB 크롤러를 사용하는 경우 이러한 속성이 자동으로 설정됩니다. + **dynamodb** – 테이블을 보충 메타데이터에 사용할 수 있음을 Athena DynamoDB 커넥터에 나타내는 문자열입니다. **classification**(분류)이라는 필드 아래의 테이블 속성에 `dynamodb`를 입력합니다(정확히 일치). **참고** AWS Glue 콘솔의 테이블 작성 프로세스의 일부인 **테이블 속성 설정** 페이지에는 **분류** 필드가 있는 **데이터 형식** 섹션이 있습니다. 여기서는 `dynamodb`를 입력하거나 선택할 수 없습니다. 대신, 테이블을 생성한 후 테이블을 편집하고 **테이블 속성** 섹션에서 `classification`과 `dynamodb`를 키-값 페어로 입력하는 단계를 수행합니다. + **sourceTable** – DynamoDB에서 소스 테이블 이름을 정의하는 선택적 테이블 속성입니다. AWS Glue 테이블 이름 지정 규칙으로 인해 DynamoDB 테이블과 동일한 이름으로 AWS Glue 테이블을 생성할 수 없는 경우 이 옵션을 사용합니다. 예를 들어, AWS Glue 테이블 이름에는 대문자가 허용되지 않지만 DynamoDB 테이블 이름에는 대문자가 허용됩니다. + **columnMapping** – 열 이름 매핑을 정의하는 선택적 테이블 속성입니다. AWS Glue 열 이름 지정 규칙으로 인해 DynamoDB 테이블과 동일한 열 이름으로 AWS Glue 테이블을 생성할 수 없는 경우 이 옵션을 사용합니다. 예를 들어, AWS Glue 열 이름에는 대문자가 허용되지 않지만 DynamoDB 열 이름에는 대문자가 허용됩니다. 속성 값은 col1=Col1,col2=Col2 형식이어야 합니다. 단, 열 매핑은 최상위 열 이름에만 적용되고 중첩된 필드에는 적용되지 않습니다. + **defaultTimeZone** – 명시적 표준 시간대가 없는 `date` 또는 `datetime` 값에 적용되는 선택적 테이블 속성입니다. 이 값을 설정하면 데이터 소스 기본 표준 시간대와 Athena 세션 시간대 간의 불일치를 방지하는 것이 좋습니다. + **datetimeFormatMapping** – AWS Glue `date` 또는 `timestamp` 데이터 형식의 열에서 데이터를 구문 분석할 때 사용할 `date` 또는 `datetime` 형식을 지정하는 선택적 테이블 속성입니다. 이 속성을 지정하지 않으면 커넥터는 ISO-8601 형식을 [추론](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/time/DateFormatUtils.html)하려고 시도합니다. 커넥터가 `date` 또는 `datetime` 형식을 추론할 수 없거나 원시 문자열을 구문 분석할 수 없는 경우 결과에서 값이 생략됩니다. `datetimeFormatMapping` 값은 `col1=someformat1,col2=someformat2` 형식이어야 합니다. 다음은 몇 가지 예제 형식입니다. ``` yyyyMMdd'T'HHmmss ddMMyyyy'T'HH:mm:ss ``` 열에 표준 시간대가 없는 `date` 또는 `datetime` 값이 있고 `WHERE` 절의 열을 사용하려는 경우 열에 대한 `datetimeFormatMapping` 속성을 설정합니다. 1. 열을 수동으로 정의하는 경우 적절한 데이터 형식을 사용하는지 확인합니다. 크롤러를 사용한 경우 크롤러가 검색한 열과 유형을 검증합니다. 1. **저장**을 선택합니다. ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-dynamodb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-dynamodb/athena-dynamodb.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. + **AWS Glue Data Catalog** - 스키마 정보를 가져오기 위해 DynamoDB 커넥터에 AWS Glue Data Catalog에 대한 읽기 전용 액세스 권한이 필요합니다. + **CloudWatch Logs** - 로그를 저장하기 위해 커넥터 CloudWatch Logs에 대한 액세스 권한이 필요합니다. + **DynamoDB 읽기 액세스** – 커넥터는 `DescribeTable`, `ListSchemas`, `ListTables`, `Query` 및 `Scan` API 작업을 사용합니다. ## 성능 Athena DynamoDB 커넥터는 병렬 스캔을 지원하고 DynamoDB 쿼리의 일부로 조건자 푸시다운을 시도합니다. `X`개의 고유 값이 있는 해시 키 조건자는 DynamoDB에 대한 `X`개의 쿼리 호출을 생성합니다. 다른 모든 조건자 시나리오에서는 `Y`개의 스캔 호출이 발생합니다. 여기서 `Y`는 테이블 크기와 프로비저닝된 처리량을 기반으로 경험적으로 결정됩니다. 그러나 열 하위 세트를 선택할 때 쿼리 실행 런타임이 길어지는 경우가 있습니다. `LIMIT` 절 및 간단한 조건자가 푸시다운되면 스캔하는 데이터가 줄어들 수 있으며 이에 따라 쿼리 실행 런타임이 감소할 수 있습니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena DynamoDB 커넥터는 이러한 표현식을 결합하고 DynamoDB로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena DynamoDB 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1NULL ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 and col_b < 10 LIMIT 10 ``` DynamoDB를 비롯한 페더레이션된 쿼리의 성능을 개선하기 위해 조건자 푸시다운을 사용하는 방법에 대한 문서는 *AWS 빅 데이터 블로그*의 [Improve federated queries with predicate pushdown in Amazon Athena](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)를 참조하세요. ## 패스스루 쿼리 DynamoDB 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원하고 PartiQL 구문을 사용합니다. DynamoDB [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) API 작업은 지원되지 않습니다. PartiQL을 사용하여 DynamoDB를 쿼리하는 방법에 대한 자세한 내용은 **Amazon DynamoDB 개발자 안내서의 [DynamoDB용 PartiQL select 문](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html)을 참조하세요. DynamoDB에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query_string' )) ``` 다음 DynamoDB 패스스루 쿼리 예제는 PartiQL을 사용하여 `DateWatched` 속성이 12/24/22 이후인 Fire TV Stick 디바이스 목록을 반환합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT Devices FROM WatchList WHERE Devices.FireStick.DateWatched[0] > '12/24/22'' )) ``` ## 문제 해결 ### 정렬 키 열의 다중 필터 **오류 메시지**: KeyConditionExpressions must only contain one condition per key **원인**: 이 문제는 Athena 엔진 버전 3의 경우 DynamoDB 정렬 키 열에 하한 및 상한 필터가 모두 있는 쿼리에서 발생할 수 있습니다. DynamoDB는 정렬 키에 대해 둘 이상의 필터 조건을 지원하지 않으므로 커넥터가 두 조건이 모두 적용된 쿼리를 푸시다운하려고 하면 오류가 발생합니다. **솔루션**: 커넥터를 버전 2023.11.1 이상으로 업데이트합니다. 커넥터 업데이트에 대한 지침은 [데이터 소스 커넥터 업데이트](connectors-updating.md) 섹션을 참조하세요. ## 비용 커넥터 사용 비용은 사용되는 기본 AWS 리소스에 따라 다릅니다. 스캔을 사용하는 쿼리는 많은 [읽기 용량 단위(RCU)](https://aws.amazon.com/dynamodb/pricing/provisioned/)를 사용할 수 있으므로 [Amazon DynamoDB 요금 정보](https://aws.amazon.com/dynamodb/pricing/)를 신중하게 고려하세요. ## 추가 리소스 + Amazon Athena DynamoDB 커넥터 사용에 대한 소개는 *AWS Prescriptive Guidance Patterns* 가이드의 [Access, query, and join Amazon DynamoDB tables using Athena](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/access-query-and-join-amazon-dynamodb-tables-using-athena.html)를 참조하세요. + Athena DynamoDB 커넥터를 사용하여 SQL로 DynamoDB의 데이터를 쿼리하고 Quick에서 인사이트를 시각화하는 방법에 대한 문서는 *AWS Big Data Blog* 게시물 [Visualize Amazon DynamoDB insights in Quick using the Amazon Athena DynamoDB connector and AWS Glue](https://aws.amazon.com/blogs/big-data/visualize-amazon-dynamodb-insights-in-amazon-quicksight-using-the-amazon-athena-dynamodb-connector-and-aws-glue/)를 참조하세요. + Amazon DynamoDB, Athena 및 Quick에서 Amazon Athena DynamoDB 커넥터를 사용하여 간단한 거버넌스 대시보드를 생성하는 방법에 대한 문서는 *AWS Big Data Blog* 게시물 [Query cross-account Amazon DynamoDB tables using Amazon Athena Federated Query](https://aws.amazon.com/blogs/big-data/query-cross-account-amazon-dynamodb-tables-using-amazon-athena-federated-query/)를 참조하세요. + 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-dynamodb)를 참조하세요. # Amazon Athena Google BigQuery 커넥터 Google [BigQuery](https://cloud.google.com/bigquery/)용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 Google BigQuery 데이터에 대해 SQL 쿼리를 실행할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + Lambda 함수의 최대 제한 시간 값은 15분입니다. 각 분할은 BigQuery에서 쿼리를 실행하며 Athena에서 읽을 결과를 저장할 수 있는 충분한 시간을 두고 완료해야 합니다. Lambda 함수가 시간 초과되면 쿼리가 실패합니다. + Google BigQuery는 대/소문자를 구분합니다. 커넥터는 데이터세트 이름, 테이블 이름 및 프로젝트 ID의 대/소문자를 수정하려고 시도합니다. 이는 Athena가 모든 메타데이터를 소문자로 만들기 때문에 필요합니다. 이러한 수정으로 인해 Google BigQuery에 대한 추가 호출이 많이 발생합니다. + 바이너리 데이터 형식은 지원되지 않습니다. + Google BigQuery 동시성 및 할당량 제한으로 인해 커넥터에 Google 할당량 제한 문제가 발생할 수 있습니다. 이러한 문제를 방지하려면 Google BigQuery에 최대한 많은 제약 조건을 푸시합니다. BigQuery 할당량에 대한 자세한 내용을 알아보려면 Google BigQuery 설명서의 [할당량 및 한도](https://cloud.google.com/bigquery/quotas)를 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 Google BigQuery 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Google BigQuery 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Google BigQuery 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type BIGQUERY ``` **Lambda 환경 속성** **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Google BigQuery 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Google BigQuery 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. **Lambda 환경 속성** + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **gcp\$1project\$1id** – 커넥터가 읽어야 하는 데이터 세트를 포함하는 프로젝트 ID(프로젝트 이름 아님)입니다(예: `semiotic-primer-1234567`). + **secret\$1manager\$1gcp\$1creds\$1name** – JSON 형식의 BigQuery 자격 증명을 포함하는 AWS Secrets Manager 내의 보안 암호 이름입니다(예: `GoogleCloudPlatformCredentials`). + **big\$1query\$1endpoint** - (선택 사항) BigQuery 프라이빗 엔드포인트의 URL입니다. 프라이빗 엔드포인트를 통해 BigQuery에 액세스하려는 경우 이 파라미터를 사용합니다. ## 분할 및 뷰 BigQuery 커넥터는 BigQuery Storage Read API를 사용하여 테이블을 쿼리하고, BigQuery Storage API는 뷰를 지원하지 않기 때문에 커넥터는 뷰의 단일 분할에 BigQuery 클라이언트를 사용합니다. ## 성능 테이블 쿼리를 위해 BigQuery 커넥터는 BigQuery 관리 스토리지에 빠르게 액세스할 수 있는 RPC 기반 프로토콜을 사용하는 BigQuery Storage Read API를 사용합니다. BigQuery 스토리지 읽기 API에 대한 자세한 내용은 Google Cloud 문서에서 [Use the BigQuery Storage Read API to read table data](https://cloud.google.com/bigquery/docs/reference/storage)를 참조하세요. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. 동시성이 증가함에 따라 커넥터에서 쿼리 오류가 발생할 수 있으며 일반적으로 커넥터가 느립니다. Athena Google BigQuery 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, `ORDER BY` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### 상위 N개 쿼리 상위 `N`개 쿼리는 결과 세트의 순서와 반환되는 행 수에 대한 한도를 지정합니다. 이 유형의 쿼리를 사용하여 데이터 세트에 대해 상위 `N`개의 최댓값 또는 상위 `N`개의 최솟값을 결정할 수 있습니다. 상위 `N`개의 푸시다운을 통해 커넥터는 Athena에 `N`개의 정렬된 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Google BigQuery 커넥터는 이러한 표현식을 결합하고 Google BigQuery로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Google BigQuery 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') ORDER BY col_a DESC LIMIT 10; ``` ## 패스스루 쿼리 Google BigQuery 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Google BigQuery에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Google BigQuery의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 Amazon Athena Google BigQuery 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다. 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-google-bigquery)를 참조하세요. # Amazon Athena Google Cloud Storage 커넥터 Amazon Athena Google Cloud Storage 커넥터를 사용하면 Amazon Athena가 Google Cloud Storage(GCS) 버킷에 저장된 Parquet 및 CSV 파일에 대해 쿼리를 실행할 수 있습니다. GCS 버킷의 분할되지 않은 폴더나 분할된 폴더에서 하나 이상의 Parquet 또는 CSV 파일을 그룹화한 후 [AWS Glue](https://aws.amazon.com/glue/) 데이터베이스 테이블에서 구성할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. 계정에서 Lake Formation을 활성화한 경우 AWS Serverless Application Repository에 배포한 Athena 페더레이션형 Lambda 커넥터의 IAM 역할은 Lake Formation에서 AWS Glue Data Catalog에 대한 읽기 액세스 권한을 가지고 있어야 합니다. Athena를 사용하여 GCS 버킷의 Parquet 또는 CSV 파일에서 쿼리를 실행하는 방법을 보여주는 문서는 AWS 빅 데이터 블로그 게시물 [Use Amazon Athena to query data stored in Google Cloud Platform](https://aws.amazon.com/blogs/big-data/use-amazon-athena-to-query-data-stored-in-google-cloud-platform/)을 참조하세요. ## 사전 조건 + Google Cloud Storage의 버킷 및 폴더에 해당하는 AWS Glue 데이터베이스 및 테이블을 설정합니다. 단계는 이 문서 뒷부분의 [AWS Glue에서 데이터베이스 및 테이블 설정](#connectors-gcs-setting-up-databases-and-tables-in-glue) 섹션을 참조하세요. + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 현재 커넥터는 파티션 열(AWS Glue 테이블 스키마의 `string` 또는 `varchar`)에 대해 `VARCHAR` 유형만 지원합니다. 다른 파티션 필드 유형은 Athena에서 쿼리할 때 오류가 발생합니다. ## 용어 다음 용어는 GCS 커넥터와 관련이 있습니다. + **핸들러** - GCS 버킷에 액세스하는 Lambda 핸들러입니다. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - GCS 버킷에서 메타데이터를 검색하는 Lambda 핸들러입니다. + **레코드 핸들러** - GCS 버킷에서 데이터 레코드를 검색하는 Lambda 핸들러입니다. + **복합 핸들러** - GCS 버킷에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러입니다. ## 지원되는 파일 형식 GCS 커넥터는 Parquet 및 CSV 파일 형식을 지원합니다. **참고** 동일한 GCS 버킷 또는 경로에 CSV 및 Parquet 파일을 모두 배치하지 않도록 합니다. 그렇게 하면 Parquet 파일을 CSV로 읽거나 그 반대로 읽으려고 할 때 런타임 오류가 발생할 수 있습니다. ## 파라미터 이 섹션의 파라미터를 사용하여 GCS 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 GCS 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 GCS 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type GOOGLECLOUDSTORAGE ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 GCS 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 GCS 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **secret\$1manager\$1gcp\$1creds\$1name** – JSON 형식의 GCS 자격 증명을 포함하는 AWS Secrets Manager 내의 보안 암호 이름입니다(예: `GoogleCloudPlatformCredentials`). ## AWS Glue에서 데이터베이스 및 테이블 설정 GCS 커넥터의 기본 제공 스키마 추론 기능은 제한적이기 때문에 메타데이터에 AWS Glue를 사용하는 것이 좋습니다. 다음 절차는 Athena에서 액세스할 수 있는 AWS Glue에서 데이터베이스와 테이블을 생성하는 방법을 보여줍니다. ### AWS Glue에서 데이터베이스 생성 AWS Glue 콘솔을 사용하여 GCS 커넥터와 함께 사용할 데이터베이스를 생성할 수 있습니다. **AWS Glue 데이터베이스 사용자를 생성하려면 다음을 수행하세요.** 1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)에서 AWS Glue 콘솔을 엽니다. 1. 탐색 창에서 **Databases**(데이터베이스)를 선택합니다. 1. **데이터베이스 추가(Add database)**를 선택합니다. 1. **Name**(이름)에 GCS 커넥터와 함께 사용할 데이터베이스 이름을 입력합니다. 1. **위치**에 `google-cloud-storage-flag`를 지정합니다. 이 위치는 AWS Glue 데이터베이스에 Athena에서 쿼리할 GCS 데이터용 테이블이 포함되어 있음을 GCS 커넥터에 알립니다. 커넥터는 Athena에서 이 플래그가 있는 데이터베이스를 인식하고 그렇지 않은 데이터베이스는 무시합니다. 1. **데이터베이스 생성**을 선택합니다. ### AWS Glue에서 테이블 생성 이제 데이터베이스용 테이블을 생성할 수 있습니다. GCS 커넥터와 함께 사용할 AWS Glue 테이블을 생성할 때 추가 메타데이터를 지정해야 합니다. **AWS Glue 콘솔에서 테이블을 생성하려면 다음을 수행하세요.** 1. AWS Glue 콘솔의 탐색 창에서 **Tables**(테이블)를 선택합니다. 1. **Tables**(테이블) 페이지에서 **Add table**(테이블 추가)을 선택합니다. 1. **Set table properties**(테이블 속성 설정) 페이지에 다음 정보를 입력합니다. + **Name**(이름) – 테이블의 고유한 이름입니다. + **Database**(데이터베이스) – GCS 커넥터용으로 생성한 AWS Glue 데이터베이스를 선택합니다. + **Include path**(포함 경로) – **Data store**(데이터 스토어) 섹션에서 **Include path**(포함 경로)에 `gs://`로 시작하는 GCS의 URI 위치를 입력합니다(예: `gs://gcs_table/data/`). 파티션 폴더가 하나 이상 있는 경우 해당 폴더를 경로에 포함하지 마세요. **참고** `s3://`가 아닌 테이블 경로를 입력하면 AWS Glue 콘솔에 오류가 표시됩니다. 이 오류는 무시할 수 있습니다. 테이블이 성공적으로 생성됩니다. + **Data format**(데이터 형식) – **Classification**(분류)에서 **CSV** 또는 **Parquet**를 선택합니다. 1. [**Next**]를 선택합니다. 1. **Choose or define schema**(스키마 선택 또는 정의) 페이지에서 테이블 스키마를 정의하는 것이 좋지만 필수는 아닙니다. 스키마를 정의하지 않으면 GCS 커넥터가 스키마 추론을 시도합니다. 다음 중 하나를 수행하세요. + GCS 커넥터가 스키마 추론을 시도하도록 하려면 **Next**(다음)를 선택한 다음 **Create**(생성)를 선택합니다. + 스키마를 직접 정의하려면 다음 섹션의 단계를 따르세요. ### AWS Glue에서 테이블 스키마 정의 AWS Glue에서 테이블 스키마를 정의하려면 더 많은 단계가 필요하지만 테이블 생성 프로세스를 더 잘 제어할 수 있습니다. **AWS Glue에서 테이블의 스키마를 정의하려면 다음을 수행하세요.** 1. **Choose or define schema**(스키마 선택 또는 정의) 페이지에서 **Add**(추가)를 선택합니다. 1. **Add schema entry**(스키마 항목 추가) 대화 상자를 사용하여 열 이름과 데이터 유형을 제공할 수 있습니다. 1. 열을 파티션 열로 지정하려면 **Set as partition key**(파티션 키로 설정) 옵션을 선택합니다. 1. **Save**(저장)를 선택하여 열을 저장합니다. 1. **Add**(추가)를 선택하여 열을 추가합니다. 1. 열 추가를 마치면 **Next**(다음)를 선택합니다. 1. **Review and create**(검토 및 생성) 페이지에서 테이블을 검토한 다음 **Create**(생성)를 선택합니다. 1. 스키마에 파티션 정보가 포함된 경우 다음 섹션의 단계에 따라 AWS Glue에서 테이블 속성에 파티션 패턴을 추가합니다. ### AWS Glue에서 테이블 속성에 파티션 패턴 추가 GCS 버킷에 파티션이 있는 경우 AWS Glue에서 테이블 속성에 파티션 패턴을 추가해야 합니다. **AWS Glue에서 테이블 속성에 파티션 정보를 추가하려면 다음을 수행하세요.** 1. AWS Glue에서 생성한 테이블의 세부 정보 페이지에서 **Actions**(작업), **Edit table**(테이블 편집)을 선택합니다. 1. **Edit table**(테이블 편집) 페이지에서 **Table properties**(테이블 속성) 세션이 나타날 때까지 아래로 스크롤합니다. 1. **Add**(추가)를 선택하여 파티션 키를 추가합니다. 1. **키**에 **partition.pattern**를 입력합니다. 이 키는 폴더 경로 패턴을 정의합니다. 1. **Value**(값)에 **StateName=\$1\$1statename\$1/ZipCode=\$1\$1zipcode\$1/**와 같은 폴더 경로 패턴을 입력합니다. 여기서 **\$1\$1\$1**로 묶인 **statename** 및 **zipcode**는 파티션 열 이름입니다. GCS 커넥터는 Hive 및 비Hive 파티션 구성표를 모두 지원합니다. 1. 작업을 마쳤으면 **저장**을 선택합니다. 1. 방금 생성한 테이블 속성을 보려면 **Advanced properties**(고급 속성) 탭을 선택합니다. 이제 Athena 콘솔로 이동할 수 있습니다. AWS Glue에서 생성한 데이터베이스와 테이블은 Athena에서 쿼리할 수 있습니다. ## 데이터 형식 지원 다음 표에 CSV 및 Parquet에 대해 지원되는 데이터 형식이 나와 있습니다. ### CSV **** | **데이터의 특성** | **추론된 데이터 형식** | | --- | --- | | 데이터가 숫자처럼 보임 | BIGINT | | 데이터가 문자열처럼 보임 | VARCHAR | | 데이터가 부동 소수점(float, double 또는 decimal)처럼 보임 | DOUBLE | | 데이터가 날짜처럼 보임 | 타임스탬프 | | 데이터에 true/false 값이 포함됨 | BOOL | ### PARQUET **** | **PARQUET** | **Athena(Arrow)** | | --- | --- | | BINARY | VARCHAR | | BOOLEAN | BOOL | | DOUBLE | DOUBLE | | ENUM | VARCHAR | | FIXED\$1LEN\$1BYTE\$1ARRAY | DECIMAL | | FLOAT | FLOAT(32비트) | | INT32 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-gcs.html) | | INT64 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-gcs.html) | | INT96 | 타임스탬프 | | MAP | MAP | | STRUCT | STRUCT | | LIST | LIST | ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-gcs.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/athena-gcs.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. + **AWS Glue Data Catalog** - 스키마 정보를 가져오기 위해 GCS 커넥터에 AWS Glue Data Catalog에 대한 읽기 전용 액세스 권한이 필요합니다. + **CloudWatch Logs** - 로그를 저장하기 위해 커넥터 CloudWatch Logs에 대한 액세스 권한이 필요합니다. ## 성능 테이블 스키마에 파티션 필드가 포함되어 있고 `partition.pattern` 테이블 속성이 올바르게 구성된 경우 쿼리의 `WHERE` 절에 파티션 필드를 포함할 수 있습니다. 이러한 쿼리의 경우 GCS 커넥터는 파티션 열을 사용하여 GCS 폴더 경로를 구체화하고 GCS 폴더에서 불필요한 파일을 스캔하지 않도록 합니다. Parquet 데이터 세트의 경우 열 하위 세트를 선택하면 스캔되는 데이터가 줄어듭니다. 이로 인해 일반적으로 열 프로젝션이 적용될 때 쿼리 실행 런타임이 짧아집니다. CSV 데이터 세트의 경우 열 프로젝션이 지원되지 않으며 스캔되는 데이터의 양을 줄이지 않습니다. `LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자를 제공하지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. GCS 커넥터는 적용된 `LIMIT` 절에 관계없이 작은 데이터 세트보다 큰 데이터 세트에 대해 더 많은 데이터를 스캔합니다. 예를 들어, 쿼리 `SELECT * LIMIT 10000`은 더 작은 기본 데이터 세트보다 더 큰 기본 데이터 세트에 대해 더 많은 데이터를 스캔합니다. ### 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ### 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-gcs)를 참조하세요. # Amazon Athena HBase 커넥터 Amazon Athena HBase 커넥터를 통해 Amazon Athena는 Apache HBase 인스턴스와 통신할 수 있고, 이로써 SQL을 사용하여 HBase 데이터를 쿼리할 수 있습니다. 기존의 관계형 데이터 스토어와 달리 HBase 컬렉션에는 설정된 스키마가 없습니다. HBase에는 메타데이터 스토어가 없습니다. HBase 컬렉션의 항목마다 필드와 데이터 형식이 다를 수 있습니다. HBase 커넥터는 테이블 스키마 정보를 생성하기 위한 두 가지 메커니즘인 기본 스키마 추론과 AWS Glue Data Catalog 메타데이터를 지원합니다. 스키마 추론이 기본값입니다. 이 옵션은 컬렉션에 있는 소수의 문서를 스캔하고, 모든 필드의 통합을 형성하고, 겹치지 않는 데이터 형식을 가진 필드를 강제 변환합니다. 이 옵션은 항목이 대부분 균일한 컬렉션에 적합합니다. 더 다양한 데이터 형식이 있는 컬렉션의 경우 커넥터는 AWS Glue Data Catalog에서 메타데이터 검색을 지원합니다. 커넥터가 HBase 네임스페이스 및 컬렉션 이름과 일치하는 AWS Glue 데이터베이스 및 테이블을 발견하면 해당 AWS Glue 테이블에서 스키마 정보를 가져옵니다. AWS Glue 테이블을 생성할 때 HBase 컬렉션에서 액세스하려는 모든 필드의 상위 세트로 만드는 것이 좋습니다. 계정에서 Lake Formation을 활성화한 경우 AWS Serverless Application Repository에 배포한 Athena 페더레이션형 Lambda 커넥터의 IAM 역할은 Lake Formation에서 AWS Glue Data Catalog에 대한 읽기 액세스 권한을 가지고 있어야 합니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 HBase 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 HBase 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 HBase 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type HBASE ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 HBase 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 HBase 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **disable\$1glue** – (선택 사항) true로 설정된 경우 커넥터는 AWS Glue에서 보충 메타데이터 검색을 시도하지 않습니다. + **glue\$1catalog** – (선택 사항) 이 옵션을 사용하여 [크로스 계정 AWS Glue 카탈로그](data-sources-glue-cross-account.md)를 지정합니다. 기본적으로 커넥터는 자체 AWS Glue 계정에서 메타데이터를 가져오려고 시도합니다. + **default\$1hbase** – 있는 경우 카탈로그 관련 환경 변수가 없을 때 사용할 HBase 연결 문자열을 지정합니다. + **enable\$1case\$1insensitive\$1match** - (선택 사항) `true`인 경우 HBase의 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다. 기본값은 `false`입니다. 쿼리에 대문자 테이블 이름이 포함된 경우에 사용합니다. #### 연결 문자열 지정 커넥터에서 사용하는 HBase 인스턴스에 대한 HBase 연결 세부 정보를 정의하는 속성을 하나 이상 제공할 수 있습니다. 이렇게 하려면 Athena에서 사용하려는 카탈로그 이름에 해당하는 Lambda 환경 변수를 설정합니다. 예를 들어, 다음 쿼리를 사용하여 Athena에서 서로 다른 2개의 HBase 인스턴스를 쿼리하려고 한다고 가정해 보겠습니다. ``` SELECT * FROM "hbase_instance_1".database.table ``` ``` SELECT * FROM "hbase_instance_2".database.table ``` 이 두 SQL 문을 사용하려면 먼저 2개의 환경 변수 `hbase_instance_1`과 `hbase_instance_2`를 Lambda 함수에 추가해야 합니다. 각 값은 다음 형식의 HBase 연결 문자열이어야 합니다. ``` master_hostname:hbase_port:zookeeper_port ``` ##### 보안 암호 사용 필요에 따라 연결 문자열 세부 정보 값의 일부 또는 전체에 대해 AWS Secrets Manager를 사용할 수 있습니다. Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) 또는 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)가 Lambda 함수에 연결된 VPC에 있어야 합니다. `${my_secret}` 구문을 사용하여 Secrets Manager의 보안 암호 이름을 연결 문자열에 입력하면 커넥터가 보안 암호 이름을 Secrets Manager의 사용자 이름 및 암호 값으로 바꿉니다. 예를 들어, `hbase_instance_1`에 대한 Lambda 환경 변수를 다음 값으로 설정했다고 가정해 보겠습니다. ``` ${hbase_host_1}:${hbase_master_port_1}:${hbase_zookeeper_port_1} ``` Athena Query Federation SDK는 자동으로 Secrets Manager에서 `hbase_instance_1_creds`라는 보안 암호를 검색하고 `${hbase_instance_1_creds}` 대신 해당 값을 삽입하려고 시도합니다. `${ }` 문자 조합으로 묶은 연결 문자열 부분은 Secrets Manager의 보안 암호로 해석됩니다. 커넥터가 Secrets Manager에서 찾을 수 없는 보안 암호 이름을 지정하면 커넥터가 텍스트를 바꾸지 않습니다. ## AWS Glue에서 데이터베이스 및 테이블 설정 커넥터의 기본 제공 스키마 추론은 HBase에서 문자열로 직렬화되는 값(예: `String.valueOf(int)`)만 지원합니다. 커넥터의 기본 제공 스키마 추론 기능이 제한되어 있으므로 메타데이터에 AWS Glue를 대신 사용할 수 있습니다. HBase에서 사용할 AWS Glue 테이블을 활성화하려면 보충 메타데이터를 제공할 HBase 네임스페이스 및 테이블과 이름이 일치하는 AWS Glue 데이터베이스 및 테이블이 있어야 합니다. HBase 열 패밀리 이름 지정 규칙의 사용은 선택 사항이며 필수는 아닙니다. **보충 메타데이터에 AWS Glue 테이블 사용** 1. AWS Glue 콘솔에서 테이블과 데이터베이스를 편집할 때 다음 테이블 속성을 추가합니다. + **hbase-metadata-flag** – 이 속성은 보충 메타데이터에 테이블을 사용할 수 있음을 HBase 커넥터에 나타냅니다. `hbase-metadata-flag` 속성이 테이블 속성 목록에 있는 한 `hbase-metadata-flag`에 모든 값을 제공할 수 있습니다. + **hbase-native-storage-flag** - 이 플래그를 사용하여 커넥터에서 지원하는 2개의 값 직렬화 모드를 전환합니다. 기본적으로 이 필드가 없으면 커넥터는 모든 값이 HBase에 문자열로 저장되어 있다고 가정합니다. 따라서 HBase에서 `INT`, `BIGINT`, `DOUBLE` 등의 데이터 형식을 문자열로 구문 분석하려고 시도합니다. 이 필드가 AWS Glue의 테이블에 있는 값으로 설정된 경우 커넥터는 '네이티브' 스토리지 모드로 전환하고 다음 함수를 사용하여 `INT`, `BIGINT`, `BIT` 및 `DOUBLE`을 바이트로 읽으려고 시도합니다. ``` ByteBuffer.wrap(value).getInt() ByteBuffer.wrap(value).getLong() ByteBuffer.wrap(value).get() ByteBuffer.wrap(value).getDouble() ``` 1. 이 문서에 나열된 대로 AWS Glue에 적합한 데이터 형식을 사용해야 합니다. ### 열 패밀리 모델링 Athena HBase 커넥터는 HBase 열 패밀리를 모델링하는 두 가지 방법, 즉 `family:column`과 같은 정규화된(평면화됨) 이름 지정 또는 `STRUCT` 객체 사용을 지원합니다. `STRUCT` 모델에서 `STRUCT` 필드의 이름은 열 패밀리와 일치해야 하고 `STRUCT`의 하위 항목은 패밀리의 열 이름과 일치해야 합니다. 그러나 조건자 푸시다운 및 열 형식 읽기는 `STRUCT`와 같은 복합 유형에 대해 아직 완전히 지원되지 않으므로 현재 `STRUCT`를 사용하는 것은 권장되지 않습니다. 다음 이미지에서는 AWS Glue에서 두 가지 접근 방식을 조합하여 사용하도록 구성된 테이블을 보여줍니다. ![\[AWS Glue에서 Apache Hbase용 열 패밀리 모델링.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-hbase-1.png) ## 데이터 형식 지원 커넥터는 모든 HBase 값을 기본 바이트 유형으로 검색합니다. 그런 다음 AWS Glue 데이터 카탈로그에서 테이블을 정의한 방법에 따라 값을 다음 테이블의 Apache Arrow 데이터 형식 중 하나로 매핑합니다. **** | AWS Glue 데이터 유형 | Apache Arrow 데이터 형식 | | --- | --- | | int | INT | | bigint | BIGINT | | double | FLOAT8 | | 실수 | FLOAT4 | | 부울 | BIT | | 이진수 | VARBINARY | | 문자열 | VARCHAR | **참고** AWS Glue를 사용하여 메타데이터를 보충하지 않는 경우 커넥터의 스키마 추론은 데이터 형식 `BIGINT`, `FLOAT8` 및 `VARCHAR`만 사용합니다. ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-hbase.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hbase/athena-hbase.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. + **AWS Glue Data Catalog** - 스키마 정보를 가져오기 위해 HBase 커넥터에 AWS Glue Data Catalog에 대한 읽기 전용 액세스 권한이 필요합니다. + **CloudWatch Logs** - 로그를 저장하기 위해 커넥터 CloudWatch Logs에 대한 액세스 권한이 필요합니다. + **AWS Secrets Manager 읽기 액세스** - Secrets Manager에 HBase 엔드포인트 세부 정보를 저장하기로 선택하는 경우 커넥터에 해당 보안 암호에 대한 액세스 권한을 부여해야 합니다. + **VPC 액세스** - VPC에 연결하고 HBase 인스턴스와 통신할 수 있도록 VPC에 인터페이스를 연결하고 분리하는 기능이 커넥터에 필요합니다. ## 성능 Athena HBase 커넥터는 각 리전 서버를 병렬로 읽어 HBase 인스턴스에 대한 쿼리 병렬화를 시도합니다. 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena HBase 커넥터에서 조건자 푸시다운을 수행합니다. 쿼리에서 스캔된는 데이터를 줄이기 위해 Lambda 함수에서 *프로젝션* 푸시다운도 수행합니다. 그러나 열의 하위 세트를 선택하면 쿼리 실행 런타임이 길어지는 경우가 있습니다. `LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자를 제공하지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. HBase는 쿼리 실패가 발생하기 쉽고 쿼리 실행 시간이 가변적입니다. 쿼리가 성공하려면 쿼리를 여러 번 다시 시도해야 할 수 있습니다. HBase 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. ## 패스스루 쿼리 HBase 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원하며 NoSQL 기반입니다. 필터링을 사용한 Apache HBase 쿼리에 대한 자세한 내용은 Apache 설명서의 [Filter language](https://hbase.apache.org/book.html#thrift.filter_language)를 참조하세요. HBase에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( database => 'database_name', collection => 'collection_name', filter => '{query_syntax}' )) ``` 다음 예제 HBase 패스스루 쿼리는 `default` 데이터베이스의 `employee` 컬렉션 내에서 24세 또는 30세 직원을 필터링합니다. ``` SELECT * FROM TABLE( system.query( DATABASE => 'default', COLLECTION => 'employee', FILTER => 'SingleColumnValueFilter(''personaldata'', ''age'', =, ''binary:30'')' || ' OR SingleColumnValueFilter(''personaldata'', ''age'', =, ''binary:24'')' )) ``` ## 라이선스 정보 Amazon Athena HBase 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hbase)를 참조하세요. # Amazon Athena Hortonworks 커넥터 Hortonworks용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 Cloudera [Hortonworks](https://www.cloudera.com/products/hdp.html) 데이터 플랫폼에 대해 SQL 쿼리를 실행할 수 있습니다. 커넥터는 Athena SQL 쿼리를 동일한 HiveQL 구문으로 변환합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. ## 용어 다음 용어는 Hortonworks Hive 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Hortonworks Hive 커넥터를 구성합니다. ### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` hive://${jdbc_connection_string} ``` ### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | HiveMuxCompositeHandler | | 메타데이터 핸들러 | HiveMuxMetadataHandler | | 레코드 핸들러 | HiveMuxRecordHandler | #### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 myhivecatalog인 경우 환경 변수 이름은 myhivecatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `hive1`(기본값)과 `hive2`라는 2개의 데이터베이스 인스턴스를 지원하는 Hive MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | hive://jdbc:hive2://hive1:10000/default?\$1\$1Test/RDS/hive1\$1 | | hive\$1catalog1\$1connection\$1string | hive://jdbc:hive2://hive1:10000/default?\$1\$1Test/RDS/hive1\$1 | | hive\$1catalog2\$1connection\$1string | hive://jdbc:hive2://hive2:10000/default?UID=sample&PWD=sample | #### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/RDS/hive1host}`입니다. ``` hive://jdbc:hive2://hive1host:10000/default?...&${Test/RDS/hive1host}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` hive://jdbc:hive2://hive1host:10000/default?...&UID=sample2&PWD=sample2&... ``` 현재 Hortonworks Hive 커넥터는 `UID` 및 `PWD` JDBC 속성을 인식합니다. ### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Hortonworks Hive 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | HiveCompositeHandler | | 메타데이터 핸들러 | HiveMetadataHandler | | 레코드 핸들러 | HiveRecordHandler | #### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Hortonworks Hive 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | hive://jdbc:hive2://hive1host:10000/default?secret=\$1\$1Test/RDS/hive1host\$1 | ### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC, Hortonworks Hive 및 Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | Hortonworks Hive | 화살표 | | --- | --- | --- | | 부울 | 부울 | Bit | | Integer | TINYINT | Tiny | | Short | SMALLINT | Smallint | | Integer | INT | 정수 | | Long | BIGINT | Bigint | | 실수 | float4 | Float4 | | 배정밀도 실수 | float8 | Float8 | | 날짜 | 날짜 | DateDay | | 타임스탬프 | timestamp | DateMilli | | 문자열 | VARCHAR | Varchar | | 바이트 | bytes | Varbinary | | BigDecimal | 10진수 | 10진수 | | ARRAY | 해당 사항 없음(참고 사항 참조) | List | **참고** 현재 Hortonworks Hive는 집계 유형 `ARRAY`, `MAP`, `STRUCT` 또는 `UNIONTYPE`을 지원하지 않습니다. 집계 유형의 열은 SQL에서 `VARCHAR` 열로 처리됩니다. ## 파티션 및 분할 파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다. ## 성능 Hortonworks Hive는 정적 파티션을 지원합니다. Athena Hortonworks Hive 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 정적 파티셔닝을 사용하는 것이 좋습니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. Hortonworks Hive 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. Athena Hortonworks Hive 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Hortonworks Hive 커넥터는 이러한 표현식을 결합하고 Hortonworks Hive로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Hortonworks Hive 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 패스스루 쿼리 Hortonworks Hive 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Hortonworks Hive에서 패스스루 쿼리를 사용하려면 다음 구문을 사용할 수 있습니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Hortonworks Hive의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Hortonworks Hive 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hortonworks-hive)를 참조하세요. # Amazon Athena Apache Kafka 커넥터 Apache Kafka용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 Apache Kafka 주제에서 SQL 쿼리를 실행할 수 있습니다. 이 커넥터를 사용하여 Athena에서 [Apache Kafka](https://kafka.apache.org/) 주제를 테이블로, 메시지를 행으로 볼 수 있습니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. ## 사전 조건 Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 필터 조건의 날짜 및 타임스탬프 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다. + 날짜 및 타임스탬프 데이터 형식은 CSV 파일 형식에 지원되지 않으며 varchar 값으로 처리됩니다. + 중첩된 JSON 필드로의 매핑은 지원되지 않습니다. 커넥터는 최상위 필드만 매핑합니다. + 커넥터는 복합 유형을 지원하지 않습니다. 복합 형식은 문자열로 해석됩니다. + 복잡한 JSON 값을 추출하거나 사용하려면 Athena에서 제공되는 JSON 관련 함수를 사용하세요. 자세한 내용은 [문자열에서 JSON 데이터 추출](extracting-data-from-JSON.md) 섹션을 참조하세요. + 커넥터는 Kafka 메시지 메타데이터에 대한 액세스를 지원하지 않습니다. ## 용어 + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **Kafka 엔드포인트** - Kafka 인스턴스에 연결하는 텍스트 문자열입니다. ## 클러스터 호환성 Kafka 커넥터는 다음과 같은 클러스터 유형과 함께 사용할 수 있습니다. + **독립 실행형 Kafka** - Kafka에 대한 직접 연결(인증된 연결 또는 인증되지 않은 연결)입니다. + **Confluent** – Confluent Kafka에 대한 직접 연결입니다. Confluent Kafka 데이터와 함께 Athena를 사용하는 방법에 대한 자세한 내용은 *AWS Business Intelligence Blog*의 [Visualize Confluent data in Quick using Amazon Athena](https://aws.amazon.com/blogs/business-intelligence/visualize-confluent-data-in-amazon-quicksight-using-amazon-athena/)를 참조하세요. ### Confluent에 연결 Confluent에 연결하려면 다음 단계를 수행해야 합니다. 1. Confluent에서 API 키를 생성합니다. 1. Confluent API 키의 사용자 이름과 암호를 AWS Secrets Manager에 저장합니다. 1. Kafka 커넥터에 `secrets_manager_secret` 환경 변수의 보안 암호 이름을 입력합니다. 1. 이 문서의 [Kafka 커넥터 설정](#connectors-kafka-setup) 섹션에 나온 단계를 수행합니다. ## 지원되는 인증 방법 커넥터에서 지원되는 인증 방법은 다음과 같습니다. + [SSL](https://kafka.apache.org/documentation/#security_ssl) + [SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram) + SASL/PLAIN + SASL/PLAINTEXT + NO\$1AUTH + **자체 관리형 Kafka 및 Confluent 플랫폼** – SSL, SASL/SCRAM, SASL/PLAINTEXT, NO\$1AUTH + **자체 관리형 Kafka 및 Confluent 플랫폼** – SASL/PLAIN 자세한 내용은 [Athena Kafka 커넥터에 대한 인증 구성](#connectors-kafka-setup-configuring-authentication) 섹션을 참조하세요. ## 지원되는 입력 데이터 형식 커넥터에서 지원되는 입력 데이터 형식은 다음과 같습니다. + JSON + CSV + AVRO + PROTOBUF(프로토콜 버퍼) ## 파라미터 이 섹션의 파라미터를 사용하여 Athena Kafka 커넥터를 구성합니다. + **auth\$1type** - 클러스터의 인증 유형을 지정합니다. 커넥터에서 지원되는 인증 유형은 다음과 같습니다. + **NO\$1AUTH** - Kafka에 직접 연결합니다. 예를 들어 인증을 사용하지 않는 EC2 인스턴스를 통해 배포되는 Kafka 클러스터에 연결합니다. + **SASL\$1SSL\$1PLAIN** - 이 메서드는 `SASL_SSL` 보안 프로토콜과 `PLAIN` SASL 메커니즘을 사용합니다. 자세한 내용은 Apache Kafka 설명서의 [SASL configuration](https://kafka.apache.org/documentation/#security_sasl_config)을 참조하세요. + **SASL\$1PLAINTEXT\$1PLAIN** - 이 메서드는 `SASL_PLAINTEXT` 보안 프로토콜과 `PLAIN` SASL 메커니즘을 사용합니다. 자세한 내용은 Apache Kafka 설명서의 [SASL configuration](https://kafka.apache.org/documentation/#security_sasl_config)을 참조하세요. + **SASL\$1SSL\$1SCRAM\$1SHA512** - 이 인증 유형을 사용하여 Apache Kafka 클러스터에 대한 액세스를 제어할 수 있습니다. 이 메서드는 사용자 이름과 암호를 AWS Secrets Manager에 저장합니다. 보안 암호는 Kafka 클러스터와 연결해야 합니다. 자세한 내용은 Apache Kafka 설명서의 [Authentication using SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram)을 참조하세요. + **SASL\$1PLAINTEXT\$1SCRAM\$1SHA512** – 이 메서드는 `SASL_PLAINTEXT` 보안 프로토콜 및 `SCRAM_SHA512 SASL` 메커니즘을 사용합니다. 이 메서드는 AWS Secrets Manager에 저장된 사용자 이름과 암호를 사용합니다. 자세한 내용은 Apache Kafka 설명서의 [SASL configuration](https://kafka.apache.org/documentation/#security_sasl_config) 섹션을 참조하세요. + **SSL** - SSL 인증은 키 스토어 및 트러스트 스토어 파일을 사용하여 Apache Kafka 클러스터에 연결합니다. 트러스트 스토어 파일과 키 스토어 파일을 생성하여 Amazon S3 버킷에 업로드하고 커넥터를 배포할 때 Amazon S3에 대한 참조를 제공해야 합니다. 키 스토어, 트러스트 스토어 및 SSL 키는 AWS Secrets Manager에 저장됩니다. 커넥터가 배포될 때 클라이언트가 AWS 보안 암호 키를 제공해야 합니다. 자세한 내용은 Apache Kafka 설명서의 [Encryption and Authentication using SSL](https://kafka.apache.org/documentation/#security_ssl)을 참조하세요. 자세한 내용은 [Athena Kafka 커넥터에 대한 인증 구성](#connectors-kafka-setup-configuring-authentication) 섹션을 참조하세요. + **certificates\$1s3\$1reference** - 인증서(키 스토어 및 트러스트 스토어 파일)가 들어 있는 Amazon S3 위치입니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **kafka\$1endpoint** - Kafka에 제공할 엔드포인트 세부 정보입니다. + **schema\$1registry\$1url** - 스키마 레지스트리의 URL 주소입니다(예: `http://schema-registry.example.org:8081`). `AVRO` 및 `PROTOBUF` 데이터 형식에 적용됩니다. Athena는 Confluent 스키마 레지스트리만 지원합니다. + **secrets\$1manager\$1secret** - 보안 인증이 저장되는 AWS 보안 암호의 이름입니다. + **유출 파라미터** - Lambda 함수는 메모리에 맞지 않는 데이터를 Amazon S3에 임시로 저장(“유출”)합니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. 다음 표의 파라미터를 사용하여 유출 위치를 지정합니다. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-kafka.html) + **서브넷 ID** – Lambda 함수가 데이터 소스에 액세스하는 데 사용할 수 있는 서브넷에 해당하는 하나 이상의 서브넷 ID입니다. + **퍼블릭 Kafka 클러스터 또는 표준 Confluent Cloud 클러스터** - 커넥터를 NAT 게이트웨이가 있는 프라이빗 서브넷에 연결합니다. + **프라이빗 연결을 제공하는 Confluent Cloud 클러스터** - Confluent Cloud 클러스터로 연결되는 경로가 있는 프라이빗 서브넷에 커넥터를 연결합니다. + [AWS Transit Gateway](https://docs.confluent.io/cloud/current/networking/aws-transit-gateway.html)의 경우 서브넷은 Confluent Cloud가 사용하는 것과 동일한 전송 게이트웨이에 연결된 VPC에 있어야 합니다. + [VPC 피어링](https://docs.confluent.io/cloud/current/networking/peering/aws-peering.html)의 경우 서브넷은 Confluent Cloud VPC에 피어링된 VPC에 있어야 합니다. + [AWS PrivateLink](https://docs.confluent.io/cloud/current/networking/private-links/aws-privatelink.html)의 경우 서브넷은 Confluent Cloud에 연결된 VPC 엔드포인트로 연결되는 경로가 있는 VPC에 있어야 합니다. **참고** 프라이빗 리소스에 액세스하기 위해 커넥터를 VPC에 배포하고 Confluent와 같이 공개적으로 액세스 가능한 서비스에도 연결하려는 경우 커넥터를 NAT 게이트웨이가 있는 프라이빗 서브넷과 연결해야 합니다. 자세한 정보는 Amazon VPC 사용 설명서의 [NAT 게이트웨이](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)를 참조하세요. ## 데이터 형식 지원 다음 표에 Kafka와 Apache Arrow에 대해 지원되는 해당 데이터 형식이 나와 있습니다. **** | Kafka | 화살표 | | --- | --- | | CHAR | VARCHAR | | VARCHAR | VARCHAR | | TIMESTAMP | MILLISECOND | | DATE | DAY | | BOOLEAN | BOOL | | SMALLINT | SMALLINT | | INTEGER | INT | | BIGINT | BIGINT | | DECIMAL | FLOAT8 | | DOUBLE | FLOAT8 | ## 파티션 및 분할 Kafka 주제는 파티션으로 분할됩니다. 각 파티션은 순서대로 정렬됩니다. 파티션의 각 메시지에는 offset이라는 증분 ID가 있습니다.** 각 Kafka 파티션은 병렬 처리를 위해 다시 여러 영역으로 분할됩니다. 데이터는 Kafka 클러스터에 구성된 보존 기간 동안 사용할 수 있습니다. ## 모범 사례 다음 예와 같이 Athena를 쿼리할 때 조건자 푸시다운을 사용하는 것이 좋습니다. ``` SELECT * FROM "kafka_catalog_name"."glue_schema_registry_name"."glue_schema_name" WHERE integercol = 2147483647 ``` ``` SELECT * FROM "kafka_catalog_name"."glue_schema_registry_name"."glue_schema_name" WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878' ``` ## Kafka 커넥터 설정 커넥터를 사용하려면 먼저 Apache Kafka 클러스터를 설정하고, [AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)를 사용하여 스키마를 정의하고, 커넥터에 대한 인증을 구성해야 합니다. AWS Glue Schema Registry에서 작업할 경우 다음 사항에 유의하세요. + AWS Glue Schema Registry의 **Description**(설명) 필드에 있는 텍스트에 `{AthenaFederationKafka}` 문자열이 포함되어 있는지 확인합니다. 이 마커 문자열은 Amazon Athena Kafka 커넥터와 함께 사용하는 AWS Glue 레지스트리에 필요합니다. + 최상의 성능을 얻으려면 데이터베이스 이름과 테이블 이름에 소문자만 사용합니다. 대/소문자를 혼합하여 사용하면 커넥터에서 대소문자를 구분하지 않고 검색하므로 더욱 컴퓨팅 집약적입니다. **Apache Kafka 환경 및 AWS Glue Schema Registry를 설정하려면** 1. Apache Kafka 환경을 설정합니다. 1. JSON 형식의 Kafka 주제 설명 파일, 즉, 스키마를 AWS Glue Schema Registry에 업로드합니다. 자세한 내용은 AWS Glue 개발자 안내서의 [AWS Glue Schema Registry와 통합](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html)을 참조하세요. 1. AWS Glue 스키마 레지스트리에서 스키마를 정의할 때 `AVRO` 또는 `PROTOBUF` 데이터 형식을 사용하는 방법: + **Schema name**에 Kafka 주제 이름을 원본과 같은 대/소문자로 입력합니다. + **Data format**에서 **Apache Avro** 또는**Protocol Buffers**를 선택합니다. 스키마 예는 다음 단원을 참조하세요. ### AWS Glue Schema Registry의 스키마 예 스키마를 [AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)에 업로드할 경우 이 단원의 예제 형식을 사용하세요. #### JSON 유형 스키마 예 다음 예제에서 AWS Glue Schema Registry에서 생성할 스키마는 `json`을 `dataFormat`의 값으로 지정하고 `datatypejson`을 `topicName`에 사용합니다. **참고** `topicName`의 값에서는 Kafka의 주제 이름과 동일한 대/소문자를 사용해야 합니다. ``` { "topicName": "datatypejson", "message": { "dataFormat": "json", "fields": [ { "name": "intcol", "mapping": "intcol", "type": "INTEGER" }, { "name": "varcharcol", "mapping": "varcharcol", "type": "VARCHAR" }, { "name": "booleancol", "mapping": "booleancol", "type": "BOOLEAN" }, { "name": "bigintcol", "mapping": "bigintcol", "type": "BIGINT" }, { "name": "doublecol", "mapping": "doublecol", "type": "DOUBLE" }, { "name": "smallintcol", "mapping": "smallintcol", "type": "SMALLINT" }, { "name": "tinyintcol", "mapping": "tinyintcol", "type": "TINYINT" }, { "name": "datecol", "mapping": "datecol", "type": "DATE", "formatHint": "yyyy-MM-dd" }, { "name": "timestampcol", "mapping": "timestampcol", "type": "TIMESTAMP", "formatHint": "yyyy-MM-dd HH:mm:ss.SSS" } ] } } ``` #### CSV 유형 스키마 예 다음 예제에서 AWS Glue Schema Registry에서 생성할 스키마는 `csv`을 `dataFormat`의 값으로 지정하고 `datatypecsvbulk`을 `topicName`에 사용합니다. `topicName`의 값에서는 Kafka의 주제 이름과 동일한 대/소문자를 사용해야 합니다. ``` { "topicName": "datatypecsvbulk", "message": { "dataFormat": "csv", "fields": [ { "name": "intcol", "type": "INTEGER", "mapping": "0" }, { "name": "varcharcol", "type": "VARCHAR", "mapping": "1" }, { "name": "booleancol", "type": "BOOLEAN", "mapping": "2" }, { "name": "bigintcol", "type": "BIGINT", "mapping": "3" }, { "name": "doublecol", "type": "DOUBLE", "mapping": "4" }, { "name": "smallintcol", "type": "SMALLINT", "mapping": "5" }, { "name": "tinyintcol", "type": "TINYINT", "mapping": "6" }, { "name": "floatcol", "type": "DOUBLE", "mapping": "7" } ] } } ``` #### AVRO 유형 스키마 예 다음 예제는 AWS Glue 스키마 레지스트리에 Avro 기반 스키마를 생성하는 데 사용됩니다. AWS Glue 스키마 레지스트리에서 스키마를 정의할 때 **Schema name**에는 원본과 동일한 대/소문자로 Kafka 주제 이름을 입력하고 **Data format**에는 **Apache Avro**를 선택합니다. 레지스트리에서 이 정보를 직접 지정하므로 `dataformat` 및 `topicName` 필드는 필요하지 않습니다. ``` { "type": "record", "name": "avrotest", "namespace": "example.com", "fields": [{ "name": "id", "type": "int" }, { "name": "name", "type": "string" } ] } ``` #### PROTOBUF 유형 스키마 예 다음 예제는 AWS Glue 스키마 레지스트리에 PROTOBUF 기반 스키마를 생성하는 데 사용됩니다. AWS Glue 스키마 레지스트리에서 스키마를 정의할 때 **Schema name**에는 원본과 동일한 대/소문자로 Kafka 주제 이름을 입력하고 **Data format**에는 **Protocol Buffers**를 선택합니다. 레지스트리에서 이 정보를 직접 지정하므로 `dataformat` 및 `topicName` 필드는 필요하지 않습니다. 첫 번째 줄은 스키마를 PROTOBUF로 정의합니다. ``` syntax = "proto3"; message protobuftest { string name = 1; int64 calories = 2; string colour = 3; } ``` AWS Glue 스키마 레지스트리에 레지스트리와 스키마를 추가하는 방법에 대한 자세한 내용은 AWS Glue 설명서의 [Getting started with Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-gs.html)를 참조하세요. ### Athena Kafka 커넥터에 대한 인증 구성 SSL, SASL/SCRAM, SASL/PLAIN, SASL/PLAINTEXT를 비롯한 다양한 방법을 사용하여 Apache Kafka 클러스터에 대한 인증을 수행할 수 있습니다. 다음 표에는 커넥터의 인증 유형과 각 유형에 대한 보안 프로토콜 및 SASL 메커니즘이 나와 있습니다. 자세한 내용은 Apache Kafka 설명서의 [Security](https://kafka.apache.org/documentation/#security) 섹션을 참조하세요. **** | auth\$1type | security.protocol | sasl.mechanism | 클러스터 유형 호환성 | | --- | --- | --- | --- | | SASL\$1SSL\$1PLAIN | SASL\$1SSL | PLAIN | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-kafka.html) | | SASL\$1PLAINTEXT\$1PLAIN | SASL\$1PLAINTEXT | PLAIN | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-kafka.html) | | SASL\$1SSL\$1SCRAM\$1SHA512 | SASL\$1SSL | SCRAM-SHA-512 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-kafka.html) | | SASL\$1PLAINTEXT\$1SCRAM\$1SHA512 | SASL\$1PLAINTEXT | SCRAM-SHA-512 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-kafka.html) | | SSL | SSL | 해당 사항 없음 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-kafka.html) | #### SSL 클러스터가 SSL 인증을 받은 경우 트러스트 스토어와 키 스토어 파일을 생성하여 Amazon S3 버킷에 업로드해야 합니다. 커넥터를 배포할 때 이 Amazon S3 참조를 제공해야 합니다. 키 스토어, 트러스트 스토어 및 SSL 키는 AWS Secrets Manager에 저장됩니다. 커넥터를 배포할 때 AWS 비밀 키를 제공합니다. Secrets Manager에서 보안 암호를 생성하는 방법에 대한 자세한 내용은 [AWS Secrets Manager 보안 암호 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)을 참조하세요. 이 인증 유형을 사용하려면 다음 표에 표시된 대로 환경 변수를 설정합니다. **** | 파라미터 | 값 | | --- | --- | | auth\$1type | SSL | | certificates\$1s3\$1reference | 인증서가 포함된 Amazon S3 위치입니다. | | secrets\$1manager\$1secret | AWS 비밀 키의 이름입니다. | Secrets Manager에서 보안 암호를 생성한 이후에 Secrets Manager 콘솔에서 보안 암호를 볼 수 있습니다. **Secrets Manager에서 보안 암호를 보려면** 1. [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)에서 Secrets Manager 콘솔을 엽니다. 1. 탐색 창에서 **Secrets**(보안 암호)를 선택합니다. 1. **Secrets**(보안 암호) 페이지에서 보안 암호에 대한 링크를 선택합니다. 1. 보안 암호에 대한 세부 정보 페이지에서 **Retrieve secret value**(보안 암호 값 검색)를 선택합니다. 다음 이미지는 세 개의 키/값 쌍(`keystore_password`, `truststore_password`, `ssl_key_password`)을 가진 보안 암호의 예를 보여줍니다. ![\[Secrets Manager에서 SSL 보안 암호 검색\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-kafka-setup-1.png) Kafka에서 SSL을 사용하는 방법에 대한 자세한 내용은 Apache Kafka 설명서의 [Encryption and Authentication using SSL](https://kafka.apache.org/documentation/#security_ssl)을 참조하세요. #### SASL/SCRAM 클러스터에서 SCRAM 인증을 사용하는 경우 커넥터를 배포할 때 클러스터와 연결되는 Secrets Manager 키를 제공합니다. 사용자의 AWS 보안 인증(비밀 키 및 액세스 키)은 클러스터에 인증하는 데 사용됩니다. 다음 표에 표시된 대로 환경 변수를 설정합니다. **** | 파라미터 | 값 | | --- | --- | | auth\$1type | SASL\$1SSL\$1SCRAM\$1SHA512 | | secrets\$1manager\$1secret | AWS 비밀 키의 이름입니다. | 다음 이미지는 Secrets Manager 콘솔에서 `username` 및 `password`에 대해 하나씩 두 개의 키/값 쌍으로 구성된 보안 암호의 예를 보여줍니다. ![\[Secrets Manager에서 SCRAM 보안 암호 검색\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-kafka-setup-2.png) Kafka에서 SASL/SCRAM을 사용하는 방법에 대한 자세한 내용은 Apache Kafka 설명서의 [Authentication using SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram)을 참조하세요. ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-kafka/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-kafka/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-kafka)를 참조하세요. # Amazon Athena MSK 커넥터 [Amazon MSK](https://aws.amazon.com/msk/)용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 Apache Kafka 주제에 대해 SQL 쿼리를 실행할 수 있습니다. 이 커넥터를 사용하여 Athena에서 [Apache Kafka](https://kafka.apache.org/) 주제를 테이블로, 메시지를 행으로 볼 수 있습니다. 자세한 내용은 AWS 빅 데이터 블로그에서 [Amazon Athena를 사용하여 Amazon MSK에서 실시간 스트리밍 데이터 분석](https://aws.amazon.com/blogs/big-data/analyze-real-time-streaming-data-in-amazon-msk-with-amazon-athena/)을 참조하세요. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. ## 사전 조건 Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 필터 조건의 날짜 및 타임스탬프 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다. + 날짜 및 타임스탬프 데이터 형식은 CSV 파일 형식에 지원되지 않으며 varchar 값으로 처리됩니다. + 중첩된 JSON 필드로의 매핑은 지원되지 않습니다. 커넥터는 최상위 필드만 매핑합니다. + 커넥터는 복합 유형을 지원하지 않습니다. 복합 형식은 문자열로 해석됩니다. + 복잡한 JSON 값을 추출하거나 사용하려면 Athena에서 제공되는 JSON 관련 함수를 사용하세요. 자세한 내용은 [문자열에서 JSON 데이터 추출](extracting-data-from-JSON.md) 섹션을 참조하세요. + 커넥터는 Kafka 메시지 메타데이터에 대한 액세스를 지원하지 않습니다. ## 용어 + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **Kafka 엔드포인트** - Kafka 인스턴스에 연결하는 텍스트 문자열입니다. ## 클러스터 호환성 MSK 커넥터는 다음과 같은 클러스터 유형과 함께 사용할 수 있습니다. + **MSK 프로비저닝 클러스터** - 클러스터 용량을 수동으로 지정, 모니터링 및 조정합니다. + **MSK 서버리스 클러스터** - 애플리케이션 I/O가 확장되면 자동으로 확장되는 온디맨드 용량을 제공합니다. + **독립 실행형 Kafka** - Kafka에 대한 직접 연결(인증된 연결 또는 인증되지 않은 연결)입니다. ## 지원되는 인증 방법 커넥터에서 지원되는 인증 방법은 다음과 같습니다. + [SAL/IAM](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html) + [SSL](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html) + [SASL/SCRAM](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html) + SASL/PLAIN + SASL/PLAINTEXT + NO\$1AUTH 자세한 내용은 [Athena MSK 커넥터에 대한 인증 구성](#connectors-msk-setup-configuring-authentication) 섹션을 참조하세요. ## 지원되는 입력 데이터 형식 커넥터에서 지원되는 입력 데이터 형식은 다음과 같습니다. + JSON + CSV ## 파라미터 이 섹션의 파라미터를 사용하여 Athena MSK 커넥터를 구성합니다. + **auth\$1type** - 클러스터의 인증 유형을 지정합니다. 커넥터에서 지원되는 인증 유형은 다음과 같습니다. + **NO\$1AUTH** - 인증 없이 Kafka에 직접 연결합니다. 예를 들어 인증을 사용하지 않는 EC2 인스턴스를 통해 배포되는 Kafka 클러스터에 연결합니다. + **SASL\$1SSL\$1PLAIN** - 이 메서드는 `SASL_SSL` 보안 프로토콜과 `PLAIN` SASL 메커니즘을 사용합니다. + **SASL\$1PLAINTEXT\$1PLAIN** - 이 메서드는 `SASL_PLAINTEXT` 보안 프로토콜과 `PLAIN` SASL 메커니즘을 사용합니다. **참고** `SASL_SSL_PLAIN` 및 `SASL_PLAINTEXT_PLAIN` 인증 유형은 Apache Kafka에서 지원되지만 Amazon MSK에서는 지원되지 않습니다. + **SASL\$1SSL\$1AWS\$1MSK\$1IAM** - Amazon MSK용 IAM 액세스 제어를 사용하여 MSK 클러스터에 대한 인증과 권한 부여를 모두 처리할 수 있습니다. 사용자 AWS 보안 인증(비밀 키 및 액세스 키)은 클러스터에 연결하는 데 사용됩니다. 자세한 내용은 Amazon Managed Streaming for Apache Kafka 개발자 안내서의 [IAM 액세스 제어](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html)를 참조하세요. + **SASL\$1SSL\$1SCRAM\$1SHA512** - 이 인증 유형을 사용하여 Amazon MSK 클러스터에 대한 액세스를 제어할 수 있습니다. 이 메서드는 사용자 이름과 암호를 AWS Secrets Manager에 저장합니다. 보안 암호를 Amazon MSK 클러스터와 연결해야 합니다. 자세한 내용은 Amazon Managed Streaming for Apache Kafka 개발자 안내서의 [Amazon MSK 클러스터에 대한 SASL/SCRAM 인증 설정](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html#msk-password-tutorial)을 참조하세요. + **SSL** - SSL 인증은 키 스토어 및 트러스트 스토어 파일을 사용하여 Amazon MSK 클러스터와 연결합니다. 트러스트 스토어 파일과 키 스토어 파일을 생성하여 Amazon S3 버킷에 업로드하고 커넥터를 배포할 때 Amazon S3에 대한 참조를 제공해야 합니다. 키 스토어, 트러스트 스토어 및 SSL 키는 AWS Secrets Manager에 저장됩니다. 커넥터가 배포될 때 클라이언트가 AWS 보안 암호 키를 제공해야 합니다. 자세한 내용은 Amazon Managed Streaming for Apache Kafka 개발자 안내서의 [상호 TLS 인증](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html)을 참조하세요. 자세한 내용은 [Athena MSK 커넥터에 대한 인증 구성](#connectors-msk-setup-configuring-authentication) 섹션을 참조하세요. + **certificates\$1s3\$1reference** - 인증서(키 스토어 및 트러스트 스토어 파일)가 들어 있는 Amazon S3 위치입니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **kafka\$1endpoint** - Kafka에 제공할 엔드포인트 세부 정보입니다. 예를 들어 Amazon MSK 클러스터의 경우 클러스터의 [부트스트랩 URL](https://docs.aws.amazon.com/msk/latest/developerguide/msk-get-bootstrap-brokers.html)을 제공합니다. + **secrets\$1manager\$1secret** - 보안 인증이 저장되는 AWS 보안 암호의 이름입니다. IAM 인증에는 이 파라미터가 필요하지 않습니다. + **유출 파라미터** - Lambda 함수는 메모리에 맞지 않는 데이터를 Amazon S3에 임시로 저장(“유출”)합니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. 다음 표의 파라미터를 사용하여 유출 위치를 지정합니다. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/connectors-msk.html) ## 데이터 형식 지원 다음 표에 Kafka와 Apache Arrow에 대해 지원되는 해당 데이터 형식이 나와 있습니다. **** | Kafka | 화살표 | | --- | --- | | CHAR | VARCHAR | | VARCHAR | VARCHAR | | TIMESTAMP | MILLISECOND | | DATE | DAY | | BOOLEAN | BOOL | | SMALLINT | SMALLINT | | INTEGER | INT | | BIGINT | BIGINT | | DECIMAL | FLOAT8 | | DOUBLE | FLOAT8 | ## 파티션 및 분할 Kafka 주제는 파티션으로 분할됩니다. 각 파티션은 순서대로 정렬됩니다. 파티션의 각 메시지에는 offset이라는 증분 ID가 있습니다.** 각 Kafka 파티션은 병렬 처리를 위해 다시 여러 영역으로 분할됩니다. 데이터는 Kafka 클러스터에 구성된 보존 기간 동안 사용할 수 있습니다. ## 모범 사례 다음 예와 같이 Athena를 쿼리할 때 조건자 푸시다운을 사용하는 것이 좋습니다. ``` SELECT * FROM "msk_catalog_name"."glue_schema_registry_name"."glue_schema_name" WHERE integercol = 2147483647 ``` ``` SELECT * FROM "msk_catalog_name"."glue_schema_registry_name"."glue_schema_name" WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878' ``` ## MSK 커넥터 설정 커넥터를 사용하려면 먼저 Amazon MSK 클러스터를 설정하고, [AWS Glue 스키마 레지스트리](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)를 사용하여 스키마를 정의하고, 커넥터에 대한 인증을 구성해야 합니다. **참고** 프라이빗 리소스에 액세스하기 위해 커넥터를 VPC에 배포하고 Confluent와 같이 공개적으로 액세스 가능한 서비스에도 연결하려는 경우 커넥터를 NAT 게이트웨이가 있는 프라이빗 서브넷과 연결해야 합니다. 자세한 정보는 Amazon VPC 사용 설명서의 [NAT 게이트웨이](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)를 참조하세요. AWS Glue Schema Registry에서 작업할 경우 다음 사항에 유의하세요. + AWS Glue Schema Registry의 **Description**(설명) 필드에 있는 텍스트에 `{AthenaFederationMSK}` 문자열이 포함되어 있는지 확인합니다. 이 마커 문자열은 Amazon Athena MSK 커넥터와 함께 사용하는 AWS Glue 레지스트리에 필요합니다. + 최상의 성능을 얻으려면 데이터베이스 이름과 테이블 이름에 소문자만 사용합니다. 대/소문자를 혼합하여 사용하면 커넥터에서 대소문자를 구분하지 않고 검색하므로 더욱 컴퓨팅 집약적입니다. **Amazon MSK 환경 및 AWS Glue Schema Registry를 설정하려면** 1. Amazon MSK 환경을 설정합니다. 자세한 내용은 Amazon Managed Streaming for Apache Kafka 개발자 안내서의 [Amazon MSK 설정](https://docs.aws.amazon.com/msk/latest/developerguide/before-you-begin.html) 및 [Amazon MSK 사용 시작하기](https://docs.aws.amazon.com/msk/latest/developerguide/getting-started.html)를 참조하세요. 1. JSON 형식의 Kafka 주제 설명 파일, 즉, 스키마를 AWS Glue Schema Registry에 업로드합니다. 자세한 내용은 AWS Glue 개발자 안내서의 [AWS Glue Schema Registry와 통합](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html)을 참조하세요. 스키마 예는 다음 단원을 참조하세요. ### AWS Glue Schema Registry의 스키마 예 스키마를 [AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)에 업로드할 경우 이 단원의 예제 형식을 사용하세요. #### JSON 유형 스키마 예 다음 예제에서 AWS Glue Schema Registry에서 생성할 스키마는 `json`을 `dataFormat`의 값으로 지정하고 `datatypejson`을 `topicName`에 사용합니다. **참고** `topicName`의 값에서는 Kafka의 주제 이름과 동일한 대/소문자를 사용해야 합니다. ``` { "topicName": "datatypejson", "message": { "dataFormat": "json", "fields": [ { "name": "intcol", "mapping": "intcol", "type": "INTEGER" }, { "name": "varcharcol", "mapping": "varcharcol", "type": "VARCHAR" }, { "name": "booleancol", "mapping": "booleancol", "type": "BOOLEAN" }, { "name": "bigintcol", "mapping": "bigintcol", "type": "BIGINT" }, { "name": "doublecol", "mapping": "doublecol", "type": "DOUBLE" }, { "name": "smallintcol", "mapping": "smallintcol", "type": "SMALLINT" }, { "name": "tinyintcol", "mapping": "tinyintcol", "type": "TINYINT" }, { "name": "datecol", "mapping": "datecol", "type": "DATE", "formatHint": "yyyy-MM-dd" }, { "name": "timestampcol", "mapping": "timestampcol", "type": "TIMESTAMP", "formatHint": "yyyy-MM-dd HH:mm:ss.SSS" } ] } } ``` #### CSV 유형 스키마 예 다음 예제에서 AWS Glue Schema Registry에서 생성할 스키마는 `csv`을 `dataFormat`의 값으로 지정하고 `datatypecsvbulk`을 `topicName`에 사용합니다. `topicName`의 값에서는 Kafka의 주제 이름과 동일한 대/소문자를 사용해야 합니다. ``` { "topicName": "datatypecsvbulk", "message": { "dataFormat": "csv", "fields": [ { "name": "intcol", "type": "INTEGER", "mapping": "0" }, { "name": "varcharcol", "type": "VARCHAR", "mapping": "1" }, { "name": "booleancol", "type": "BOOLEAN", "mapping": "2" }, { "name": "bigintcol", "type": "BIGINT", "mapping": "3" }, { "name": "doublecol", "type": "DOUBLE", "mapping": "4" }, { "name": "smallintcol", "type": "SMALLINT", "mapping": "5" }, { "name": "tinyintcol", "type": "TINYINT", "mapping": "6" }, { "name": "floatcol", "type": "DOUBLE", "mapping": "7" } ] } } ``` ### Athena MSK 커넥터에 대한 인증 구성 IAM, SSL, SCRAM, 독립 실행형 Kafka를 비롯한 다양한 방법으로 Amazon MSK 클러스터에 인증할 수 있습니다. 다음 표에는 커넥터의 인증 유형과 각 유형에 대한 보안 프로토콜 및 SASL 메커니즘이 나와 있습니다. 자세한 내용은 Amazon Managed Streaming for Apache Kafka 개발자 안내서의 [Apache Kafka API에 대한 인증 및 권한 부여](https://docs.aws.amazon.com/msk/latest/developerguide/kafka_apis_iam.html)를 참조하세요. **** | auth\$1type | security.protocol | sasl.mechanism | | --- | --- | --- | | SASL\$1SSL\$1PLAIN | SASL\$1SSL | PLAIN | | SASL\$1PLAINTEXT\$1PLAIN | SASL\$1PLAINTEXT | PLAIN | | SASL\$1SSL\$1AWS\$1MSK\$1IAM | SASL\$1SSL | AWS\$1MSK\$1IAM | | SASL\$1SSL\$1SCRAM\$1SHA512 | SASL\$1SSL | SCRAM-SHA-512 | | SSL | SSL | 해당 사항 없음 | **참고** `SASL_SSL_PLAIN` 및 `SASL_PLAINTEXT_PLAIN` 인증 유형은 Apache Kafka에서 지원되지만 Amazon MSK에서는 지원되지 않습니다. #### SASL/IAM 클러스터에서 IAM 인증을 사용하는 경우 클러스터를 설정할 때 사용자에 대한 IAM 정책을 구성해야 합니다. 자세한 내용은 Amazon Managed Streaming for Apache Kafka 개발자 안내서의 [IAM 액세스 제어](https://docs.aws.amazon.com/msk/latest/developerguide/IAM-access-control.html)를 참조하세요. 이 인증 유형을 사용하려면 커넥터에 대한 `auth_type` Lambda 환경 변수를 `SASL_SSL_AWS_MSK_IAM`으로 설정합니다. #### SSL 클러스터가 SSL 인증을 받은 경우 트러스트 스토어와 키 스토어 파일을 생성하여 Amazon S3 버킷에 업로드해야 합니다. 커넥터를 배포할 때 이 Amazon S3 참조를 제공해야 합니다. 키 스토어, 트러스트 스토어 및 SSL 키는 AWS Secrets Manager에 저장됩니다. 커넥터를 배포할 때 AWS 비밀 키를 제공합니다. Secrets Manager에서 보안 암호를 생성하는 방법에 대한 자세한 내용은 [AWS Secrets Manager 보안 암호 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)을 참조하세요. 이 인증 유형을 사용하려면 다음 표에 표시된 대로 환경 변수를 설정합니다. **** | 파라미터 | 값 | | --- | --- | | auth\$1type | SSL | | certificates\$1s3\$1reference | 인증서가 포함된 Amazon S3 위치입니다. | | secrets\$1manager\$1secret | AWS 비밀 키의 이름입니다. | Secrets Manager에서 보안 암호를 생성한 이후에 Secrets Manager 콘솔에서 보안 암호를 볼 수 있습니다. **Secrets Manager에서 보안 암호를 보려면** 1. [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)에서 Secrets Manager 콘솔을 엽니다. 1. 탐색 창에서 **Secrets**(보안 암호)를 선택합니다. 1. **Secrets**(보안 암호) 페이지에서 보안 암호에 대한 링크를 선택합니다. 1. 보안 암호에 대한 세부 정보 페이지에서 **Retrieve secret value**(보안 암호 값 검색)를 선택합니다. 다음 이미지는 세 개의 키/값 쌍(`keystore_password`, `truststore_password`, `ssl_key_password`)을 가진 보안 암호의 예를 보여줍니다. ![\[Secrets Manager에서 SSL 보안 암호 검색\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-msk-setup-1.png) #### SASL/SCRAM 클러스터에서 SCRAM 인증을 사용하는 경우 커넥터를 배포할 때 클러스터와 연결되는 Secrets Manager 키를 제공합니다. 사용자의 AWS 보안 인증(비밀 키 및 액세스 키)은 클러스터에 인증하는 데 사용됩니다. 다음 표에 표시된 대로 환경 변수를 설정합니다. **** | 파라미터 | 값 | | --- | --- | | auth\$1type | SASL\$1SSL\$1SCRAM\$1SHA512 | | secrets\$1manager\$1secret | AWS 비밀 키의 이름입니다. | 다음 이미지는 Secrets Manager 콘솔에서 `username` 및 `password`에 대해 하나씩 두 개의 키/값 쌍으로 구성된 보안 암호의 예를 보여줍니다. ![\[Secrets Manager에서 SCRAM 보안 암호 검색\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-msk-setup-2.png) ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-msk/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-msk/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-msk)를 참조하세요. # Amazon Athena MySQL 커넥터 Amazon Athena는 Amazon Athena Lambda MySQL 커넥터를 통해 MySQL 데이터베이스에 액세스할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. + 이 커넥터를 사용하기 전에 VPC와 보안 그룹을 설정합니다. 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + Athena는 쿼리를 소문자로 변환하므로 MySQL 테이블 이름은 소문자여야 합니다. 예를 들어, `myTable`이라는 테이블에 대한 Athena 쿼리는 실패합니다. + MySQL 연결을 Glue Catalog 및 Lake Formation으로 마이그레이션하면 소문자 테이블과 열 이름만 인식됩니다. ## 용어 다음 용어는 MySQL 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 MySQL 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 MySQL 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 MySQL 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type MYSQL ``` **Lambda 환경 속성** **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 MySQL 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 MySQL 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` mysql://${jdbc_connection_string} ``` **참고** MySQL 테이블에서 `SELECT` 쿼리를 수행할 때 java.sql.SQLException: Zero date value prohibited(java.sql.SQLException: 0 날짜 값 금지) 오류가 발생하면 연결 문자열에 다음 파라미터를 추가합니다. ``` zeroDateTimeBehavior=convertToNull ``` 자세한 내용을 알아보려면 GitHub.com의 [Error 'Zero date value prohibited' while trying to select from MySQL table](https://github.com/awslabs/aws-athena-query-federation/issues/760)(MySQL 테이블에서 선택하는 동안 '0 날짜 값 금지' 오류)를 참조하세요. #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | MySqlMuxCompositeHandler | | 메타데이터 핸들러 | MySqlMuxMetadataHandler | | 레코드 핸들러 | MySqlMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mymysqlcatalog인 경우 환경 변수 이름은 mymysqlcatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `mysql1`(기본값)과 `mysql2`라는 2개의 데이터베이스 인스턴스를 지원하는 MySql MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | mysql://jdbc:mysql://mysql2.host:3333/default?user=sample2&password=sample2 | | mysql\$1catalog1\$1connection\$1string | mysql://jdbc:mysql://mysql1.host:3306/default?\$1\$1Test/RDS/MySql1\$1 | | mysql\$1catalog2\$1connection\$1string | mysql://jdbc:mysql://mysql2.host:3333/default?user=sample2&password=sample2 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/RDS/MySql1}`입니다. ``` mysql://jdbc:mysql://mysql1.host:3306/default?...&${Test/RDS/MySql1}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` mysql://jdbc:mysql://mysql1host:3306/default?...&user=sample2&password=sample2&... ``` 현재 MySQL 커넥터는 `user` 및 `password` JDBC 속성을 인식합니다. #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 MySQL 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | MySqlCompositeHandler | | 메타데이터 핸들러 | MySqlMetadataHandler | | 레코드 핸들러 | MySqlRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 MySQL 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | mysql://mysql1.host:3306/default?secret=Test/RDS/MySql1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC와 Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | 화살표 | | --- | --- | | 부울 | Bit | | Integer | Tiny | | Short | Smallint | | Integer | 정수 | | Long | Bigint | | 실수 | Float4 | | 배정밀도 실수 | Float8 | | 날짜 | DateDay | | 타임스탬프 | DateMilli | | 문자열 | Varchar | | 바이트 | Varbinary | | BigDecimal | 10진수 | | ARRAY | List | ## 파티션 및 분할 파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다. ## 성능 MySQL은 기본 파티션을 지원합니다. Athena MySQL 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다. Athena MySQL 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena MySQL 커넥터는 이러한 표현식을 결합하고 MySQL로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena MySQL 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` MySQL을 비롯한 페더레이션된 쿼리의 성능을 개선하기 위해 조건자 푸시다운을 사용하는 방법에 대한 문서는 *AWS 빅 데이터 블로그*의 [Improve federated queries with predicate pushdown in Amazon Athena](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)를 참조하세요. ## 패스스루 쿼리 MySQL 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. MySQL에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 MySQL의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 MySQL 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-mysql)를 참조하세요. # Amazon Athena Neptune 커넥터 Amazon Neptune은 빠르고 안정적인 종합 관리형 그래프 데이터베이스 서비스로, 고도로 연결된 데이터 세트를 사용하는 애플리케이션을 쉽게 빌드하고 실행할 수 있습니다. Neptune의 특수 목적 고성능 그래프 데이터베이스 엔진은 수십억 개의 관계를 최적으로 저장하고 단 몇 밀리초의 지연 시간으로 그래프를 쿼리합니다. 자세한 내용은 [Neptune 사용 설명서](https://docs.aws.amazon.com/neptune/latest/userguide/intro.html)를 참조하세요. Amazon Athena Neptune 커넥터를 통해 Athena는 Neptune 그래프 데이터베이스 인스턴스와 통신할 수 있고, 이로써 SQL 쿼리로 Neptune 그래프 데이터에 액세스할 수 있습니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. 계정에서 Lake Formation을 활성화한 경우 AWS Serverless Application Repository에 배포한 Athena 페더레이션형 Lambda 커넥터의 IAM 역할은 Lake Formation에서 AWS Glue Data Catalog에 대한 읽기 액세스 권한을 가지고 있어야 합니다. ## 사전 조건 Neptune 커넥터를 사용하려면 다음 세 단계가 필요합니다. + Neptune 클러스터 설정 + AWS Glue Data Catalog 설정 + AWS 계정에 커넥터 배포 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. Neptune 커넥터 배포와 관련된 자세한 내용을 알아보려면 GitHub.com의 [Deploy the Amazon Athena Neptune Connector](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/neptune-connector-setup)(Amazon Athena Neptune 커넥터 배포)를 참조하세요. ## 제한 사항 현재 Neptune 커넥터에는 다음과 같은 제한 사항이 있습니다. + 프라이머리 키(ID)를 비롯한 예측 열은 지원되지 않습니다. ## Neptune 클러스터 설정 사용하려는 기존 Amazon Neptune 클러스터 및 속성 그래프 데이터 세트가 없는 경우 하나 설정해야 합니다. Neptune 클러스터를 호스팅하는 VPC에 인터넷 게이트웨이와 NAT 게이트웨이가 있는지 확인합니다. Neptune 커넥터 Lambda 함수가 사용하는 프라이빗 서브넷에는 이 NAT 게이트웨이를 통한 인터넷 경로가 있어야 합니다. Neptune 커넥터 Lambda 함수는 NAT 게이트웨이를 사용하여 AWS Glue와 통신합니다. 새 Neptune 클러스터를 설정하고 샘플 데이터 세트와 함께 로드하는 방법에 대한 지침은 GitHub.com의 [Sample Neptune Cluster Setup](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/neptune-cluster-setup)(샘플 Neptune 클러스터 설정)을 참조하세요. ## AWS Glue Data Catalog 설정 기존의 관계형 데이터 스토어와 달리 Neptune 그래프 DB 노드 및 엣지는 세트 스키마를 사용하지 않습니다. 항목마다 필드와 데이터 형식이 다를 수 있습니다. 그러나 Neptune 커넥터는 AWS Glue Data Catalog에서 메타데이터를 검색하기 때문에 필요한 스키마가 포함된 테이블이 있는 AWS Glue 데이터베이스를 생성해야 합니다. AWS Glue 데이터베이스 및 테이블을 생성한 후 커넥터는 Athena에서 쿼리할 수 있는 테이블 목록을 채울 수 있습니다. ### 대소문자를 구분하지 않는 열 일치 활성화 AWS Glue에서 열 이름이 모두 소문자인 경우에도 Neptune 테이블의 열 이름을 올바른 대소문자로 확인하려면 대소문자를 구분하지 않도록 Neptune 커넥터를 구성할 수 있습니다. 이 기능을 활성화하려면 Neptune 커넥터 Lambda 함수의 `enable_caseinsensitivematch` 환경 변수를 `true`로 설정합니다. ### 대소문자를 구분하는 테이블 이름의 경우 AWS Glue glabel 테이블 파라미터 지정 AWS Glue에서는 소문자 테이블 이름만 지원하므로 Neptune에 대해 AWS Glue 테이블을 생성하고 Neptune 테이블 이름이 대소문자를 구분하는 경우 `glabel` AWS Glue 테이블 파라미터를 지정해야 합니다. AWS Glue 테이블 정의에 `glabel` 파라미터를 포함하고 값을 원래 대소문자를 사용하는 테이블 이름으로 설정합니다. 이렇게 하면 AWS Glue에서 Neptune 테이블과 상호 작용할 때 올바른 대소문자가 유지됩니다. 다음 예제에서는 `glabel`의 값을 테이블 이름 `Airport`로 설정합니다. ``` glabel = Airport ``` ![\[Neptune 테이블에 대해 테이블 이름 대소문자를 유지하도록 glabel AWS Glue 테이블 속성 설정\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-neptune-1.png) Neptune과 함께 작동하도록 AWS Glue Data Catalog를 설정하는 방법에 대한 자세한 내용은 GitHub.com의 [Set up AWS Glue Catalog](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/aws-glue-sample-scripts)를 참조하세요. ## 성능 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Neptune 커넥터에서 조건자 푸시다운을 수행합니다. 그러나 조건자에서 프라이머리 키를 사용하면 쿼리가 실패하게 됩니다. `LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자를 제공하지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. Neptune 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. ## 패스스루 쿼리 Neptune 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 이 특성을 사용하여 속성 그래프에서 Gremlin 쿼리를 실행하고 RDF 데이터에 대해 SPARQL 쿼리를 실행할 수 있습니다. Neptune에서 패스스루 쿼리를 생성하려면 다음 구문을 사용하세요. ``` SELECT * FROM TABLE( system.query( DATABASE => 'database_name', COLLECTION => 'collection_name', QUERY => 'query_string' )) ``` 다음 예시 Neptune 패스스루 쿼리는 `ATL` 코드가 있는 공항을 필터링합니다. 이중 작은따옴표는 이스케이프 처리용입니다. ``` SELECT * FROM TABLE( system.query( DATABASE => 'graph-database', COLLECTION => 'airport', QUERY => 'g.V().has(''airport'', ''code'', ''ATL'').valueMap()' )) ``` ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune)를 참조하세요. # Amazon Athena OpenSearch 커넥터 OpenSearch Service Amazon Athena OpenSearch 커넥터를 통해 Amazon Athena는 OpenSearch 인스턴스와 통신할 수 있고, 이로써 SQL을 사용하여 데이터를 쿼리할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. **참고** 알려진 문제로 인해 OpenSearch 커넥터는 VPC에서 사용할 수 없습니다. 계정에서 Lake Formation을 활성화한 경우 AWS Serverless Application Repository에 배포한 Athena 페더레이션형 Lambda 커넥터의 IAM 역할은 Lake Formation에서 AWS Glue Data Catalog에 대한 읽기 액세스 권한을 가지고 있어야 합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 용어 다음 용어는 OpenSearch 커넥터와 관련이 있습니다. + **도메인** - 이 커넥터가 OpenSearch 인스턴스의 엔드포인트와 연결하는 이름입니다. 도메인은 데이터베이스 이름으로도 사용됩니다. Amazon OpenSearch Service 내에 정의된 OpenSearch 인스턴스의 경우 도메인은 자동 검색 가능합니다. 다른 인스턴스의 경우 도메인 이름과 엔드포인트 간의 매핑을 제공해야 합니다. + **인덱스** - OpenSearch 인스턴스에 정의된 데이터베이스 테이블입니다. + **매핑** - 인덱스가 데이터베이스 테이블인 경우 매핑은 해당 스키마(즉, 해당 필드 및 속성의 정의)입니다. 이 커넥터는 OpenSearch 인스턴스와 AWS Glue Data Catalog에서 메타데이터 검색을 모두 지원합니다. 커넥터가 OpenSearch 도메인 및 인덱스 이름과 일치하는 AWS Glue 데이터베이스 및 테이블을 찾으면 커넥터가 스키마 정의에 이들을 사용하려고 시도합니다. OpenSearch 인덱스에 있는 모든 필드의 상위 세트가 되도록 AWS Glue 테이블을 생성하는 것이 좋습니다. + **문서** – 데이터베이스 테이블 내의 레코드입니다. + **데이터 스트림** - 여러 백업 인덱스로 구성된 시간 기반 데이터입니다. 자세한 내용은 OpenSearch 설명서의 [Data streams](https://opensearch.org/docs/latest/dashboards/im-dashboards/datastream/) 및 *Amazon OpenSearch Service 개발자 안내서*의 [데이터 스트림 시작하기](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/data-streams.html#data-streams-example)를 참조하세요. **참고** 데이터 스트림 인덱스는 OpenSearch에 의해 내부적으로 생성 및 관리되므로 커넥터는 사용 가능한 첫 번째 인덱스에서 스키마 매핑을 선택합니다. 이러한 이유로 AWS Glue 테이블을 보충 메타데이터 소스로 설정하는 것이 좋습니다. 자세한 내용은 [AWS Glue에서 데이터베이스 및 테이블 설정](#connectors-opensearch-setting-up-databases-and-tables-in-aws-glue) 섹션을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 OpenSearch 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 OpenSearch 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 OpenSearch 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type OPENSEARCH ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 OpenSearch 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 OpenSearch 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **disable\$1glue** – (선택 사항) true로 설정된 경우 커넥터는 AWS Glue에서 보충 메타데이터 검색을 시도하지 않습니다. + **query\$1timeout\$1cluster** – 병렬 스캔 생성에 사용되는 클러스터 상태 쿼리의 제한 시간(초)입니다. + **query\$1timeout\$1search** – 인덱스에서 문서를 검색하는 데 사용되는 검색 쿼리의 제한 시간(초)입니다. + **auto\$1discover\$1endpoint** – 부울입니다. 기본값은 `true`입니다. Amazon OpenSearch Service를 사용하고 이 파라미터를 true로 설정하면 커넥터가 OpenSearch Service에서 적절한 설명 또는 나열 API 작업을 호출하여 도메인과 엔드포인트를 자동으로 검색할 수 있습니다. 다른 유형의 OpenSearch 인스턴스(예: 자체 호스팅)의 경우 `domain_mapping` 변수에 연결된 도메인 엔드포인트를 지정해야 합니다. `auto_discover_endpoint=true`인 경우 커넥터는 AWS 자격 증명을 사용하여 OpenSearch Service에 인증합니다. 그렇지 않으면 커넥터가 `domain_mapping` 변수를 통해 AWS Secrets Manager에서 사용자 이름 및 암호 자격 증명을 검색합니다. + **domain\$1mapping** – `auto_discover_endpoint`가 false로 설정되고 도메인 이름과 관련 엔드포인트 간의 매핑을 정의하는 경우에만 사용됩니다. `domain_mapping` 변수는 다음 형식으로 여러 OpenSearch 엔드포인트를 수용할 수 있습니다. ``` domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,... ``` OpenSearch 엔드포인트에 대한 인증을 위해 커넥터는 `${SecretName}` 형식을 사용하여 삽입된 대체 문자열을 지원하며, 여기에는 AWS Secrets Manager에서 검색한 사용자 이름과 암호가 포함됩니다. 보안 암호는 다음 JSON 형식으로 저장해야 합니다. ``` { "username": "your_username", "password": "your_password" } ``` 커넥터는 자동으로 이 JSON 구조를 구문 분석하여 자격 증명을 검색합니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. 다음 예제에서는 `opensearch-creds` 보안 암호를 사용합니다. ``` movies=https://${opensearch-creds}:search-movies-ne...qu---us-east-1---es.amazonaws.com ``` 런타임 시 `${opensearch-creds}`는 다음 예제와 같이 사용자 이름과 암호로 렌더링됩니다. ``` movies=https://myusername@mypassword:search-movies-ne...qu---us-east-1---es.amazonaws.com ``` `domain_mapping` 파라미터에서 각 도메인-엔드포인트 페어는 다른 보안 암호를 사용할 수 있습니다. 보안 암호 자체는 *user\$1name*@*password* 형식으로 지정해야 합니다. 암호에 `@` 기호가 포함될 수 있지만 첫 번째 `@`은 *user\$1name*과의 구분자 역할을 합니다. 쉼표(,)와 등호(=)가 이 커넥터에서 도메인-엔드포인트 페어의 구분자로 사용된다는 점도 중요합니다. 따라서 저장된 보안 암호 내의 어디에도 쉼표(,)와 등호(=)를 사용하면 안 됩니다. ## AWS Glue에서 데이터베이스 및 테이블 설정 커넥터는 AWS Glue 또는 OpenSearch를 사용하여 메타데이터 정보를 가져옵니다. AWS Glue 테이블을 보충 메타데이터 정의 소스로 설정할 수 있습니다. 이 기능을 활성화하려면 보충하려는 소스의 도메인 및 인덱스와 일치하는 AWS Glue 데이터베이스 및 테이블을 정의합니다. 커넥터는 지정된 인덱스에 대한 매핑을 검색하여 OpenSearch 인스턴스에 저장된 메타데이터 정의를 활용할 수도 있습니다. ### OpenSearch에서 배열에 대한 메타데이터 정의 OpenSearch에는 전용 배열 데이터 형식이 없습니다. 데이터 형식이 같으면 모든 필드에 0개 이상의 값이 포함될 수 있습니다. OpenSearch를 메타데이터 정의 소스로 사용하려면 목록 또는 배열로 간주될 필드에 대해 Athena와 함께 사용되는 모든 인덱스에 대해 `_meta` 속성을 정의해야 합니다. 이 단계를 완료하지 못하면 쿼리는 목록 필드의 첫 번째 요소만 반환합니다. `_meta` 속성을 지정할 때 필드 이름은 중첩 JSON 구조에 대해 정규화되어야 합니다(예: `address.street` 여기서 `street`는 `address` 구조 내부의 중첩 필드임). 다음 예제는 `movies` 테이블에 `actor` 및 `genre` 목록을 정의합니다. ``` PUT movies/_mapping { "_meta": { "actor": "list", "genre": "list" } } ``` ### 데이터 타입 OpenSearch 커넥터는 AWS Glue 또는 OpenSearch 인스턴스에서 메타데이터 정의를 추출할 수 있습니다. 커넥터는 다음 표의 매핑을 사용하여 정의를 Apache Arrow 데이터 형식으로 변환합니다. 여기에는 다음 섹션에 언급된 사항이 포함됩니다. **** | OpenSearch | Apache Arrow | AWS Glue | | --- | --- | --- | | text, keyword, binary | VARCHAR | 문자열 | | bigint | BIGINT | bigint | | scaled\$1float | BIGINT | SCALED\$1FLOAT(...) | | 정수 | INT | int | | bigint | SMALLINT | smallint | | 바이트 | TINYINT | tinyint | | double | FLOAT8 | double | | float, half\$1float | FLOAT4 | 실수 | | 부울 | BIT | 부울 | | date, date\$1nanos | DATEMILLI | timestamp | | JSON 구조 | STRUCT | STRUCT | | \$1meta(자세한 내용을 알아보려면 [OpenSearch에서 배열에 대한 메타데이터 정의](#connectors-opensearch-defining-metadata-for-arrays-in-opensearch) 섹션 참조) | LIST | ARRAY | #### 데이터 형식에 대한 참고 사항 + 현재 커넥터는 앞의 표에 나열된 OpenSearch 및 AWS Glue 데이터 형식만 지원합니다. + `scaled_float`는 고정 이중 스케일링 팩터로 조정된 부동 소수점 숫자이며 Apache Arrow에서 `BIGINT`로 표시됩니다. 예를 들어, 스케일링 팩터가 100인 0.756은 76으로 반올림됩니다. + AWS Glue에서 `scaled_float`를 정의하려면 `array` 열 유형을 선택하고 SCALED\$1FLOAT(*scaling\$1factor*) 형식을 사용하여 필드를 선언해야 합니다. 다음 예제는 유효합니다. ``` SCALED_FLOAT(10.51) SCALED_FLOAT(100) SCALED_FLOAT(100.0) ``` 다음 예제는 유효하지 않습니다. ``` SCALED_FLOAT(10.) SCALED_FLOAT(.5) ``` + `date_nanos`에서 `DATEMILLI`로 변환할 때 나노초는 가장 가까운 밀리초로 반올림됩니다. `date` 및 `date_nanos`에 대한 유효한 값에는 다음 형식이 포함되지만 이에 국한되지 않습니다. ``` "2020-05-18T10:15:30.123456789" "2020-05-15T06:50:01.123Z" "2020-05-15T06:49:30.123-05:00" 1589525370001 (epoch milliseconds) ``` + OpenSearch `binary`는 `Base64`를 사용하여 인코딩된 바이너리 값의 문자열 표현이며 `VARCHAR`로 변환됩니다. ## SQL 쿼리 실행 다음은 이 커넥터에서 사용할 수 있는 DDL 쿼리의 예제입니다. 예제에서 *function\$1name*은 Lambda 함수의 이름에 해당하고, *domain*은 쿼리하려는 도메인의 이름이고, *index*는 인덱스의 이름입니다. ``` SHOW DATABASES in `lambda:function_name` ``` ``` SHOW TABLES in `lambda:function_name`.domain ``` ``` DESCRIBE `lambda:function_name`.domain.index ``` ## 성능 Athena OpenSearch 커넥터는 샤드 기반 병렬 스캔을 지원합니다. 커넥터는 OpenSearch 인스턴스에서 검색된 클러스터 상태 정보를 사용하여 문서 검색 쿼리에 대한 여러 요청을 생성합니다. 요청은 각 샤드에 대해 분할되고 동시에 실행됩니다. 또한 커넥터는 문서 검색 쿼리의 일부로 조건자를 푸시다운합니다. 다음 예제 쿼리 및 조건자는 커넥터가 조건자 푸시다운을 사용하는 방법을 보여줍니다. **Query** ``` SELECT * FROM "lambda:elasticsearch".movies.movies WHERE year >= 1955 AND year <= 1962 OR year = 1996 ``` **조건자** ``` (_exists_:year) AND year:([1955 TO 1962] OR 1996) ``` ## 패스스루 쿼리 OpenSearch 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원하고 Query DSL 언어를 사용합니다. Query DSL을 사용한 쿼리에 대한 자세한 내용은 Elasticsearch 설명서의 [Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) 또는 OpenSearch 설명서의 [Query DSL](https://opensearch.org/docs/latest/query-dsl/)을 참조하세요. OpenSearch 커넥터에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( schema => 'schema_name', index => 'index_name', query => "{query_string}" )) ``` 다음 OpenSearch 예제 패스스루 쿼리는 `default` 스키마의 `employee` 인덱스에서 활성 고용 상태인 직원을 필터링합니다. ``` SELECT * FROM TABLE( system.query( schema => 'default', index => 'employee', query => "{ ''bool'':{''filter'':{''term'':{''status'': ''active''}}}}" )) ``` ## 추가 리소스 + Amazon Athena OpenSearch 커넥터를 사용하여 단일 쿼리로 Amazon OpenSearch Service와 Amazon S3에서 데이터를 쿼리하는 방법에 대한 문서는 *AWS 빅 데이터 블로그*의 [Query data in Amazon OpenSearch Service using SQL from Amazon Athena](https://aws.amazon.com/blogs/big-data/query-data-in-amazon-opensearch-service-using-sql-from-amazon-athena/)를 참조하세요. + 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-elasticsearch)를 참조하세요. # Amazon Athena Oracle 커넥터 Oracle용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 온프레미스나 Amazon EC2 또는 Amazon RDS에서 실행 중인 Oracle에 저장된 데이터에 대해 SQL 쿼리를 실행할 수 있습니다. 커넥터를 사용하여 [Oracle Exadata](https://www.oracle.com/engineered-systems/exadata/)에 대해 데이터를 쿼리할 수도 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + Oracle Database는 버전 12.1.0.2만 지원됩니다. + Oracle 커넥터가 Glue 연결을 사용하지 않는 경우 데이터베이스, 테이블 및 열 이름은 커넥터에 의해 대문자로 변환됩니다. Oracle 커넥터가 Glue 연결을 사용하는 경우 데이터베이스, 테이블 및 열 이름은 기본적으로 커넥터의 대문자로 설정되지 않습니다. 이 대소문자 변환 동작을 변경하려면 Lambda 환경 변수 `casing_mode`를 필요에 따라 `upper` 또는 `lower`로 변경합니다. Glue 연결을 사용하는 Oracle 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. + 정밀도와 소수점 자릿수가 정의되지 않은 Oracle `NUMBER`를 사용하면 Athena는 이를 `BIGINT`로 취급합니다. Athena에서 필요한 소수점 자릿수를 가져오려면 Lambda 환경 변수에 `default_scale=`를 지정합니다. ## 용어 다음 용어는 Oracle 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Oracle 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Oracle 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Oracle 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type ORACLE ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **is\$1fips\$1enabled** – (선택 사항) FIPS 모드가 활성화된 경우 true로 설정합니다. 기본값은 false입니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. 연결된 Glue 연결이 없는 커넥터의 기본값입니다. + **case\$1insensitive\$1search** - Oracle에서 스키마 및 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다. 쿼리에 커넥터의 기본 대소문자와 일치하지 않는 스키마 또는 테이블 이름이 포함된 경우 이 값을 사용합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Oracle 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Oracle 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. **Lambda 환경 속성** + **default** - Oracle 데이터베이스 인스턴스에 연결하는 데 사용할 JDBC 연결 문자열입니다. 예: `oracle://${jdbc_connection_string}` + **catalog\$1connection\$1string** – 멀티플렉싱 핸들러에서 사용합니다(Glue 연결을 사용할 때는 지원되지 않음). 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어 Athena에 등록된 카탈로그가 myoraclecatalog인 경우 환경 변수 이름은 myoraclecatalog\$1connection\$1string입니다. + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **is\$1fips\$1enabled** – (선택 사항) FIPS 모드가 활성화된 경우 true로 설정합니다. 기본값은 false입니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. 연결된 Glue 연결이 없는 커넥터의 기본값입니다. + **case\$1insensitive\$1search** - Oracle에서 스키마 및 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다. 쿼리에 커넥터의 기본 대소문자와 일치하지 않는 스키마 또는 테이블 이름이 포함된 경우 이 값을 사용합니다. #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` oracle://${jdbc_connection_string} ``` **참고** 암호에 특수 문자(예: `some.password`)가 포함된 경우 연결 문자열에 암호를 전달할 때 암호를 큰따옴표로 묶습니다(예: `"some.password"`). 이렇게 하지 않으면 Invalid Oracle URL specified 오류가 발생할 수 있습니다. #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Oracle 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | OracleCompositeHandler | | 메타데이터 핸들러 | OracleMetadataHandler | | 레코드 핸들러 | OracleRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | | IsFIPSEnabled | 선택 사항. FIPS 모드가 활성화될 때 true로 설정합니다. 기본값은 false입니다. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 커넥터는 Amazon RDS 인스턴스에 대한 SSL 기반 연결을 지원합니다. 지원은 전송 계층 보안(TLS) 프로토콜 및 클라이언트에 의한 서버 인증으로 제한됩니다. Amazon RDS에서는 상호 인증이 지원되지 않습니다. 아래 표의 두 번째 행은 SSL 사용 구문을 보여줍니다. 다음은 Lambda 함수에서 지원하는 단일 Oracle 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@//hostname:port/servicename | | | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS) (HOST=)(PORT=))(CONNECT\$1DATA=(SID=))(SECURITY=(SSL\$1SERVER\$1CERT\$1DN=))) | #### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **참고** 암호에 특수 문자(예: `some.password`)가 포함된 경우 Secrets Manager에 암호를 저장할 때 암호를 큰따옴표로 묶습니다(예: `"some.password"`). 이렇게 하지 않으면 Invalid Oracle URL specified 오류가 발생할 수 있습니다. **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/RDS/Oracle}`입니다. ``` oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` oracle://jdbc:oracle:thin:username/password@//hostname:port/servicename ``` 현재 Oracle 커넥터는 `UID` 및 `PWD` JDBC 속성을 인식합니다. #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | OracleMuxCompositeHandler | | 메타데이터 핸들러 | OracleMuxMetadataHandler | | 레코드 핸들러 | OracleMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 myoraclecatalog인 경우 환경 변수 이름은 myoraclecatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `oracle1`(기본값)과 `oracle2`라는 2개의 데이터베이스 인스턴스를 지원하는 Oracle MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename | | oracle\$1catalog1\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename | | oracle\$1catalog2\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle2\$1@//oracle2.hostname:port/servicename | ## 데이터 형식 지원 다음 표에 JDBC, Oracle 및 Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | Oracle | 화살표 | | --- | --- | --- | | 부울 | 부울 | Bit | | Integer | 해당 사항 없음 | Tiny | | Short | smallint | Smallint | | Integer | 정수 | 정수 | | Long | bigint | Bigint | | 실수 | float4 | Float4 | | 배정밀도 실수 | float8 | Float8 | | 날짜 | 날짜 | DateDay | | 타임스탬프 | timestamp | DateMilli | | 문자열 | 텍스트 | Varchar | | 바이트 | bytes | Varbinary | | BigDecimal | numeric(p,s) | 10진수 | | ARRAY | 해당 사항 없음(참고 사항 참조) | List | ## 파티션 및 분할 파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다. ## 성능 Oracle은 기본 파티션을 지원합니다. Athena Oracle 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. Oracle 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. 하지만 쿼리 런타임이 길어지는 경향이 있습니다. 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Oracle 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Oracle 커넥터는 이러한 표현식을 결합하고 Oracle로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Oracle 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 패스스루 쿼리 Oracle 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Oracle에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Oracle의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리가 `customer` 테이블의 모든 열을 선택합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Oracle 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-oracle)를 참조하세요. # Amazon Athena PostgreSQL 커넥터 Amazon Athena PostgreSQL 커넥터를 사용하면 Athena에서 PostgreSQL 데이터베이스에 액세스할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + PostgreSQL과 마찬가지로 Athena는 길이 및 비교 목적으로 PostgreSQL `CHAR` 형식의 후행 공백을 의미상 중요하지 않은 것으로 취급합니다. 이는 `CHAR` 형식에만 적용되며 `VARCHAR` 형식에는 적용되지 않습니다. Athena는 `CHAR` 형식의 후행 공백을 무시하지만 `VARCHAR` 형식의 후행 공백은 유의미한 것으로 취급합니다. + 대/소문자를 구분하지 않는 [citext](https://www.postgresql.org/docs/current/citext.html) 문자열 데이터 유형을 사용하는 경우 PostgreSQL은 Athena와 다른, 대소문자를 구분하지 않는 데이터 비교를 사용합니다. 이러한 차이로 인해 SQL `JOIN` 작업 중에 데이터 불일치가 발생합니다. 이러한 문제를 해결하려면 PostgreSQL 커넥터 패스스루 쿼리 기능을 사용합니다. 자세한 내용은 이 문서의 후반부에 있는 [패스스루 쿼리](#connectors-postgres-passthrough-queries)를 참조하세요. ## 용어 다음 용어는 PostgreSQL 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 PostgreSQL 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 PostgreSQL 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 PostgreSQL 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type POSTGRESQL ``` **Lambda 환경 속성** **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 PostgreSQL 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 PostgreSQL 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` postgres://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | PostGreSqlMuxCompositeHandler | | 메타데이터 핸들러 | PostGreSqlMuxMetadataHandler | | 레코드 핸들러 | PostGreSqlMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mypostgrescatalog인 경우 환경 변수 이름은 mypostgrescatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `postgres1`(기본값)과 `postgres2`라는 2개의 데이터베이스 인스턴스를 지원하는 PostGreSql MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 | | postgres\$1catalog1\$1connection\$1string | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 | | postgres\$1catalog2\$1connection\$1string | postgres://jdbc:postgresql://postgres2.host:5432/default?user=sample&password=sample | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/RDS/PostGres1}`입니다. ``` postgres://jdbc:postgresql://postgres1.host:5432/default?...&${Test/RDS/PostGres1}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` postgres://jdbc:postgresql://postgres1.host:5432/default?...&user=sample2&password=sample2&... ``` 현재 PostgreSQL 커넥터는 `user` 및 `password` JDBC 속성을 인식합니다. ##### SSL 활성화 PostgreSQL 연결에서 SSL을 지원하려면 연결 문자열에 다음을 추가합니다. ``` &sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory ``` **예제** 다음 연결 문자열 예제에서는 SSL을 사용하지 않습니다. ``` postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword ``` SSL을 활성화하려면 다음과 같이 문자열을 수정합니다. ``` postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory ``` #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 PostgreSQL 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | PostGreSqlCompositeHandler | | 메타데이터 핸들러 | PostGreSqlMetadataHandler | | 레코드 핸들러 | PostGreSqlRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 PostgreSQL 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | postgres://jdbc:postgresql://postgres1.host:5432/default?secret=\$1\$1Test/RDS/PostgreSQL1\$1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC, PostGreSQL 및 Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | PostGreSQL | 화살표 | | --- | --- | --- | | 부울 | 부울 | Bit | | Integer | 해당 사항 없음 | Tiny | | Short | smallint | Smallint | | Integer | 정수 | 정수 | | Long | bigint | Bigint | | 실수 | float4 | Float4 | | 배정밀도 실수 | float8 | Float8 | | 날짜 | 날짜 | DateDay | | 타임스탬프 | timestamp | DateMilli | | 문자열 | 텍스트 | Varchar | | 바이트 | bytes | Varbinary | | BigDecimal | numeric(p,s) | 10진수 | | ARRAY | 해당 사항 없음(참고 사항 참조) | List | **참고** `ARRAY` 형식은 다차원 배열(`[][]` 또는 중첩 배열)은 지원되지 않는다는 제약 조건이 있는 PostgreSQL 커넥터에 대해 지원됩니다. 지원되지 않는 `ARRAY` 데이터 형식이 있는 열은 문자열 요소의 배열(`array`)로 변환됩니다. ## 파티션 및 분할 파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다. ## 성능 PostgreSQL은 기본 파티션을 지원합니다. Athena PostgreSQL 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다. Athena PostgreSQL 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. 그러나 열 하위 세트를 선택할 때 쿼리 실행 런타임이 길어지는 경우가 있습니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena PostgreSQL 커넥터는 이러한 표현식을 결합하고 PostgreSQL로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena PostgreSQL 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 패스스루 쿼리 PostgreSQL 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. PostgreSQL에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 PostgreSQL의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 PostgreSQL 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-postgresql/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-postgresql)를 참조하세요. # Amazon Athena Redis OSS 커넥터 Amazon Redis OSS 커넥터를 통해 Amazon Athena는 Redis OSS 인스턴스와 통신할 수 있고, 이로써 SQL을 사용하여 Redis OSS 데이터를 쿼리할 수 있습니다. AWS Glue Data Catalog를 사용하여 Redis OSS 키-값 페어를 가상 테이블에 매핑할 수 있습니다. 기존의 관계형 데이터 스토어와 달리 Redis OSS에는 테이블이나 열의 개념이 없습니다. 대신 Redis OSS는 키가 기본적으로 `string`이고 값이 `string`, `z-set` 또는 `hmap`인 키-값 액세스 패턴을 제공합니다. AWS Glue Data Catalog를 사용하여 스키마를 생성하고 가상 테이블을 구성할 수 있습니다. Athena Redis OSS 커넥터는 특수 테이블 속성을 통해 Redis OSS 키와 값을 테이블에 매핑하는 방법을 알 수 있습니다. 자세한 내용은 이 문서의 후반부에서 [AWS Glue에서 데이터베이스 및 테이블 설정](#connectors-redis-setting-up-databases-and-tables-in-glue) 단원을 참조하세요. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. 계정에서 Lake Formation을 활성화한 경우 AWS Serverless Application Repository에 배포한 Athena 페더레이션형 Lambda 커넥터의 IAM 역할은 Lake Formation에서 AWS Glue Data Catalog에 대한 읽기 액세스 권한을 가지고 있어야 합니다. Amazon Athena Redis OSS 커넥터는 Amazon MemoryDB 및 Amazon ElastiCache(Redis OSS)를 지원합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. + 이 커넥터를 사용하기 전에 VPC와 보안 그룹을 설정합니다. 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) 섹션을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 Redis 커넥터를 구성합니다. + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **glue\$1catalog** – (선택 사항) 이 옵션을 사용하여 [크로스 계정 AWS Glue 카탈로그](data-sources-glue-cross-account.md)를 지정합니다. 기본적으로 커넥터는 자체 AWS Glue 계정에서 메타데이터를 가져오려고 시도합니다. ## AWS Glue에서 데이터베이스 및 테이블 설정 Redis OSS에서 사용할 AWS Glue 테이블을 활성화하려면 테이블에서 `redis-endpoint`, `redis-value-type` 및 `redis-keys-zset` 또는 `redis-key-prefix`와 같은 테이블 속성을 설정합니다. 또한 Redis OSS 테이블이 포함된 모든 AWS Glue 데이터베이스에는 데이터베이스의 URI 속성에 `redis-db-flag`가 있어야 합니다. `redis-db-flag` URI 속성을 설정하려면 AWS Glue 콘솔을 사용하여 데이터베이스를 편집합니다. 다음 목록에서는 테이블 속성을 설명합니다. + **redis-endpoint** – (필수) 이 테이블에 대한 데이터가 포함된 Redis OSS 서버의 *hostname*`:`*port*`:`*password*(예: `athena-federation-demo.cache.amazonaws.com:6379`). 또는 \$1\$1*Secret\$1Name*\$1을 테이블 속성 값으로 사용하여 AWS Secrets Manager에 엔드포인트 또는 엔드포인트의 일부를 저장할 수 있습니다. **참고** AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Lambda 함수에 연결된 VPC에 Secrets Manager에 연결할 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) 가 있어야 합니다. + **redis-keys-zset** – (`redis-key-prefix`가 사용되지 않는 경우 필수) 값이 [zset](https://redis.com/ebook/part-2-core-concepts/chapter-3-commands-in-redis/3-5-sorted-sets/)인 쉼표로 구분된 키 목록입니다(예: `active-orders,pending-orders`). zset의 각 값은 테이블의 일부인 키로 처리됩니다. `redis-keys-zset` 속성 또는 `redis-key-prefix` 속성을 설정해야 합니다. + **redis-key-prefix** – (`redis-keys-zset`가 사용되지 않는 경우 필수) 테이블에서 값을 스캔하기 위한 쉼표로 구분된 키 접두사 목록입니다(예: `accounts-*,acct-`). `redis-key-prefix` 속성 또는 `redis-keys-zset` 속성을 설정해야 합니다. + **redis-value-type** – (필수) `redis-key-prefix` 또는 `redis-keys-zset`에 의해 정의된 키의 값이 테이블에 매핑되는 방법을 정의합니다. 리터럴은 단일 열에 매핑됩니다. zset도 단일 열에 매핑되지만 각 키는 많은 행을 저장할 수 있습니다. 해시를 사용하면 각 키가 여러 열(예: 해시, 리터럴 또는 zset)이 있는 행이 될 수 있습니다. + **redis-ssl-flag** – (선택 사항) `True`이면 SSL/TLS를 사용하는 Redis 연결을 생성합니다. 기본값은 `False`입니다. + **redis-cluster-flag** – (선택 사항) `True`이면 클러스터링된 Redis 인스턴스에 대한 지원을 활성화합니다. 기본값은 `False`입니다. + **redis-db-number** – (선택 사항) 클러스터링되지 않은 독립 실행형 인스턴스에만 적용됩니다. 기본값이 아닌 Redis 데이터베이스에서 읽으려면 이 번호(예: 1, 2 또는 3)를 설정합니다. 기본값은 Redis 논리적 데이터베이스 0입니다. 이 번호는 Athena 또는 AWS Glue의 데이터베이스가 아니라 Redis 논리 데이터베이스를 나타냅니다. 자세한 내용을 알아보려면 Redis 설명서의 [SELECT 인덱스](https://redis.io/commands/select)를 참조하세요. ## 데이터 타입 Redis OSS 커넥터는 다음 데이터 형식을 지원합니다. Redis OSS 스트림은 지원되지 않습니다. + [문자열](https://redis.com/ebook/part-1-getting-started/chapter-1-getting-to-know-redis/1-2-what-redis-data-structures-look-like/1-2-1-strings-in-redis/) + [해시](https://redis.com/ebook/part-1-getting-started/chapter-1-getting-to-know-redis/1-2-what-redis-data-structures-look-like/1-2-4-hashes-in-redis/) + 정렬된 세트([ZSet](https://redis.com/ebook/part-2-core-concepts/chapter-3-commands-in-redis/3-5-sorted-sets/)) 모든 Redis OSS 값은 `string` 데이터 형식으로 검색됩니다. 그런 다음 AWS Glue Data Catalog에서 테이블이 정의된 방식에 따라 다음 Apache Arrow 데이터 형식 중 하나로 변환됩니다. **** | AWS Glue 데이터 유형 | Apache Arrow 데이터 형식 | | --- | --- | | int | INT | | 문자열 | VARCHAR | | bigint | BIGINT | | double | FLOAT8 | | 실수 | FLOAT4 | | smallint | SMALLINT | | tinyint | TINYINT | | 부울 | BIT | | 이진수 | VARBINARY | ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-redis.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-redis/athena-redis.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. + **AWS Glue Data Catalog** - 스키마 정보를 가져오기 위해 Redis 커넥터에 AWS Glue Data Catalog에 대한 읽기 전용 액세스 권한이 필요합니다. + **CloudWatch Logs** - 로그를 저장하기 위해 커넥터 CloudWatch Logs에 대한 액세스 권한이 필요합니다. + **AWS Secrets Manager 읽기 액세스** - Secrets Manager에 Redis 엔드포인트 세부 정보를 저장하기로 선택하는 경우 커넥터에 해당 보안 암호에 대한 액세스 권한을 부여해야 합니다. + **VPC 액세스** - VPC에 연결하고 Redis 인스턴스와 통신할 수 있도록 VPC에 인터페이스를 연결하고 분리하는 기능이 커넥터에 필요합니다. ## 성능 Athena Redis OSS 커넥터는 사용자가 정의한 테이블 유형(예: zset 키 또는 접두사 키)에 따라 Redis OSS 인스턴스에 대한 쿼리 병렬화를 시도합니다. 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Redis 커넥터에서 조건자 푸시다운을 수행합니다. 그러나 프라이머리 키에 대한 조건자를 포함하는 쿼리는 시간 초과로 실패합니다. `LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자를 제공하지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. Redis 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. ## 패스스루 쿼리 Redis 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 이 기능을 사용하여 Redis 데이터베이스에서 Lua 스크립트를 사용하는 쿼리를 실행할 수 있습니다. Redis에서 패스스루 쿼리를 생성하려면 다음 구문을 사용하세요. ``` SELECT * FROM TABLE( system.script( script => 'return redis.[call|pcall](query_script)', keys => '[key_pattern]', argv => '[script_arguments]' )) ``` 다음 예제에서는 Lua 스크립트를 실행하여 `l:a` 키에서 값을 가져옵니다. ``` SELECT * FROM TABLE( system.script( script => 'return redis.call("GET", KEYS[1])', keys => '[l:a]', argv => '[]' )) ``` ## 라이선스 정보 Amazon Athena Redis 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redis)를 참조하세요. # Amazon Athena Redshift 커넥터 Amazon Athena Redshift 커넥터를 사용하면 Amazon Athena에서 Amazon Redshift 데이터베이스 및 Redshift Serverless 뷰를 포함하는 Amazon Redshift Serverless 데이터베이스에 액세스할 수 있습니다. 이 페이지에 설명된 JDBC 연결 문자열 구성 설정을 사용하여 두 서비스 중 하나에 연결할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + Redshift에서 외부 파티션을 지원하지 않기 때문에 쿼리에서 지정된 모든 데이터가 매번 검색됩니다. + Redshift와 마찬가지로 Athena는 길이 및 비교 목적으로 Redshift `CHAR` 형식의 후행 공백을 의미상 중요하지 않은 것으로 취급합니다. 이는 `CHAR` 형식에만 적용되며 `VARCHAR` 형식에는 적용되지 않습니다. Athena는 `CHAR` 형식의 후행 공백을 무시하지만 `VARCHAR` 형식의 후행 공백은 유의미한 것으로 취급합니다. ## 용어 다음 용어는 Redshift 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Redshift 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Redshift 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Amazon Redshift 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type REDSHIFT ``` **Lambda 환경 속성** **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Redshift 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Redshift 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. **Lambda 환경 속성** + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **disable\$1glue** – (선택 사항) true로 설정된 경우 커넥터는 AWS Glue에서 보충 메타데이터 검색을 시도하지 않습니다. + **glue\$1catalog** – (선택 사항) 이 옵션을 사용하여 [크로스 계정 AWS Glue 카탈로그](data-sources-glue-cross-account.md)를 지정합니다. 기본적으로 커넥터는 자체 AWS Glue 계정에서 메타데이터를 가져오려고 시도합니다. #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` redshift://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | RedshiftMuxCompositeHandler | | 메타데이터 핸들러 | RedshiftMuxMetadataHandler | | 레코드 핸들러 | RedshiftMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 myredshiftcatalog인 경우 환경 변수 이름은 myredshiftcatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `redshift1`(기본값)과 `redshift2`라는 2개의 데이터베이스 인스턴스를 지원하는 Redshift MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | redshift://jdbc:redshift://redshift1.host:5439/dev?user=sample2&password=sample2 | | redshift\$1catalog1\$1connection\$1string | redshift://jdbc:redshift://redshift1.host:3306/default?\$1\$1Test/RDS/Redshift1\$1 | | redshift\$1catalog2\$1connection\$1string | redshift://jdbc:redshift://redshift2.host:3333/default?user=sample2&password=sample2 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 \$1\$1Test/RDS/ `Redshift1`\$1입니다. ``` redshift://jdbc:redshift://redshift1.host:3306/default?...&${Test/RDS/Redshift1}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` redshift://jdbc:redshift://redshift1.host:3306/default?...&user=sample2&password=sample2&... ``` 현재 Redshift 커넥터는 `user` 및 `password` JDBC 속성을 인식합니다. ## 데이터 형식 지원 다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | 화살표 | | --- | --- | | 부울 | Bit | | Integer | Tiny | | Short | Smallint | | Integer | 정수 | | Long | Bigint | | 실수 | Float4 | | 배정밀도 실수 | Float8 | | 날짜 | DateDay | | 타임스탬프 | DateMilli | | 문자열 | Varchar | | 바이트 | Varbinary | | BigDecimal | 10진수 | | ARRAY | List | ## 파티션 및 분할 Redshift는 외부 파티션을 지원하지 않습니다. 성능 관련 문제에 대한 자세한 내용을 알아보려면 [성능](#connectors-redshift-performance) 섹션을 참조하세요. ## 성능 Athena Redshift 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, `ORDER BY` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. 그러나 열 하위 세트를 선택할 때 쿼리 실행 런타임이 길어지는 경우가 있습니다. Amazon Redshift는 여러 쿼리를 동시에 실행할 때 특히 쿼리 실행 속도 저하에 취약합니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### 상위 N개 쿼리 상위 `N`개 쿼리는 결과 세트의 순서와 반환되는 행 수에 대한 한도를 지정합니다. 이 유형의 쿼리를 사용하여 데이터 세트에 대해 상위 `N`개의 최댓값 또는 상위 `N`개의 최솟값을 결정할 수 있습니다. 상위 `N`개의 푸시다운을 통해 커넥터는 Athena에 `N`개의 정렬된 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Redshift 커넥터는 이러한 표현식을 결합하고 Redshift로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Redshift 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') ORDER BY col_a DESC LIMIT 10; ``` Amazon Redshift를 비롯한 페더레이션된 쿼리의 성능을 개선하기 위해 조건자 푸시다운을 사용하는 방법에 대한 문서는 *AWS 빅 데이터 블로그*의 [Improve federated queries with predicate pushdown in Amazon Athena](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)를 참조하세요. ## 패스스루 쿼리 Redshift 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Redshift에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Redshift의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Redshift 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-redshift/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redshift)를 참조하세요. # Amazon Athena SAP HANA 커넥터 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + SAP HANA에서 객체 이름은 SAP HANA 데이터베이스에 저장될 때 대문자로 변환됩니다. 그러나 따옴표 안의 이름은 대/소문자를 구분하기 때문에 두 테이블이 이름은 같지만 대/소문자가 다를 수 있습니다(예: `EMPLOYEE` 및 `employee`). Athena 연합 쿼리에서 스키마 테이블 이름은 소문자로 Lambda 함수에 제공됩니다. 이 문제를 해결하려면 `@schemaCase` 쿼리 힌트를 제공하여 대/소문자를 구분하는 이름을 가진 테이블에서 데이터를 검색합니다. 다음은 쿼리 힌트가 포함된 두 가지 샘플 쿼리입니다. ``` SELECT * FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=upper" ``` ``` SELECT * FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=lower" ``` ## 용어 다음 용어는 SAP HANA 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 SAP HANA 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 SAP HANA 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 SAP HANA 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type SAPHANA ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 SAP HANA 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 SAP HANA 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` saphana://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | SaphanaMuxCompositeHandler | | 메타데이터 핸들러 | SaphanaMuxMetadataHandler | | 레코드 핸들러 | SaphanaMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mysaphanacatalog인 경우 환경 변수 이름은 mysaphanacatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `saphana1`(기본값)과 `saphana2`라는 2개의 데이터베이스 인스턴스를 지원하는 Saphana MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 | | saphana\$1catalog1\$1connection\$1string | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 | | saphana\$1catalog2\$1connection\$1string | saphana://jdbc:sap://saphana2.host:port/?user=sample2&password=sample2 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/RDS/Saphana1}`입니다. ``` saphana://jdbc:sap://saphana1.host:port/?${Test/RDS/Saphana1}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` saphana://jdbc:sap://saphana1.host:port/?user=sample2&password=sample2&... ``` 현재 SAP HANA 커넥터는 `user` 및 `password` JDBC 속성을 인식합니다. #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 SAP HANA 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | SaphanaCompositeHandler | | 메타데이터 핸들러 | SaphanaMetadataHandler | | 레코드 핸들러 | SaphanaRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 SAP HANA 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | saphana://jdbc:sap://saphana1.host:port/?secret=Test/RDS/Saphana1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | 화살표 | | --- | --- | | 부울 | Bit | | Integer | Tiny | | Short | Smallint | | Integer | 정수 | | Long | Bigint | | 실수 | Float4 | | 배정밀도 실수 | Float8 | | 날짜 | DateDay | | 타임스탬프 | DateMilli | | 문자열 | Varchar | | 바이트 | Varbinary | | BigDecimal | 10진수 | | ARRAY | List | ## 데이터 형식 변환 JDBC에서 Arrow로의 변환 외에도 커넥터는 SAP HANA 소스와 Athena 데이터 형식이 호환되도록 다른 특정 변환을 수행합니다. 이러한 변환은 쿼리가 성공적으로 실행되도록 하는 데 도움이 됩니다. 다음 표에 이러한 변환이 나와 있습니다. **** | 소스 데이터 형식(SAP HANA) | 변환된 데이터 형식(Athena) | | --- | --- | | DECIMAL | BIGINT | | INTEGER | INT | | DATE | DATEDAY | | TIMESTAMP | DATEMILLI | 지원되지 않는 다른 모든 데이터 형식은 `VARCHAR`로 변환됩니다. ## 파티션 및 분할 파티션은 `Integer` 형식의 단일 파티션 열로 표시됩니다. 열에는 SAP HANA 테이블에 정의된 파티션의 이름이 들어 있습니다. 파티션 이름이 없는 테이블의 경우 단일 파티션에 해당하는 \$1가 반환됩니다. 파티션은 분할과 동일합니다. **** | 이름 | Type | 설명 | | --- | --- | --- | | PART\$1ID | Integer | SAP HANA의 명명된 파티션. | ## 성능 SAP HANA는 기본 파티션을 지원합니다. Athena SAP HANA 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. 이 커넥터는 동시성으로 인해 상당한 제한을 나타나며 경우에 따라 쿼리 오류가 발생할 수 있습니다. Athena SAP HANA 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena SAP HANA 커넥터는 이러한 표현식을 결합하고 SAP HANA로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena SAP HANA 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 패스스루 쿼리 SAP HANA 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. SAP HANA에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 SAP HANA의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 SAP HANA 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-saphana)를 참조하세요. # Amazon Athena Snowflake 커넥터 [Snowflake](https://www.snowflake.com/)용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 JDBC를 사용하여 Snowflake SQL 데이터베이스 또는 RDS 인스턴스에 저장된 데이터에 대해 SQL 쿼리를 실행할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 Athena 콘솔 또는 `CreateDataCatalog` API 작업을 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 레거시 연결만 멀티플렉서 설정을 지원합니다. + 현재 단일 분할이 포함된 Snowflake 뷰가 지원됩니다. + Snowflake에서 객체 이름은 대소문자를 구분합니다. Athena는 DDL 및 DML 쿼리에서 대소문자 혼용을 허용하지만 쿼리를 실행할 때 객체 이름은 기본적으로 [소문자](https://docs.aws.amazon.com/athena/latest/ug/tables-databases-columns-names.html#table-names-and-table-column-names-in-ate-must-be-lowercase)입니다. Snowflake 커넥터는 Glue Catalog/Lake Formation이 사용되는 경우 소문자만 지원합니다. Athena 카탈로그를 사용하면 `casing_mode` Lambda 환경 변수([파라미터](#connectors-snowflake-parameters) 섹션에 가능한 값이 나열됨, 예: `key=casing_mode, value = CASE_INSENSITIVE_SEARCH`)를 사용하여 대소문자 구분 동작을 제어할 수 있습니다. ## 용어 다음 용어는 Snowflake 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Snowflake 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Snowflake 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Snowflake 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type SNOWFLAKE ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **NONE** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다(Snowflake에서와 같이 쿼리 실행). **casing\$1mode**가 지정되지 않은 경우 기본값입니다. + **UPPER** - Snowflake에서 실행하기 전에 쿼리에 지정된 스키마와 테이블 이름을 모두 대문자로 표시합니다. + **LOWER** - Snowflake에서 실행하기 전에 쿼리에 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. + **CASE\$1INSENSITIVE\$1SEARCH** - Snowflake에서 스키마 및 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다. 예를 들어 `SELECT * FROM EMPLOYEE`와 같은 쿼리가 있고 Snowflake에 `Employee`라는 테이블이 포함된 경우 이 모드를 사용할 수 있습니다. 그러나 Snowflake에 `EMPLOYEE`라는 테이블과 `Employee`라는 다른 테이블이 있는 등 이름 충돌이 있는 경우 쿼리에 실패합니다. **참고** Glue 연결을 사용하여 생성된 Snowflake 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Snowflake 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. **자격 증명 저장** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. 자세한 내용은 [Snowflake로 인증](connectors-snowflake-authentication.md) 섹션을 참조하세요. ### 레거시 연결 **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. **Lambda 환경 속성** + **default** - Snowflake 데이터베이스 인스턴스에 연결하는 데 사용할 JDBC 연결 문자열입니다. 예: `snowflake://${jdbc_connection_string}` + **catalog\$1connection\$1string** – 멀티플렉싱 핸들러에서 사용합니다(Glue 연결을 사용할 때는 지원되지 않음). 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어 Athena에 등록된 카탈로그가 mysnowflakecatalog인 경우 환경 변수 이름은 mysnowflakecatalog\$1connection\$1string입니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **NONE** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다(Snowflake에서와 같이 쿼리 실행). **casing\$1mode**가 지정되지 않은 경우 기본값입니다. + **UPPER** - Snowflake에서 실행하기 전에 쿼리에 지정된 스키마와 테이블 이름을 모두 대문자로 표시합니다. + **LOWER** - Snowflake에서 실행하기 전에 쿼리에 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. + **CASE\$1INSENSITIVE\$1SEARCH** - Snowflake에서 스키마 및 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다. 예를 들어 `SELECT * FROM EMPLOYEE`와 같은 쿼리가 있고 Snowflake에 `Employee`라는 테이블이 포함된 경우 이 모드를 사용할 수 있습니다. 그러나 Snowflake에 `EMPLOYEE`라는 테이블과 `Employee`라는 다른 테이블이 있는 등 이름 충돌이 있는 경우 쿼리에 실패합니다. + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` snowflake://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | SnowflakeMuxCompositeHandler | | 메타데이터 핸들러 | SnowflakeMuxMetadataHandler | | 레코드 핸들러 | SnowflakeMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mysnowflakecatalog인 경우 환경 변수 이름은 mysnowflakecatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `snowflake1`(기본값)과 `snowflake2`라는 2개의 데이터베이스 인스턴스를 지원하는 Snowflake MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1&\$1\$1Test/RDS/Snowflake1\$1 | | snowflake\$1catalog1\$1connection\$1string | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1\$1\$1Test/RDS/Snowflake1\$1 | | snowflake\$1catalog2\$1connection\$1string | snowflake://jdbc:snowflake://snowflake2.host:port/?warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/RDS/Snowflake1}`입니다. ``` snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` snowflake://jdbc:snowflake://snowflake1.host:port/warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2&... ``` 현재 Snowflake는 `user` 및 `password` JDBC 속성을 인식합니다. 또한 `user` 또는 `password` 키 없이 *username*`/`*password* 형식의 사용자 이름과 암호를 허용합니다. #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Snowflake 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | SnowflakeCompositeHandler | | 메타데이터 핸들러 | SnowflakeMetadataHandler | | 레코드 핸들러 | SnowflakeRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Snowflake 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | snowflake://jdbc:snowflake://snowflake1.host:port/?secret=Test/RDS/Snowflake1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | 화살표 | | --- | --- | | 부울 | Bit | | Integer | Tiny | | Short | Smallint | | Integer | 정수 | | Long | Bigint | | 실수 | Float4 | | 배정밀도 실수 | Float8 | | 날짜 | DateDay | | 타임스탬프 | DateMilli | | 문자열 | Varchar | | 바이트 | Varbinary | | BigDecimal | 10진수 | | ARRAY | List | ## 데이터 형식 변환 JDBC에서 Arrow로의 변환 외에도 커넥터는 Snowflake 소스와 Athena 데이터 형식이 호환되도록 다른 특정 변환을 수행합니다. 이러한 변환은 쿼리가 성공적으로 실행되도록 하는 데 도움이 됩니다. 다음 표에 이러한 변환이 나와 있습니다. **** | 소스 데이터 형식(Snowflake) | 변환된 데이터 형식(Athena) | | --- | --- | | TIMESTAMP | TIMESTAMPMILLI | | DATE | TIMESTAMPMILLI | | INTEGER | INT | | DECIMAL | BIGINT | | TIMESTAMP\$1NTZ | TIMESTAMPMILLI | 지원되지 않는 다른 모든 데이터 형식은 `VARCHAR`로 변환됩니다. ## 파티션 및 분할 파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다. 이 합성 열과 파티션을 생성하려면 Athena에 프라이머리 키를 정의해야 합니다. 하지만 Snowflake는 프라이머리 키 제약 조건을 적용하지 않으므로 고유성을 직접 적용해야 합니다. 그렇지 않으면 Athena는 단일 분할을 기본값으로 설정하게 됩니다. ## 성능 최적의 성능을 위해 가능하면 쿼리에 필터를 사용합니다. 또한 파티션 배포가 균일한 방대한 데이터 세트를 검색하려면 기본 파티셔닝을 사용하는 것이 좋습니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. Snowflake 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. Athena Snowflake 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. ### LIMIT 절 `LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Snowflake 커넥터는 이러한 표현식을 결합하고 Snowflake로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Snowflake 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` # Snowflake로 인증 키 페어 인증 또는 OAuth 인증 방법을 사용하여 Snowflake 데이터 웨어하우스에 연결하도록 Amazon Athena Snowflake 커넥터를 구성할 수 있습니다. 두 방법 모두 Snowflake에 대한 보안 액세스를 제공하며 연결 문자열에 암호를 저장할 필요가 없습니다. + **키 페어 인증** - 이 방법은 RSA 퍼블릭 또는 프라이빗 키 페어를 사용하여 Snowflake로 인증합니다. 프라이빗 키는 확인을 위해 해당 퍼블릭 키가 Snowflake에 등록되어 있는 동안 인증 요청에 디지털 방식으로 서명합니다. 이 방법을 사용하면 암호 저장이 필요하지 않습니다. + **OAuth 인증** - 이 방법은 권한 부여 토큰과 새로 고침 토큰을 사용하여 Snowflake로 인증합니다. 이 인증은 자동 토큰 새로 고침을 지원하므로 장기 실행 애플리케이션에 적합합니다. 자세한 내용은 Snowflake 사용 설명서의 [Key-pair authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth) 및 [OAuth authentication](https://docs.snowflake.com/en/user-guide/oauth-custom)을 참조하세요. ## 사전 조건 시작하기 전에 다음 필수 조건을 완료합니다. + 관리 권한이 있는 Snowflake 계정 액세스입니다. + Athena 커넥터 전용 Snowflake 사용자 계정입니다. + 키 페어 인증을 위한 OpenSSL 또는 동등한 키 생성 도구입니다. + AWS Secrets Manager에 액세스하여 보안 암호를 생성하고 관리합니다. + OAuth 인증을 위한 OAuth 흐름을 완료하는 웹 브라우저입니다. ## 키 페어 인증 구성 이 프로세스에는 RSA 키 페어 생성, 퍼블릭 키로 Snowflake 계정 구성, AWS Secrets Manager에 프라이빗 키의 안전한 저장이 포함됩니다. 다음 단계에서는 암호화 키를 생성하고, 필요한 Snowflake 권한을 설정하고, 원활한 인증을 위해 AWS 자격 증명을 구성하는 방법을 안내합니다. 1. **RSA 키 페어 생성** OpenSSL을 사용하여 프라이빗 및 퍼블릭 키 페어를 생성합니다. + 암호화되지 않은 버전을 생성하려면 로컬 명령줄 애플리케이션에서 다음 명령을 사용합니다. ``` openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt ``` + 암호화된 버전을 생성하려면 `-nocrypt`를 생략하는 다음 명령을 사용합니다. ``` openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8 ``` + 프라이빗 키에서 퍼블릭 키를 생성하려면 ``` openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub # Set appropriate permissions (Unix/Linux) chmod 600 rsa_key.p8 chmod 644 rsa_key.pub ``` **참고** 프라이빗 키를 공유해서는 안됩니다. 프라이빗 키는 Snowflake로 인증해야 하는 애플리케이션에서만 액세스할 수 있어야 합니다. 1. **Snowflake에 대한 구분 기호 없이 퍼블릭 키 콘텐츠 추출** ``` # Extract public key content (remove BEGIN/END lines and newlines) cat rsa_key.pub | grep -v "BEGIN\|END" | tr -d '\n' ``` 이 출력은 다음 단계의 뒷부분에서 필요하므로 저장합니다. 1. **Snowflake 사용자 구성** 다음 단계에 따라 Snowflake 사용자를 구성합니다. 1. Athena 커넥터의 전용 사용자가 없는 경우 사용자를 생성합니다. ``` -- Create user for Athena connector CREATE USER athena_connector_user; -- Grant necessary privileges GRANT USAGE ON WAREHOUSE your_warehouse TO ROLE athena_connector_role; GRANT USAGE ON DATABASE your_database TO ROLE athena_connector_role; GRANT SELECT ON ALL TABLES IN DATABASE your_database TO ROLE athena_connector_role; ``` 1. 사용자에게 인증 권한을 부여합니다. 사용자에게 퍼블릭 키를 할당하려면 다음 역할 또는 권한 중 하나가 있어야 합니다. + 사용자에 대한 `MODIFY PROGRAMMATIC AUTHENTICATION METHODS` 또는 `OWNERSHIP` 권한입니다. + `SECURITYADMIN` 역할 이상입니다. 다음 명령을 사용하여 퍼블릭 키를 할당하는 데 필요한 권한을 부여합니다. ``` GRANT MODIFY PROGRAMMATIC AUTHENTICATION METHODS ON USER athena_connector_user TO ROLE your_admin_role; ``` 1. 다음 명령을 사용하여 Snowflake 사용자에게 퍼블릭 키를 할당합니다. ``` ALTER USER athena_connector_user SET RSA_PUBLIC_KEY='RSAkey'; ``` 다음 명령을 사용하여 퍼블릭 키가 사용자에게 성공적으로 할당되었는지 확인합니다. ``` DESC USER athena_connector_user; ``` 1. **AWS Secrets Manager에 프라이빗 키 저장** 1. 프라이빗 키를 커넥터에 필요한 형식으로 변환합니다. ``` # Read private key content cat rsa_key.p8 ``` 1. 다음 구조를 사용하여 AWS Secrets Manager에서 보안 암호를 생성합니다. ``` { "sfUser": "your_snowflake_user", "pem_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----", "pem_private_key_passphrase": "passphrase_in_case_of_encrypted_private_key(optional)" } ``` **참고** 헤더와 바닥글은 선택 사항입니다. 프라이빗 키는 `\n`(으)로 구분해야 합니다. ## OAuth 인증 구성 이 인증 방법을 사용하면 자동 자격 증명 새로 고침 기능을 통해 Snowflake에 대한 안전한 토큰 기반 액세스가 가능합니다. 구성 프로세스에는 Snowflake에서 보안 통합 생성, OAuth 클라이언트 자격 증명 검색, 액세스 코드를 얻기 위한 권한 부여 흐름 완료, 커넥터가 사용할 OAuth 자격 증명을 AWS Secrets Manager에 저장하는 작업이 포함됩니다. 1. **Snowflake에서 보안 통합 생성** Snowflake에서 다음 SQL 명령을 실행하여 Snowflake OAuth 보안 통합을 생성합니다. ``` CREATE SECURITY INTEGRATION my_snowflake_oauth_integration_a TYPE = OAUTH ENABLED = TRUE OAUTH_CLIENT = CUSTOM OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' OAUTH_REDIRECT_URI = 'https://localhost:8080/oauth/callback' OAUTH_ISSUE_REFRESH_TOKENS = TRUE OAUTH_REFRESH_TOKEN_VALIDITY = 7776000; ``` **구성 파라미터** + `TYPE = OAUTH` - OAuth 인증 유형을 지정합니다. + `ENABLED = TRUE` - 보안 통합을 활성화합니다. + `OAUTH_CLIENT = CUSTOM` - 사용자 지정 OAuth 클라이언트 구성을 사용합니다. + `OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'` - 보안 애플리케이션의 클라이언트 유형을 설정합니다. + `OAUTH_REDIRECT_URI` - OAuth 흐름의 콜백 URL입니다. 테스트를 위한 localhost일 수 있습니다. + `OAUTH_ISSUE_REFRESH_TOKENS = TRUE` - 새로 고침 토큰 생성을 활성화합니다. + `OAUTH_REFRESH_TOKEN_VALIDITY = 7776000` - 새로 고침 토큰 유효 기간(초 단위 90일)을 설정합니다. 1. **OAuth 클라이언트 보안 암호 검색** 1. 이 클라이언트 자격 증명을 가져오려면 다음 SQL 명령을 실행합니다. ``` DESC SECURITY INTEGRATION 'MY_SNOWFLAKE_OAUTH_INTEGRATION_A'; ``` 1. OAuth 클라이언트 보안 암호를 검색합니다. ``` SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('MY_SNOWFLAKE_OAUTH_INTEGRATION_A'); ``` **응답의 예** ``` { "OAUTH_CLIENT_SECRET_2": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "OAUTH_CLIENT_SECRET": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY, "OAUTH_CLIENT_ID": "AIDACKCEVSQ6C2EXAMPLE" } ``` **참고** 이러한 자격 증명을 안전하게 저장하고 공유해서는 안됩니다. 이 자격 증명은 OAuth 클라이언트를 구성하는 데 사용됩니다. 1. **사용자 권한 부여 및 권한 부여 코드 검색** 1. 브라우저에서 다음 URL을 엽니다. ``` https://.snowflakecomputing.com/oauth/authorize?client_id=&response_type=code&redirect_uri=https://localhost:8080/oauth/callback ``` 1. 권한 부여 흐름을 완료합니다. 1. Snowflake 자격 증명을 사용하여 로그인합니다. 1. 요청된 권한을 부여합니다. 권한 부여 코드가 있는 콜백 URI로 리디렉션됩니다. 1. 리디렉션 URL에서 코드 파라미터를 복사하여 권한 부여 코드를 추출합니다. ``` https://localhost:8080/oauth/callback?code= ``` **참고** 권한 부여 코드는 제한된 시간 동안 유효하며 한 번만 사용할 수 있습니다. 1. **AWS Secrets Manager에 OAuth 자격 증명 저장** 다음 구조를 사용하여 AWS Secrets Manager에서 보안 암호를 생성합니다. ``` { "redirect_uri": "https://localhost:8080/oauth/callback", "client_secret": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY", "token_url": "https://.snowflakecomputing.com/oauth/token-request", "client_id": "AIDACKCEVSQ6C2EXAMPLE, "username": "your_snowflake_username", "auth_code": "authorizationcode" } ``` **필수 필드** + `redirect_uri` - 1단계에서 얻은 OAuth 리디렉션 URI입니다. + `client_secret` - 2단계에서 얻은 OAuth 클라이언트 보안 암호입니다. + `token_url` – Snowflake OAuth 토큰 엔드포인트입니다. + `client_id` - 2단계에서 얻은 OAuth 클라이언트 ID입니다. + `username` - 커넥터의 Snowflake 사용자 이름입니다. + `auth_code` - 3단계에서 얻은 권한 부여 코드입니다. 보안 암호를 생성한 후 [데이터 소스 연결을 생성](connect-to-a-data-source.md)할 때 Glue 연결에 사용할 수 있는 보안 암호 ARN을 가져옵니다. ## 패스스루 쿼리 Snowflake 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Snowflake에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Snowflake의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Snowflake 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-snowflake)를 참조하세요. # Amazon Athena Microsoft SQL Server 커넥터 [Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/?view=sql-server-ver15)용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 JDBC를 사용하여 Microsoft SQL Server에 저장된 데이터에 대해 SQL 쿼리를 실행할 수 있습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. + 필터 조건에서 `Date` 및 `Timestamp` 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다. + `Real` 및 `Float` 형식의 음수 값을 검색하려면 `<=` 또는 `>=` 연산자를 사용합니다. + `binary`, `varbinary`, `image` 및 `rowversion` 데이터 형식은 지원되지 않습니다. ## 용어 다음 용어는 SQL Server 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 SQL Server 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 SQL Server 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 SQL Server 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type SQLSERVER ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 SQL Server 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 SQL Server 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` sqlserver://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | SqlServerMuxCompositeHandler | | 메타데이터 핸들러 | SqlServerMuxMetadataHandler | | 레코드 핸들러 | SqlServerMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mysqlservercatalog인 경우 환경 변수 이름은 mysqlservercatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `sqlserver1`(기본값)과 `sqlserver2`라는 2개의 데이터베이스 인스턴스를 지원하는 SqlServer MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 | | sqlserver\$1catalog1\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 | | sqlserver\$1catalog2\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver2.hostname:port;databaseName=;\$1\$1secret2\$1name\$1 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${secret_name}`입니다. ``` sqlserver://jdbc:sqlserver://hostname:port;databaseName=;${secret_name} ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` sqlserver://jdbc:sqlserver://hostname:port;databaseName=;user=;password= ``` #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 SQL Server 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | SqlServerCompositeHandler | | 메타데이터 핸들러 | SqlServerMetadataHandler | | 레코드 핸들러 | SqlServerRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 SQL Server 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | sqlserver://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 SQL Server와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | SQL Server | 화살표 | | --- | --- | | bit | TINYINT | | tinyint | SMALLINT | | smallint | SMALLINT | | int | INT | | bigint | BIGINT | | decimal | DECIMAL | | numeric | FLOAT8 | | smallmoney | FLOAT8 | | money | DECIMAL | | float[24] | FLOAT4 | | float[53] | FLOAT8 | | real | FLOAT4 | | datetime | Date(MILLISECOND) | | datetime2 | Date(MILLISECOND) | | smalldatetime | Date(MILLISECOND) | | 날짜 | Date(DAY) | | 시간 | VARCHAR | | datetimeoffset | Date(MILLISECOND) | | char[n] | VARCHAR | | varchar[n/max] | VARCHAR | | nchar[n] | VARCHAR | | nvarchar[n/max] | VARCHAR | | 텍스트 | VARCHAR | | ntext | VARCHAR | ## 파티션 및 분할 파티션은 `varchar` 형식의 단일 파티션 열로 표시됩니다. SQL Server 커넥터의 경우 파티션 함수에 따라 테이블에 파티션이 적용되는 방식이 결정됩니다. 파티션 함수 및 열 이름 정보는 SQL Server 메타데이터 테이블에서 검색됩니다. 그런 다음 사용자 지정 쿼리가 파티션을 가져옵니다. 분할은 수신된 개별 파티션 수를 기준으로 생성됩니다. ## 성능 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. SQL Server 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena SQL Server 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena SQL Server 커넥터는 이러한 표현식을 결합하고 SQL Server로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena SQL Server 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 패스스루 쿼리 SQL Server 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. SQL Server에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 SQL Server의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 SQL Server 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-sqlserver)를 참조하세요. # Amazon Athena Teradata 커넥터 Teradata용 Amazon Athena 커넥터를 사용하면 Athena가 Teradata 데이터베이스에 저장된 데이터에 대해 SQL 쿼리를 실행할 수 있습니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 제한 사항 + DDL 쓰기 작업은 지원되지 않습니다. + 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. ## 용어 다음 용어는 Teradata 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. + **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러. ## 파라미터 이 섹션의 파라미터를 사용하여 Teradata 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Teradata 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Teradata 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type TERADATA ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Teradata 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Teradata 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` teradata://${jdbc_connection_string} ``` #### 멀티플렉싱 핸들러 사용 멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다. **** | 핸들러 | Class | | --- | --- | | 복합 핸들러 | TeradataMuxCompositeHandler | | 메타데이터 핸들러 | TeradataMuxMetadataHandler | | 레코드 핸들러 | TeradataMuxRecordHandler | ##### 멀티플렉싱 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 myteradatacatalog인 경우 환경 변수 이름은 myteradatacatalog\$1connection\$1string입니다. | | default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 다음은 `teradata1`(기본값)과 `teradata2`라는 2개의 데이터베이스 인스턴스를 지원하는 Teradata MUX Lambda 함수에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | teradata://jdbc:teradata://teradata2.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,user=sample2&password=sample2 | | teradata\$1catalog1\$1connection\$1string | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,\$1\$1Test/RDS/Teradata1\$1 | | teradata\$1catalog2\$1connection\$1string | teradata://jdbc:teradata://teradata2.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,user=sample2&password=sample2 | ##### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 `${Test/RDS/Teradata1}`입니다. ``` teradata://jdbc:teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,${Test/RDS/Teradata1}&... ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,...&user=sample2&password=sample2&... ``` 현재 Teradata는 `user` 및 `password` JDBC 속성을 인식합니다. 또한 `user` 또는 `password` 키 없이 *username*`/`*password* 형식의 사용자 이름과 암호를 허용합니다. #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Teradata 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | TeradataCompositeHandler | | 메타데이터 핸들러 | TeradataMetadataHandler | | 레코드 핸들러 | TeradataRecordHandler | ##### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. 다음은 Lambda 함수에서 지원하는 단일 Teradata 인스턴스에 대한 예제 속성입니다. **** | 속성 | 값 | | --- | --- | | default | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,secret=Test/RDS/Teradata1 | #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다. **** | JDBC | 화살표 | | --- | --- | | 부울 | Bit | | Integer | Tiny | | Short | Smallint | | Integer | 정수 | | Long | Bigint | | 실수 | Float4 | | 배정밀도 실수 | Float8 | | 날짜 | DateDay | | 타임스탬프 | DateMilli | | 문자열 | Varchar | | 바이트 | Varbinary | | BigDecimal | 10진수 | | ARRAY | List | ## 파티션 및 분할 파티션은 `Integer` 형식의 단일 파티션 열로 표시됩니다. 열에는 Teradata 테이블에 정의된 파티션의 이름이 들어 있습니다. 파티션 이름이 없는 테이블의 경우 단일 파티션에 해당하는 \$1가 반환됩니다. 파티션은 분할과 동일합니다. **** | 이름 | Type | 설명 | | --- | --- | --- | | 파티션 | Integer | Teradata의 명명된 파티션. | ## 성능 Teradata는 기본 파티션을 지원합니다. Athena Teradata 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다. 열 하위 집합을 선택하면 쿼리 런타임이 크게 느려집니다. 이 커넥터는 동시성으로 인해 약간의 제한을 나타냅니다. 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Teradata 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다. ### Predicates 조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena Teradata 커넥터는 이러한 표현식을 결합하고 Teradata로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다. 다음 Athena Teradata 커넥터 연산자는 조건자 푸시다운을 지원합니다. + **부울: **AND, OR, NOT + **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, NULL\$1IF, IS\$1NULL + **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE + **기타: **LIKE\$1PATTERN, IN ### 결합된 푸시다운 예제 쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다. ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 패스스루 쿼리 Teradata 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Teradata에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Teradata의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리가 `customer` 테이블의 모든 열을 선택합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Teradata 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-teradata)를 참조하세요. # Amazon Athena Timestream 커넥터 Amazon Athena Timestream 커넥터를 사용하면 Amazon Athena가 [Amazon Timestream](https://aws.amazon.com/timestream/)과 통신할 수 있으므로 Amazon Athena를 통해 시계열 데이터에 액세스할 수 있습니다. 선택에 따라 AWS Glue Data Catalog를 보충 메타데이터의 소스로 사용할 수 있습니다. Amazon Timestream은 빠르고 확장 가능한 완전 관리형 특수 목적 시계열 데이터베이스로, 매일 수조 개의 시계열 데이터 포인트를 쉽게 저장하고 분석할 수 있습니다. Timestream은 사용자 정의 정책에 따라 최근 데이터는 메모리에 보관하고 기록 데이터는 비용 최적화 스토리지 계층으로 이동하여 시계열 데이터의 수명주기를 관리하는 데 드는 시간과 비용을 절약합니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. 계정에서 Lake Formation을 활성화한 경우 AWS Serverless Application Repository에 배포한 Athena 페더레이션형 Lambda 커넥터의 IAM 역할은 Lake Formation에서 AWS Glue Data Catalog에 대한 읽기 액세스 권한을 가지고 있어야 합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 Timestream 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Timestream 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Timestream 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type TIMESTREAM ``` **Lambda 환경 속성** **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Timestream 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Timestream 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다. **Lambda 환경 속성** + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. + **glue\$1catalog** – (선택 사항) 이 옵션을 사용하여 [크로스 계정 AWS Glue 카탈로그](data-sources-glue-cross-account.md)를 지정합니다. 기본적으로 커넥터는 자체 AWS Glue 계정에서 메타데이터를 가져오려고 시도합니다. ## AWS Glue에서 데이터베이스 및 테이블 설정 필요에 따라 AWS Glue Data Catalog를 보충 메타데이터의 소스로 사용할 수 있습니다. Timestream에서 사용할 AWS Glue 테이블을 활성화하려면 보충 메타데이터를 제공할 Timestream 데이터베이스 및 테이블과 이름이 일치하는 AWS Glue 데이터베이스 및 테이블이 있어야 합니다. **참고** 최상의 성능을 얻으려면 데이터베이스 이름과 테이블 이름에 소문자만 사용합니다. 대/소문자를 혼합하여 사용하면 커넥터에서 대소문자를 구분하지 않고 검색하므로 더욱 컴퓨팅 집약적입니다. Timestream에서 사용할 AWS Glue 테이블을 구성하려면 AWS Glue에서 테이블 속성을 설정해야 합니다. **보충 메타데이터에 AWS Glue 테이블 사용** 1. AWS Glue 콘솔에서 테이블을 편집하여 다음 테이블 속성을 추가합니다. + **timestream-metadata-flag** – 이 속성은 보충 메타데이터에 테이블을 사용할 수 있음을 Timestream 커넥터에 나타냅니다. `timestream-metadata-flag` 속성이 테이블 속성 목록에 있는 한 `timestream-metadata-flag`에 모든 값을 제공할 수 있습니다. + **\$1view\$1template** – 보충 메타데이터에 AWS Glue를 사용하는 경우 이 테이블 속성을 사용하고 모든 Timestream SQL을 보기로 지정할 수 있습니다. Athena Timestream 커넥터는 보기의 SQL을 Athena의 SQL과 함께 사용하여 쿼리를 실행합니다. 이는 Athena에서 사용할 수 없는 Timestream SQL의 기능을 사용하려는 경우에 유용합니다. 1. 이 문서에 나열된 대로 AWS Glue에 적합한 데이터 형식을 사용해야 합니다. ### 데이터 타입 현재 Timestream 커넥터는 Timestream에서 사용 가능한 데이터 형식의 하위 세트, 특히 스칼라 값 `varchar`, `double` 및 `timestamp`만 지원합니다. `timeseries` 데이터 형식을 쿼리하려면 Timestream `CREATE_TIME_SERIES` 함수를 사용하는 AWS Glue 테이블 속성에서 보기를 구성해야 합니다. 또한 시계열 열의 유형으로 `ARRAY>` 구문을 사용하는 보기에 대한 스키마를 제공해야 합니다. `double`을 테이블에 적합한 스칼라 유형으로 바꿉니다. 다음 이미지는 시계열에 대한 보기를 설정하도록 구성된 AWS Glue 테이블 속성의 예제를 보여줍니다. ![\[AWS Glue에서 테이블 속성을 구성하여 시계열에 대한 보기 설정.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-timestream-1.png) ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-timestream.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-timestream/athena-timestream.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. + **AWS Glue Data Catalog** - 스키마 정보를 가져오기 위해 Timestream 커넥터에 AWS Glue Data Catalog에 대한 읽기 전용 액세스 권한이 필요합니다. + **CloudWatch Logs** - 로그를 저장하기 위해 커넥터 CloudWatch Logs에 대한 액세스 권한이 필요합니다. + **Timestream 액세스** - Timestream 쿼리를 실행하는 데 사용됩니다. ## 성능 대화형 쿼리가 제대로 작동하려면 반환되는 데이터(스캔되는 데이터 아님)를 256MB 미만으로 제한하는 `LIMIT` 절을 사용하는 것이 좋습니다. Athena Timestream 커넥터는 조건자 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절은 스캔하는 데이터를 줄이지만 조건자가 제공되지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. Timestream 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. ## 패스스루 쿼리 Timestream 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Timestream에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Timestream의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 Amazon Athena Timestream 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-timestream)를 참조하세요. # Amazon Athena TPC Benchmark DS(TPC-DS) 커넥터 Amazon Athena TPC-DS 커넥터를 통해 Amazon Athena는 Athena Federation의 벤치마킹 및 기능 테스트에 사용하기 위해 무작위로 생성된 TPC 벤치마크 DS 데이터 소스와 통신할 수 있습니다. Athena TPC-DS 커넥터는 네 가지 확장 요소 중 하나로 TPC-DS 호환 데이터베이스를 생성합니다. Amazon S3 기반 데이터 레이크 성능 테스트의 대안으로 이 커넥터를 사용하지 않는 것이 좋습니다. 이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. ## 파라미터 이 섹션의 파라미터를 사용하여 TPC-DS 커넥터를 구성합니다. **참고** 2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다. 아래에 나열된 파라미터 이름과 정의는 2024년 12월 3일 이전에 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. 이는 해당 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)과 차이가 있을 수 있습니다. 2024년 12월 3일부터 Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하는 경우에만 아래 파라미터를 사용합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 TPC-DS 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 TPC-DS 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type TPCDS ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Snowflake TPC-DS 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 TPC-DS 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 + **spill\$1bucket** – Lambda 함수 제한을 초과하는 데이터에 대한 Amazon S3 버킷을 지정합니다. + **spill\$1prefix** – (선택 사항) 기본값은 `athena-federation-spill`이라는 지정된 `spill_bucket`의 하위 폴더입니다. 미리 정해진 일 수 또는 시간보다 오래된 유출을 삭제하려면 이 위치에서 Amazon S3 [스토리지 수명 주기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 구성하는 것이 좋습니다. + **spill\$1put\$1request\$1headers** – (선택 사항) 유출에 사용되는 Amazon S3 `putObject` 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵입니다(예: `{"x-amz-server-side-encryption" : "AES256"}`). 다른 가능한 헤더를 알아보려면 *Amazon Simple Storage Service API Reference*(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. + **kms\$1key\$1id** – (선택 사항) 기본적으로 Amazon S3로 유출된 모든 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. Lambda 함수가 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`과 같이 KMS에서 생성된 더 강력한 암호화 키를 사용하도록 하려면 KMS 키 ID를 지정합니다. + **disable\$1spill\$1encryption** – (선택 사항) `True`로 설정하면 유출 암호화가 비활성화됩니다. S3로 유출되는 데이터가 AES-GCM을 사용하여 암호화되도록 기본값은 `False`입니다(임의로 생성된 키 또는 KMS를 사용하여 키 생성). 유출 암호화를 비활성화하면 특히 유출 위치가 [서버 측 암호화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)를 사용하는 경우 성능이 향상될 수 있습니다. ## 데이터베이스 및 테이블 테스트 Athena TPC-DS 커넥터는 4개의 스케일 팩터 `tpcds1`, `tpcds10`, `tpcds100`, `tpcds250` 또는 `tpcds1000` 중 하나로 TPC-DS 호환 데이터베이스를 생성합니다. ### 테이블 요약 테스트 데이터 테이블 및 열의 전체 목록을 보려면 `SHOW TABLES` 또는 `DESCRIBE TABLE` 쿼리를 실행합니다. 편의를 위해 다음 표 요약이 제공됩니다. 1. call\$1center 1. catalog\$1page 1. catalog\$1returns 1. catalog\$1sales 1. customer 1. customer\$1address 1. customer\$1demographics 1. date\$1dim 1. dbgen\$1version 1. household\$1demographics 1. income\$1band 1. Inventory 1. item 1. promotion 1. reason 1. ship\$1mode 1. store 1. store\$1returns 1. store\$1sales 1. time\$1dim 1. warehouse 1. web\$1page 1. web\$1returns 1. web\$1sales 1. web\$1site 이렇게 생성된 스키마 및 데이터와 호환되는 TPC-DS 쿼리를 알아보려면 GitHub의 [athena-tpcds/src/main/resources/queries/](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds/src/main/resources/queries) 디렉터리를 참조하세요. ### 예제 쿼리 다음 `SELECT` 쿼리 예제는 특정 군(country)의 고객 인구 통계에 대해 `tpcds` 카탈로그를 쿼리합니다. ``` SELECT cd_gender, cd_marital_status, cd_education_status, count(*) cnt1, cd_purchase_estimate, count(*) cnt2, cd_credit_rating, count(*) cnt3, cd_dep_count, count(*) cnt4, cd_dep_employed_count, count(*) cnt5, cd_dep_college_count, count(*) cnt6 FROM "lambda:tpcds".tpcds1.customer c, "lambda:tpcds".tpcds1.customer_address ca, "lambda:tpcds".tpcds1.customer_demographics WHERE c.c_current_addr_sk = ca.ca_address_sk AND ca_county IN ('Rush County', 'Toole County', 'Jefferson County', 'Dona Ana County', 'La Porte County') AND cd_demo_sk = c.c_current_cdemo_sk AND exists(SELECT * FROM "lambda:tpcds".tpcds1.store_sales, "lambda:tpcds".tpcds1.date_dim WHERE c.c_customer_sk = ss_customer_sk AND ss_sold_date_sk = d_date_sk AND d_year = 2002 AND d_moy BETWEEN 1 AND 1 + 3) AND (exists(SELECT * FROM "lambda:tpcds".tpcds1.web_sales, "lambda:tpcds".tpcds1.date_dim WHERE c.c_customer_sk = ws_bill_customer_sk AND ws_sold_date_sk = d_date_sk AND d_year = 2002 AND d_moy BETWEEN 1 AND 1 + 3) OR exists(SELECT * FROM "lambda:tpcds".tpcds1.catalog_sales, "lambda:tpcds".tpcds1.date_dim WHERE c.c_customer_sk = cs_ship_customer_sk AND cs_sold_date_sk = d_date_sk AND d_year = 2002 AND d_moy BETWEEN 1 AND 1 + 3)) GROUP BY cd_gender, cd_marital_status, cd_education_status, cd_purchase_estimate, cd_credit_rating, cd_dep_count, cd_dep_employed_count, cd_dep_college_count ORDER BY cd_gender, cd_marital_status, cd_education_status, cd_purchase_estimate, cd_credit_rating, cd_dep_count, cd_dep_employed_count, cd_dep_college_count LIMIT 100 ``` ## 필수 권한 이 커넥터에 필요한 IAM 정책에 대한 자세한 내용을 알아보려면 [athena-tpcds.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-tpcds/athena-tpcds.yaml) 파일의 `Policies` 섹션을 검토하세요. 다음 목록에 필요한 권한이 요약되어 있습니다. + **Amazon S3 쓰기 액세스** - 대규모 쿼리의 결과 유출을 위해서는 커넥터에 Amazon S3 위치에 대한 쓰기 액세스 권한이 필요합니다. + **Athena GetQueryExecution** - 커넥터는 업스트림 Athena 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다. ## 성능 Athena TPC-DS 커넥터는 선택한 스케일 팩터를 기준으로 쿼리 병렬화를 시도합니다. 조건자 푸시다운은 Lambda 함수 내에서 수행됩니다. ## 라이선스 정보 Amazon Athena TPC-DS 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다. ## 추가 리소스 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds)를 참조하세요. # Amazon Athena Vertica 커넥터 Vertica는 클라우드 또는 온프레미스에 배포할 수 있는 열 형식 데이터베이스 플랫폼으로서 엑사바이트 규모의 데이터 웨어하우스를 지원합니다. 연합 쿼리에 Amazon Athena Vertica 커넥터를 사용하여 Athena에서 Vertica 데이터 원본을 쿼리할 수 있습니다. 예를 들어 Vertica의 데이터 웨어하우스와 Amazon S3의 데이터 레이크에 대해 분석 쿼리를 실행할 수 있습니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. ## 사전 조건 + Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요. + 이 커넥터를 사용하기 전에 VPC와 보안 그룹을 설정합니다. 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) 섹션을 참조하세요. ## 제한 사항 + Athena Vertica 커넥터는 Amazon S3에서 내보낸 Parquet 파일을 읽기 때문에 커넥터의 성능이 느려질 수 있습니다. 큰 테이블을 쿼리할 때는 [CREATE TABLE AS (SELECT ...)](ctas.md) 쿼리와 SQL 조건자를 사용하는 것이 좋습니다. + 현재 Athena 연합 쿼리의 알려진 문제 때문에 커넥터로 인해 Vertica가 쿼리된 테이블의 모든 열을 Amazon S3로 내보내지만 쿼리된 열만 Athena 콘솔의 결과에 표시됩니다. + DDL 쓰기 작업은 지원되지 않습니다. + 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요. ## 워크플로 다음 다이어그램은 Vertica 커넥터를 사용하는 쿼리의 워크플로를 보여줍니다. ![\[Amazon Athena의 Vertica 쿼리 워크플로\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-vertica-1.png) 1. Vertica에 있는 하나 이상의 테이블에 대해 SQL 쿼리가 실행됩니다. 1. 커넥터는 SQL 쿼리를 구문 분석하여 JDBC 연결을 통해 관련 부분을 Vertica로 보냅니다. 1. 연결 문자열은 AWS Secrets Manager에 저장된 사용자 이름과 암호를 사용하여 Vertica에 액세스합니다. 1. 커넥터는 다음 예와 같이 Vertica `EXPORT` 명령으로 SQL 쿼리를 래핑합니다. ``` EXPORT TO PARQUET (directory = 's3://amzn-s3-demo-bucket/folder_name, Compression='Snappy', fileSizeMB=64) OVER() as SELECT PATH_ID, ... SOURCE_ITEMIZED, SOURCE_OVERRIDE FROM DELETED_OBJECT_SCHEMA.FORM_USAGE_DATA WHERE PATH_ID <= 5; ``` 1. Vertica는 SQL 쿼리를 처리하고 결과 세트를 Amazon S3 버킷으로 보냅니다. 처리량 향상을 위해 Vertica는 `EXPORT` 옵션을 사용하여 여러 Parquet 파일의 쓰기 작업을 병렬화합니다. 1. Athena는 Amazon S3 버킷을 스캔하여 결과 세트에 대해 읽을 파일 수를 결정합니다. 1. Athena는 Lambda 함수를 여러 번 호출하고 Amazon `ArrowReader`를 사용하여 결과 데이터 세트에서 Parquet 파일을 읽습니다. 여러 번의 호출을 통해 Athena는 Amazon S3 파일 읽기를 병렬화하고 초당 최대 100GB의 처리량을 달성할 수 있습니다. 1. Athena는 데이터 레이크에서 스캔한 데이터로 Vertica에서 반환된 데이터를 처리하고 결과를 반환합니다. ## 용어 다음 용어는 Vertica 커넥터와 관련이 있습니다. + **데이터베이스 인스턴스** - Amazon EC2에 배포된 Vertica 데이터베이스의 모든 인스턴스. + **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다. + **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러. + **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러. + **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러. + **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다. + **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열. + **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그. ## 파라미터 이 섹션의 파라미터를 사용하여 Vertica 커넥터를 구성합니다. ### Glue 연결(권장) Glue 연결 객체를 사용하여 Vertica 커넥터를 구성하는 것이 좋습니다. 이렇게 하려면 Vertica 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다. **Glue 연결 속성** 다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다. ``` aws glue describe-connection-type --connection-type VERTICA ``` **Lambda 환경 속성** + **glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다. + **casing\$1mode** - (선택 사항) 스키마 및 테이블 이름의 대소문자를 처리하는 방법을 지정합니다. `casing_mode` 파라미터는 다음 값을 사용하여 대소문자 지정 동작을 지정합니다. + **none** - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다. 연결된 Glue 연결이 있는 커넥터의 기본값입니다. + **upper** - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다. + **lower** - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다. **참고** Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다. Glue 연결을 사용하여 생성된 Vertica 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다. Glue 연결을 사용하여 생성된 Vertica 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다. ### 레거시 연결 Amazon Athena Vertica 커넥터는 Lambda 환경 변수를 통해 구성 옵션을 제공합니다. 다음 Lambda 환경 변수를 사용하여 커넥터를 구성할 수 있습니다. + **AthenaCatalogName** – Lambda 함수 이름입니다. + **ExportBucket** – Vertica 쿼리 결과를 내보내는 Amazon S3 버킷입니다. + **SpillBucket** – 이 함수가 데이터를 유출할 수 있는 Amazon S3 버킷의 이름입니다. + **SpillPrefix** – 이 함수가 데이터를 유출할 수 있는 `SpillBucket` 위치의 접두사입니다. + **SecurityGroupIds** – Lambda 함수에 적용해야 하는 보안 그룹에 해당하는 하나 이상의 ID입니다(예: `sg1`, `sg2` 또는 `sg3`). + **SubnetIds** – Lambda 함수가 데이터 소스에 액세스하는 데 사용할 수 있는 서브넷에 해당하는 하나 이상의 서브넷 ID입니다(예: `subnet1` 또는 `subnet2`). + **SecretNameOrPrefix** – 이 함수가 액세스할 수 있는 Secrets Manager 이름 세트의 이름 또는 접두사입니다(예: `vertica-*`). + **VerticaConnectionString** – 카탈로그 관련 연결이 정의되지 않은 경우 기본적으로 사용할 Vertica 연결 세부 정보입니다. 문자열은 선택적으로 AWS Secrets Manager 구문(예: `${secret_name}`)을 사용할 수 있습니다. + **VPC ID** – Lambda 함수에 연결할 VPC ID입니다. #### 연결 문자열 다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다. ``` vertica://jdbc:vertica://host_name: port/database?user=vertica-username&password= vertica-password ``` #### 단일 연결 핸들러 사용 다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Vertica 인스턴스에 연결할 수 있습니다. **** | 핸들러 유형 | Class | | --- | --- | | 복합 핸들러 | VerticaCompositeHandler | | 메타데이터 핸들러 | VerticaMetadataHandler | | 레코드 핸들러 | VerticaRecordHandler | #### 단일 연결 핸들러 파라미터 **** | 파라미터 | 설명 | | --- | --- | | default | 필수 사항입니다. 기본 연결 문자열. | 단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다. #### 자격 증명 제공 JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다. + **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다. **중요** 보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요. + **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다. JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다. Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다. ``` {"username": "${username}", "password": "${password}"} ``` **보안 암호 이름이 있는 연결 문자열의 예제** 다음 문자열의 보안 암호 이름은 \$1\$1`vertica-username`\$1 및 `${vertica-password}`입니다. ``` vertica://jdbc:vertica:// host_name:port/database?user=${vertica-username}&password=${vertica-password} ``` 커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다. ``` vertica://jdbc:vertica:// host_name:port/database?user=sample-user&password=sample-password ``` 현재 Vertica 커넥터는 `vertica-username` 및 `vertica-password` JDBC 속성을 인식합니다. #### 유출 파라미터 Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다. **** | 파라미터 | 설명 | | --- | --- | | spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | | spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | | spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | ## 데이터 형식 지원 다음 표에 Vertica 커넥터의 지원되는 데이터 형식이 나와 있습니다. **** | 부울 | | --- | | BigInt | | Short | | Integer | | Long | | Float | | 배정밀도 실수 | | 날짜 | | Varchar | | 바이트 | | BigDecimal | | TimeStamp as Varchar | ## 성능 Lambda 함수는 프로젝션 푸시다운을 수행하여 쿼리에서 스캔되는 데이터를 줄입니다. `LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자가 제공되지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. Vertica 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. ## 패스스루 쿼리 Vertica 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다. Vertica에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다. ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 다음 예제 쿼리는 Vertica의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 라이선스 정보 이 커넥터를 사용하면 이 커넥터에 대한 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) 파일에서 목록을 찾을 수 있는 타사 구성 요소가 포함되어 있음을 인정하고 GitHub.com의 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/LICENSE.txt) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다. ## 추가 리소스 최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 Vertica 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) 파일을 참조하세요. 이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-vertica) 및 *AWS Big Data Blog*(빅 데이터 블로그)의 [Querying a Vertica data source in Amazon Athena using the Athena Federated Query SDK](https://aws.amazon.com/blogs/big-data/querying-a-vertica-data-source-in-amazon-athena-using-the-athena-federated-query-sdk/)(Athena 연합 쿼리 SDK를 사용하여 Amazon Athena에서 Vertica 데이터 소스 쿼리)를 참조하세요. # 데이터 소스 연결 생성 Athena 데이터 소스 커넥터를 사용하려면 커넥터 및 데이터 소스에 대한 연결 정보를 저장하는 AWS Glue 연결을 생성합니다. 연결을 생성할 때 SQL 쿼리에서 데이터 소스를 참조하는 데 사용할 이름을 데이터 소스에 지정합니다. [콘솔](connect-to-a-data-source-console-steps.md) 또는 [CreateDataCatalog API](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateDataCatalog.html) 작업을 사용하여 Athena에서 데이터 소스 연결을 생성하고 구성할 수 있습니다. **Topics** + [Athena에서 데이터 소스를 생성하고 사용할 수 있는 권한](connect-to-a-data-source-permissions.md) + [Athena 콘솔을 사용하여 데이터 소스에 연결](connect-to-a-data-source-console-steps.md) + [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) + [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) + [AWS 계정으로 ECR 이미지 가져오기](pull-ecr-customer-account.md) + [연결을 Glue 데이터 카탈로그로 등록](register-connection-as-gdc.md) + [교차 계정 페더레이션 쿼리 활성화](xacct-fed-query-enable.md) + [데이터 소스 커넥터 업데이트](connectors-updating.md) # Athena에서 데이터 소스를 생성하고 사용할 수 있는 권한 데이터 소스를 생성하고 사용하려면 다음 권한 집합이 필요합니다. + AmazonAthenaFullAccess는 Amazon Athena에 대한 전체 액세스 권한과 쿼리, 결과 작성, 데이터 관리를 활성화하는 데 필요한 종속 항목에 대한 범위 지정 액세스 권한을 제공합니다. 자세한 내용은 AWS 관리형 정책 참조 안내서의 [AmazonAthenaFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html)를 참조하세요. + CreateDataCatalog API를 호출할 수 있는 권한입니다. 이러한 권한은 Glue 연결과 통합되는 데이터 소스를 생성할 때만 필요합니다. 예제 정책에 대한 자세한 내용은 [커넥터 및 Athena 카탈로그를 생성하기 위해 필요한 권한](athena-catalog-access.md) 섹션을 참조하세요. + Lake Formation의 세분화된 액세스 제어를 사용하려면 위에 나열된 권한 외에 다음 권한도 필요합니다. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "lakeformation:RegisterResource", "iam:ListRoles", "glue:CreateCatalog", "glue:GetCatalogs", "glue:GetCatalog" ], "Resource": "*" } ] } ``` ------ # Athena 콘솔을 사용하여 데이터 소스에 연결 Athena 콘솔을 사용하여 데이터 소스 연결을 생성하고 구성할 수 있습니다. **데이터 소스에 대한 연결을 생성하려면** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 **데이터 소스 생성**을 선택합니다. 1. **데이터 원본 선택(Choose data source)**에서 다음 지침을 고려하여 에서 쿼리할 데이터 원본을 선택합니다. + 데이터 소스에 해당하는 연결 옵션을 선택합니다. Athena에는 MySQL, Amazon DocumentDB 및 PostgreSQL을 포함한 소스에 대해 구성할 수 있는 사전 구축된 데이터 원본 커넥터가 있습니다. + Amazon S3에서 데이터를 쿼리하려고 하고 이 페이지에서 Apache Hive 메타스토어 또는 다른 연동 쿼리 데이터 원본 옵션 중 하나를 사용하고 있지 않은 경우 **S3 - AWS Glue Data Catalog**를 선택합니다. Athena는 AWS Glue Data Catalog를 사용하여 Amazon S3의 데이터 원본에 대한 메타데이터 및 스키마 정보를 저장합니다. 이것은 기본(비연합) 옵션입니다. 자세한 내용은 [AWS Glue Data Catalog을 사용하여 데이터에 연결](data-sources-glue.md) 섹션을 참조하세요. 이 워크플로를 사용하는 단계는 [Athena에 데이터 카탈로그 등록 및 사용](gdc-register.md) 섹션을 참조하세요. + **S3 - Apache Hive 메타스토어(S3 - Apache Hive metastore)**를 선택하여 Apache Hive 메타스토어를 사용하는 Amazon S3의 데이터 집합을 쿼리합니다. 이 옵션에 대한 자세한 내용은 [Apache Hive 메타스토어에 Athena 연결](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md) 섹션을 참조하세요. + 에서 사용할 고유한 데이터 원본 커넥터를 생성하려면 **사용자 정의 또는 고유 데이터(Custom or shared data)**을 선택합니다. 데이터 원본 커넥터 작성에 대한 정보에 대한 자세한 내용은 [Athena Query Federation SDK를 사용하여 데이터 소스 커넥터 개발](connect-data-source-federation-sdk.md) 섹션을 참조하세요. 1. **다음**을 선택합니다. 1. **데이터 소스 세부 정보 입력** 페이지의 **데이터 소스 이름**에서 자동 생성된 이름을 사용하거나 Athena에서 데이터 소스를 쿼리할 때 SQL 문에 사용할 고유 이름을 입력합니다. 이름은 127자까지 입력할 수 있으며 계정 내에서 고유해야 합니다. 생성 후에는 변경할 수 없습니다. 유효한 문자는 a-z, A-Z, 0-9, \$1(밑줄), @(앰퍼샌드) 및 -(하이픈)입니다. `awsdatacatalog`, `hive`, `jmx`, `system` 이름은 Athena에 예약되어 있으므로 데이터 원본 이름에 사용할 수 없습니다. 1. 선택한 데이터 소스가 AWS Glue 연결과 통합되는 경우. 1. **AWS Glue 연결 세부 정보**에 필요한 정보를 입력합니다. 특정 데이터 소스에 연결하는 데 필요한 속성을 포함하는 연결입니다. 필요한 속성은 연결 유형에 따라 다릅니다. 커넥터와 관련된 속성에 대한 자세한 내용은 [사용 가능한 데이터 소스 커넥터](connectors-available.md) 섹션을 참조하세요. 추가 연결 속성에 대한 자세한 내용은 *AWS Glue 사용 설명서*의 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)을 참조하세요. **참고** Glue 연결 속성을 업데이트할 때 업데이트된 속성을 가져오려면 Lambda 커넥터를 다시 시작해야 합니다. 이렇게 하려면 환경 속성을 편집한 다음 실제로 아무 것도 변경하지 않은 상태로 저장합니다. Glue 연결을 업데이트하면 해당 Lambda 함수에서 다음 속성이 자동으로 업데이트되지 않습니다. 이러한 속성에 대해 Lambda 함수를 수동으로 업데이트해야 합니다. Lambda VPC 구성 – `security_group_ids`, `subnet_ids` Lambda 실행 역할 – `spill_bucket`, `secret_name`, `spill_kms_key_id` 1. **Lambda 실행 IAM 역할**의 경우 다음 중 하나를 선택합니다. + **새 실행 역할 생성 및 사용** - (기본값) Athena는 사용자를 대신하여 AWS Lambda의 리소스에 액세스하는 데 사용할 실행 역할을 생성합니다. Athena에서 페더레이션된 데이터 소스를 생성하려면 이 역할이 필요합니다. + **기존 실행 역할 사용** - 이 옵션을 사용하여 기존 실행 역할을 선택합니다. 이 옵션의 경우 **실행 역할** 드롭다운에서 사용하려는 실행 역할을 선택합니다. 1. 선택한 데이터 소스가 AWS Glue 연결과 통합되지 않는 경우. 1. **Lambda 함수**에 대해 **Lambda 함수 생성**을 선택합니다. 선택한 커넥터의 함수 페이지가 AWS Lambda 콘솔에서 열립니다. 이 페이지에는 커넥터에 대한 자세한 정보가 포함되어 있습니다. 1. **애플리케이션 설정(Application settings)**에서 각 애플리케이션 설정에 관한 설명을 신중히 읽은 다음 필요에 따라 값을 입력합니다. 표시되는 애플리케이션 설정은 데이터 원본의 커넥터에 따라 다릅니다. 최소한의 필수 설정은 다음과 같습니다. + **AthenaCatalogName** – `cloudwatchlogs`와 같이 대상으로 하는 데이터 원본을 나타내는 소문자로 된 Lambda 함수의 이름입니다. + **SpillBucket** – Lambda 함수 응답 크기 제한을 초과하는 데이터를 저장하기 위한 계정의 Amazon S3 버킷입니다. **참고** 유출된 데이터는 후속 실행에서 재사용되지 않으며 안전하게 삭제할 수 있습니다. Athena는 이 데이터를 삭제하지 않습니다. Amazon S3 유출 버킷에서 이전 데이터를 삭제하는 객체 수명 주기 정책을 추가하여 이러한 객체를 관리하는 것이 좋습니다. 자세한 내용은 Amazon S3 사용 설명서의 [스토리지 수명 주기 관리](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 참조하세요. 1. **이 앱이 사용자 지정 IAM 역할 및 리소스 정책을 생성하는 것을 확인(I acknowledge that this app creates custom IAM roles and resource policies)**을 선택합니다. 자세한 내용을 보려면 **정보** 링크를 선택하세요. 1. **배포(Deploy)**를 선택합니다. 배포가 완료되면 Lambda 콘솔의 **리소스** 섹션에 Lambda 함수가 나타납니다. 계정에 데이터 원본 커넥터를 배포한 후 Athena를 연결할 수 있습니다. 1. 콘솔의 **데이터 원본 입력(Enter data sources)** 페이지로 돌아갑니다. 1. **연결 세부 정보(Connection details)**섹션에서 **Lambda 함수 선택 또는 입력** 검색 상자 옆에 있는 새로 고침 아이콘을 선택합니다. 1. Lambda 콘솔에서 방금 생성한 함수의 이름을 선택합니다. Lambda 함수의 ARN이 표시됩니다. 1. (선택 사항) **태그(Tags)**에 대해 이 데이터 원본과 연결할 키-값 페어를 추가합니다. 태그에 대한 자세한 내용은 [Athena 리소스 태깅](tags.md) 섹션을 참조하세요. 1. **다음**을 선택합니다. 1. **검토 및 생성** 페이지에서 데이터 소스의 세부 정보를 검토합니다. 변경하려면 **편집**을 선택합니다. 1. **Athena가 계정에 리소스 생성**의 정보를 읽어보세요. 동의하는 경우 **Athena가 본인을 대신하여 리소스를 생성할 것임을 확인합니다**를 선택합니다. 1. **데이터 소스 생성**을 선택합니다. **Athena**가 다음과 같은 리소스를 대신 생성합니다. + Lambda 실행 IAM 역할 + AWS Glue 연결(데이터 소스가 AWS Glue 연결과 호환되는 경우에만 해당) + Lambda 함수 **데이터 원본 세부 정보(Data source details)** 페이지 섹션에는 새 커넥터에 대한 정보가 표시됩니다. 이제 쿼리에 커넥터를 사용할 수 있습니다. 쿼리에서 데이터 커넥터 사용에 대한 자세한 내용은 [페더레이션 쿼리 실행](running-federated-queries.md) 섹션을 참조하세요. # AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포 데이터 소스 커넥터를 배포하려면 AWS Glue 연결 대신 [AWS Serverless Application Repository](https://aws.amazon.com/serverless/serverlessrepo/)을 사용할 수 있습니다. **참고** 사용자 지정 커넥터가 있거나 이전 커넥터를 사용해야 하는 경우에만 SAR을 사용하는 것이 좋습니다. 그렇지 않은 경우 Athena 콘솔 사용을 권장합니다. AWS Serverless Application Repository로 사용할 커넥터를 찾고 커넥터에 필요한 파라미터를 제공한 다음 계정에 커넥터를 배포할 수 있습니다. 그런 다음 커넥터를 배포한 후 Athena 콘솔을 사용하여 Athena에서 데이터 원본을 사용할 수 있도록 합니다. ## 계정에 커넥터 배포 **AWS Serverless Application Repository을 사용하여 데이터 원본 커넥터를 계정에 배포하려면** 1. AWS Management Console에 로그인하고 **서버리스 앱 리포지토리**를 엽니다. 1. 탐색 창에서 **사용 가능한 애플리케이션**을 선택합니다. 1. **사용자 지정 IAM 역할 또는 리소스 정책을 만드는 앱 표시(Show apps that create custom IAM roles or resource policies)** 옵션을 선택합니다. 1. 검색 상자에 커넥터 이름을 입력합니다. 사전 구축된 Athena 데이터 커넥터의 목록은 [사용 가능한 데이터 소스 커넥터](connectors-available.md) 단원을 참조하세요. 1. 커넥터의 이름을 선택합니다. 커넥터를 선택하면 AWS Lambda 콘솔에서 Lambda 함수의 **애플리케이션 세부 정보(Application details)** 페이지가 열립니다. 1. 세부 정보 페이지 오른쪽의 **애플리케이션 설정(Application settings)**에서 필수 정보를 입력합니다. 최소 필수 설정은 다음과 같습니다. Athena에서 구축한 데이터 커넥터의 나머지 구성 가능한 옵션에 대한 자세한 내용은 GitHub의 [사용 가능한 커넥터](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors) 주제를 참조하세요. + **AthenaCatalogName** – `cloudwatchlogs`와 같이 대상으로 하는 데이터 원본을 나타내는 소문자로 된 Lambda 함수의 이름입니다. + **SpillBucket** – Lambda 함수 응답 크기 제한을 초과하는 대규모 응답 페이로드에서 데이터를 수신하도록 계정에 Amazon S3 버킷을 지정합니다. 1. **이 앱이 사용자 지정 IAM 역할 및 리소스 정책을 생성하는 것을 확인(I acknowledge that this app creates custom IAM roles and resource policies)**을 선택합니다. 자세한 내용을 보려면 **정보** 링크를 선택하세요. 1. **애플리케이션 설정(Application settings)** 섹션의 오른쪽 하단에서 **배포(Deploy)**를 선택합니다. 배포가 완료되면 Lambda 콘솔의 **리소스** 섹션에 Lambda 함수가 나타납니다. ## Athena에서 커넥터 사용 설정 콘솔을 사용하여 에서 데이터 원본을 사용할 수 있도록 합니다. ** 콘솔을 사용하여 에서 데이터 원본을 사용할 수 있도록 합니다.** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 **데이터 소스 생성**을 선택합니다. 1. **데이터 원본 선택**에서는 AWS Serverless Application Repository에서 커넥터를 생성한 데이터 원본을 선택합니다. 이 자습서에서는 **Amazon CloudWatch Logs**를 연합 데이터 원본으로 선택합니다. 1. **다음**을 선택합니다. 1. **데이터 원본 세부 정보 입력(Enter data source details)** 섹션의 **데이터 원본 이름(Data source name)**에 에서 데이터 원본을 쿼리할 때 SQL 문에 사용할 이름을 입력합니다(예: `CloudWatchLogs`). 이름은 127자까지 입력할 수 있으며 계정 내에서 고유해야 합니다. 생성 후에는 변경할 수 없습니다. 유효한 문자는 a-z, A-Z, 0-9, \$1(밑줄), @(앰퍼샌드) 및 -(하이픈)입니다. `awsdatacatalog`, `hive`, `jmx`, `system` 이름은 Athena에 예약되어 있으므로 데이터 원본 이름에 사용할 수 없습니다. 1. **연결 세부 정보** 섹션에서, **Lambda 함수 선택 또는 입력** 상자를 사용해 방금 만든 함수의 이름을 선택합니다. Lambda 함수의 ARN이 표시됩니다. 1. (선택 사항) **태그(Tags)**에 대해 이 데이터 원본과 연결할 키-값 페어를 추가합니다. 태그에 대한 자세한 내용은 [Athena 리소스 태깅](tags.md) 섹션을 참조하세요. 1. **다음**을 선택합니다. 1. **검토 및 생성** 페이지에서 데이터 원본 세부 정보를 검토한 다음 **데이터 원본 생성**을 선택합니다. 1. **데이터 원본 세부 정보(Data source details)** 페이지 섹션에는 새 커넥터에 대한 정보가 표시됩니다. 이제 쿼리에 커넥터를 사용할 수 있습니다. 쿼리에서 데이터 커넥터 사용에 대한 자세한 내용은 [페더레이션 쿼리 실행](running-federated-queries.md) 섹션을 참조하세요. # 데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성 일부 Athena 데이터 소스 커넥터 및 AWS Glue 연결은 VPC 및 보안 그룹이 필요합니다. 이 주제에서는 서브넷과 보안 그룹이 있는 VPC를 생성하는 방법을 보여줍니다. 이 과정의 일부로서 사용자가 생성하는 VPC, 서브넷, 보안 그룹에 대한 ID를 검색합니다. 이러한 ID는 Athena와 함께 사용하도록 AWS Glue 연결 또는 데이터 소스 커넥터를 구성할 때 필요합니다. **Athena 데이터 원본 커넥터에 대한 VPC를 생성하려면** 1. AWS Management Console에 로그인하고 [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)에서 Amazon VPC 콘솔을 엽니다. 1. **VPC 생성**을 선택합니다. 1. **VPC 생성** 페이지에서 **VPC 설정**의 **생성할 리소스**에서 **VPC 등**을 선택합니다. 1. **이름 태그 자동 생성**의 **자동 생성**에 VPC의 모든 리소스에 대한 이름 태그를 생성하는 데 사용할 값을 입력합니다. 1. **VPC 생성**을 선택합니다. 1. 프로세스가 완료되면 **VPC 보기**를 선택합니다. 1. **세부 정보(Details)** 섹션의 **VPC ID**에서 나중에 참조할 수 있도록 VPC ID를 복사합니다. 이제 방금 생성한 VPC의 서브넷 ID를 검색할 준비가 되었습니다. **VPC 서브넷 ID를 검색하려면** 1. VPC 콘솔 탐색 창에서 **서브넷(Subnets)**을 선택합니다. 1. **VPC** 열에 기록해 둔 VPC ID가 있는 서브넷의 이름을 선택합니다. 1. **세부 정보(Details)** 섹션의 **서브넷 ID(Subnet ID)**에서 나중에 참조할 수 있도록 서브넷 ID를 복사합니다. 다음으로 VPC의 보안 그룹을 생성합니다. **VPC의 보안 그룹을 생성하려면** 1. VPC 콘솔 탐색 창에서 **보안(Security)**, **보안 그룹(Security Groups)**을 선택합니다. 1. **보안 그룹 생성**을 선택합니다. 1. **보안 그룹 생성(Create security group)** 페이지에서 다음 정보를 입력합니다. + **보안 그룹 이름(Security group name)**에 보안 그룹의 이름을 입력합니다. + **설명(Description)**에 보안 그룹의 설명을 입력합니다. 설명이 필요합니다. + **VPC**에서 데이터 소스 커넥터에 대해 생성한 VPC의 VPC ID를 선택합니다. + **인바운드 규칙(Inbound rules)** 및 **아웃바운드 규칙(Outbound rules)**에 필요한 인바운드 및 아웃바운드 규칙을 추가합니다. 1. **보안 그룹 생성**을 선택합니다. 1. 보안 그룹의 **세부 정보(Details)** 페이지에서 나중에 참조할 수 있도록 **보안 그룹 ID(Security group ID)**를 복사합니다. ## VPC에서 Athena 커넥터를 사용하기 위한 중요 고려 사항 모든 커넥터가 VPC를 사용할 수 있으므로 다음 지침은 모든 Athena 커넥터에 적용됩니다. **참고** VPC에서 AWS Glue 연결을 사용하는 경우 다음 PrivateLink 엔드포인트를 설정해야 합니다. Amazon S3 AWS Glue AWS Secrets Manager 또한 퍼블릭 인터넷 액세스를 사용할 수 있습니다. 하지만 보안상의 이유로 권장하지는 않습니다. **주의** 퍼블릭 인터넷 액세스를 사용하면 리소스가 추가 보안 위험에 노출될 수 있습니다. VPC 구성에서 보안 강화를 위해 PrivateLink 엔드포인트를 사용하는 것이 좋습니다. # AWS 계정으로 ECR 이미지 가져오기 Athena 페더레이션 커넥터 Lambda 함수는 Athena 관리형 Amazon ECR 리포지토리에 저장된 컨테이너 이미지를 사용합니다. 이러한 컨테이너 이미지에서 보안 스캔을 수행하려면 먼저 해당 이미지를 계정의 Amazon ECR 리포지토리에 복사해야 합니다. 이 섹션에서는 이미지를 리포지토리에 복사하고 해당 이미지를 사용하도록 Lambda 함수를 구성하는 방법에 대한 단계별 지침을 제공합니다. ## 사전 조건 + Athena 페더레이션 커넥터 - 컨테이너 이미지를 사용하는 경우 모든 소스를 통해 커넥터를 생성할 수 있습니다. **참고** 이미지 배포를 확인하려면 Athena 페더레이션 커넥터 Lambda의 이미지 탭을 확인하세요. + Docker 설치 및 실행 중 + AWS CLI 설치 + 적절한 풀 권한이 있는 계정 자격 증명 ## 이미지를 전송하는 방법 1. Athena 페더레이션 커넥터 Lambda에서 이미지 URI 찾기 **Example** ``` account_id_1.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.15.1 ``` 1. Athena 관리형 계정을 위한 Docker 인증 토큰을 생성합니다. ``` aws ecr get-login-password --region regionID | docker login --username AWS --password-stdin athena-managed-registry ``` 위치: + *regionID*는 배포 리전입니다(예: us-east-1). + *athena-managed-registry*는 이미지 URI의 레지스트리 부분입니다(예: account\$1id\$11.dkr.ecr.us-east-1.amazonaws.com). 1. Athena 관리형 계정에서 이미지를 가져옵니다. ``` docker pull athenaImageURI ``` 1. 레지스트리에 Docker를 인증합니다. ``` aws ecr get-login-password --region regionID | docker login --username AWS --password-stdin customer-registry ``` 여기서 *customer-registry*는 ECR 레지스트리(예: account\$1id\$12.dkr.ecr.us-east-1.amazonaws.com)입니다. 1. 가져온 이미지에 리포지토리 태그를 지정합니다. ``` docker tag athenaImageURI yourImageURI ``` 1. 리포지토리에 이미지를 푸시합니다. ``` docker push yourImageURI ``` 1. Athena 페더레이션 커넥터를 업데이트합니다. 1. Lambda 함수로 이동합니다. 1. **새 이미지 배포**를 선택합니다. 1. 새 이미지 URI를 입력합니다. 이제 Athena 페더레이션 커넥터 이미지가 계정에 있으므로 이미지에서 CVE 스캔을 수행할 수 있습니다. # 연결을 Glue 데이터 카탈로그로 등록 데이터 소스를 생성한 후 Athena 콘솔을 사용하여 연결을 Glue 데이터 카탈로그로 등록할 수 있습니다. 등록되면 Lake Formation을 사용하여 페더레이션된 데이터 카탈로그를 관리하고 세분화된 액세스 제어를 활성화할 수 있습니다. 자세한 내용은 [페더레이션된 카탈로그 생성](https://docs.aws.amazon.com/lake-formation/latest/dg/create-fed-catalog-data-source.html)을 참조하세요. 다음 커넥터를 등록하여 AWS Glue와 통합하고 세분화된 액세스 제어를 수행할 수 있습니다. + Redshift + BigQuery + DynamoDB(미리 보기) + Snowflake(미리 보기) + MySQL + PostgreSQL + AWS CMDB + Timestream + Azure Data Lake Storage + Azure Synapse + IBM DB2 + IBM Db2 AS/400(Db2 iSeries) + DocumentDB + Google Cloud Storage + HBase + OpenSearch + Oracle + SAP HANA + SQL Server + TPC-DS + Cloudera Hive + Cloudwatch + CloudWatch 지표 + Teradata + Vertica ## 사전 조건 시작하기 전에 다음과 같은 사전 조건을 완료해야 합니다. + 위치를 등록하는 데 필요한 역할과 권한이 있는지 확인합니다. 자세한 내용은 AWS Lake Formation 개발자 안내서의 [역할에 대한 요구 사항](https://docs.aws.amazon.com/lake-formation/latest/dg/registration-role.html)을 참조하세요. + 필요한 Lake Formation 역할이 있는지 확인합니다. 자세한 내용은 AWS Lake Formation 개발자 안내서의 [데이터 카탈로그를 외부 데이터 소스에 연결하기 위한 사전 조건](https://docs.aws.amazon.com/lake-formation/latest/dg/federated-catalog-data-connection.html)을 참조하세요. + Glue에 등록하는 역할에는 다음 예제에 나열된 권한이 있어야 합니다. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/spill-prefix/*", "arn:aws:s3:::amzn-s3-demo-bucket/spill-prefix" ] }, { "Sid": "lambdainvoke", "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-1:111122223333:function:lambda_function_name" }, { "Sid": "gluepolicy", "Effect": "Allow", "Action": "glue:*", "Resource": [ "arn:aws:glue:us-east-1:111122223333:connection/", "arn:aws:glue:us-east-1:111122223333:catalog" ] } ] } ``` ------ + 적절한 데이터 액세스를 결정하고 관리할 책임은 사용자에게 있습니다. 페더레이션 쿼리에 대한 세분화된 액세스 제어를 통해 [AmazonAthenaFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html) 관리형 정책을 사용하는 것이 좋습니다. 자체 정책을 사용하려면 페더레이션 쿼리를 실행하는 사용자가 다음 리소스에 액세스할 수 없게 해야 합니다. + Glue 연결에 지정된 Lambda 커넥터의 `lambda:InvokeFunction` + IAM의 유출 버킷 위치 액세스 + 페더레이션 카탈로그와 연결된 Glue 연결에 대한 액세스 + IAM의 Lake Formation 역할 ## 콘솔을 사용하여 연결 등록 **연결을 Glue 데이터 카탈로그로 등록하려면** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스** 목록에서 생성한 데이터 소스를 선택하여 **데이터 소스 세부 정보** 페이지를 엽니다. 1. **Get started with AWS Lake Formation(SES 시작하기)**를 선택합니다. **참고** 이 옵션을 선택한 후에는 Lambda 함수를 직접 관리해야 합니다. Athena는 Lambda 함수를 삭제하지 않습니다. 1. **데이터 카탈로그 이름**에 카탈로그의 고유한 이름을 입력합니다. 1. Lake Formation에 Lambda 함수를 호출할 권한을 부여하는 **Lake Formation IAM 역할**을 선택합니다. 역할에 [예시](#register-connection-as-gdc-pre)에 표시된 것과 같은 권한이 있는지 확인합니다. 1. 텍스트 상자에 **확인**을 입력하여 Athena 데이터 소스를 삭제하고 Glue 데이터 카탈로그 등록으로 바꿉니다. **참고** 이 작업을 수행하면 Athena 데이터 소스가 삭제되고 해당 위치에 새 Glue 데이터 카탈로그가 생성됩니다. 이 프로세스가 완료되면 데이터 소스에 액세스하는 쿼리를 업데이트하여 새로 생성된 Glue 데이터 카탈로그를 대신 참조해야 할 수 있습니다. 1. **카탈로그 생성을 선택하고 Lake Formation으로 이동**합니다. 그러면 카탈로그를 관리하고 카탈로그, 데이터베이스, 테이블의 사용자에게 권한을 부여할 수 있는 Lake Formation 콘솔이 열립니다. # 교차 계정 페더레이션 쿼리 활성화 연합 쿼리를 사용하면 AWS Lambda에 배포된 데이터 원본 커넥터를 사용하여 Amazon S3 이외의 데이터 원본을 쿼리할 수 있습니다. 교차 계정 연합 쿼리 기능을 사용하면 Lambda 함수와 쿼리할 데이터 원본이 다른 계정에 위치하도록 할 수 있습니다. **참고** AWS Glue Data Catalog에 페더레이션 데이터 소스를 등록하지 않은 경우에만 이 방법을 사용합니다. AWS Glue Data Catalog에 데이터 소스를 등록한 경우 AWS Glue Data Catalog 교차 계정 기능 및 권한 모델을 사용합니다. 자세한 내용은 *AWS Glue 사용 설명서*의 [교차 계정 액세스 권한 부여](https://docs.aws.amazon.com/glue/latest/dg/cross-account-access.html)를 참조하세요. 데이터 관리자는 데이터 커넥터를 데이터 분석가의 계정과 공유하거나 데이터 분석가로서 데이터 관리자의 공유 Lambda ARN을 사용하여 계정에 추가하여 교차 계정 연동 쿼리를 활성화할 수 있습니다. 원래 계정의 커넥터에 대한 구성이 변경되면 업데이트된 구성이 다른 사용자 계정에 있는 커넥터의 공유 인스턴스에 자동으로 적용됩니다. ## 고려 사항 및 제한 사항 + 교차 계정 연동 쿼리 기능은 Lambda 기반 데이터 원본을 사용하는 비 Hive 메타스토어 데이터 커넥터에 사용할 수 있습니다. + AWS Glue Data Catalog 데이터 원본 유형에 대해 해당 기능을 사용할 수 없습니다. AWS Glue Data Catalog에 대한 교차 계정 액세스에 관한 자세한 내용은 [AWS Glue 데이터 카탈로그에 대한 크로스 계정 액세스 구성](security-iam-cross-account-glue-catalog-access.md) 섹션을 참조하세요. + 커넥터의 Lambda 함수에서 얻은 응답이 Lambda 응답 크기 제한(6MB)을 초과하는 경우 Athena는 자동으로 응답을 암호화하고 일괄 처리한 후 사용자가 구성한 Amazon S3 버킷으로 유출합니다. Athena 쿼리를 실행하는 엔터티가 유출 위치에 대한 액세스 권한을 보유해야 Athena에서 유출한 데이터를 읽을 수 있습니다. 쿼리를 완료한 후에는 데이터가 필요하지 않으므로 유출 위치에서 객체를 삭제하도록 Amazon S3 수명 주기 정책을 설정하는 것이 좋습니다. + AWS 리전에서 페더레이션된 쿼리 사용은 지원되지 않습니다. ## 필수 권한 필요한 권한을 설정하려면 계정 A(*444455556666*)와 계정 B(*111122223333*) 모두에서 작업을 수행해야 합니다. ### 계정 A에 대한 작업 데이터 관리자 계정 A가 데이터 분석가 계정 B와 Lambda 함수를 공유하려면 계정 B에서 Lambda가 함수 및 유출 버킷 액세스를 호출해야 합니다. 따라서 계정 A는 [리소스 기반 정책](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)을 Lambda 함수에 추가하고 [보안 주체](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html) 액세스 권한을 Amazon S3 유출 버킷에 추가해야 합니다. 1. 다음 정책은 Lambda가 계정 A의 Lambda 함수에서 계정 B에 대한 함수 호출 권한을 부여합니다. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "CrossAccountInvocationStatement", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:user/username" ] }, "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-1:444455556666:function:lambda-function-name" } ] } ``` ------ 1. 다음 정책은 계정 B의 보안 주체에 대한 유출 버킷 액세스를 허용합니다. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": ["arn:aws:iam::111122223333:user/username"] }, "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::spill-bucket", "arn:aws:s3:::spill-bucket/*" ] } ] } ``` ------ 1. Lambda 함수가 퍼더레이션 SDK가 제공하는 기본 암호화 대신에 AWS KMS 키를 통해 유출 버킷을 암호화하려면 다음 예와 같이 계정 A의 AWS KMS 키 정책은 계정 B의 사용자에게 액세스 권한을 부여해야 합니다. ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": { "AWS": ["arn:aws:iam::account-B-id:user/username"] }, "Action": [ "kms:Decrypt" ], "Resource": "*" // Resource policy that gets placed on the KMS key. } ``` ### 계정 B에 대한 작업 계정 A가 해당 커넥터를 계정 B와 공유하려면 계정 B는 계정 A가 AWS Security Token Service [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API 작업을 호출함으로써 권한을 맡는 `AthenaCrossAccountCreate-account-A-id`라는 역할을 생성해야 합니다. 1. IAM 콘솔 또는 AWS CLI를 사용하여 `AthenaCrossAccountCreate-account-A-id` 역할을 사용자 지정 신뢰 정책 역할로 생성합니다. 사용자 지정 신뢰 정책은 액세스를 위임하고 다른 사람이 AWS 계정에서 작업을 수행하도록 허용합니다. 자세한 단계는 *IAM 사용 설명서*에서 [사용자 지정 신뢰 정책을 사용한 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)을 참조하세요. 신뢰 관계에는 다음 예와 같이 키가 `AWS`이고 값이 계정 A의 ARN인 위탁자 객체가 있어야 합니다. ``` ... "Principal": { "AWS": ["arn:aws:iam::account-A-id:user/username"] }, ... ``` 1. 또한 계정 B에서 `CreateDataCatalog` 작업을 허용하는 다음 정책을 생성합니다. ``` { "Effect": "Allow", "Action": "athena:CreateDataCatalog", "Resource": "arn:aws:athena:*:account-B-id:datacatalog/*" } ``` 1. 계정 B를 사용하여 생성한 `AthenaCrossAccountCreate-account-A-id` 역할에 `CreateDataCatalog` 작업을 허용하는 정책을 추가합니다. ## 계정 A의 데이터 원본을 계정 B와 공유 사용 권한이 설정된 후에는 Athena 콘솔의 **데이터 소스 및 카탈로그** 페이지를 사용하여 사용자 계정(계정 A)의 데이터 커넥터를 다른 계정(계정 B)과 연결할 수 있습니다. 계정 A는 커넥터의 모든 제어 및 소유권을 유지합니다. 계정 A가 커넥터에 대한 구성을 변경하면 업데이트된 구성이 계정 B의 공유 커넥터에 적용됩니다. **참고** Lambda 유형 데이터 소스만 공유할 수 있으며 AWS Glue 연결을 사용하는 데이터 소스는 공유할 수 없습니다. 자세한 내용은 [사용 가능한 데이터 소스 커넥터](connectors-available.md) 섹션을 참조하세요. **계정 B와 계정 A의 Lambda 데이터 원본 공유** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 공유할 커넥터의 링크를 선택합니다. 1. Lambda 데이터 원본에 대한 세부 정보 페이지에서 오른쪽 상단 모서리에 있는 **작업(Actions)** 메뉴에서 **공유(Share)**를 선택합니다. 1. **다른 계정과 *Lambda-name*을 공유하시겠습니까?(Share Lambda-name with another account?)** 대화 상자에 필수 정보를 입력합니다. + **데이터 원본 이름(Data source name)**에서 복사된 데이터 원본의 이름을 다른 계정에 표시하려는 대로 입력합니다. + **계정 ID(Account ID)**에서 데이터 원본을 공유할 계정의 ID(이 경우 계정 B)를 입력합니다. 1. **공유**를 선택합니다. 지정한 공유 데이터 커넥터가 계정 B에 생성됩니다. 계정 A의 커넥터에 대한 구성 변경 사항은 계정 B의 커넥터에 적용됩니다. ## 계정 A에서 계정 B로 공유 데이터 원본 추가 데이터 분석가는 데이터 관리자로부터 계정에 추가할 커넥터의 ARN을 제공받을 수 있습니다. 관리자가 제공한 Lambda ARN을 계정에 추가하려면 Athena 콘솔의 **데이터 소스 및 카탈로그** 페이지를 사용합니다. **계정에 공유 데이터 커넥터의 Lambda ARN 추가** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. 1. **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 **데이터 소스 생성**을 선택합니다. 1. **데이터 소스 선택** 페이지에서 **사용자 지정 또는 공유 커넥터**를 선택합니다. 1. **다음**을 선택합니다. 1. **데이터 소스 세부 정보 입력** 페이지의 **연결 세부 정보** 섹션에서 **Lambda 함수 선택 또는 입력**에 계정 A의 Lambda ARN을 입력합니다. 1. **다음**을 선택합니다. 1. **검토 및 생성** 페이지에서 **데이터 소스 생성**을 선택합니다. ## 문제 해결 계정 A에 계정 B에서 역할을 부여할 권한이 없다는 오류 메시지가 나타나면 계정 B에서 생성한 역할 이름의 철자가 올바른지, 올바른 정책이 연결되어 있는지 확인합니다. # 데이터 소스 커넥터 업데이트 Athena는 사용하는 데이터 소스 커넥터를 최신 버전으로 주기적으로 업데이트하여 새로운 기능과 향상된 기능을 활용하도록 권장합니다. 데이터 소스 커넥터 업데이트에는 다음 단계가 포함됩니다. # Glue 연결(권장) ## 최신 Athena Query Federation 버전 찾기 Athena 데이터 소스 커넥터의 최신 버전 번호는 최신 Athena Query Federation 버전에 해당됩니다. 경우에 따라 GitHub 릴리스가 AWS Serverless Application Repository(SAR)에서 제공되는 것보다 조금 더 최신일 수 있습니다. **최신 Athena Query Federation 버전 번호를 찾으려면** 1. GitHub URL [https://github.com/awslabs/aws-athena-query-federation/releases/latest](https://github.com/awslabs/aws-athena-query-federation/releases/latest)를 방문하세요. 1. 기본 페이지 제목의 릴리스 번호를 다음 형식으로 기록합니다. **Athena Query Federation의** **릴리스 v***year*.*week\$1of\$1year*.*iteration\$1of\$1week* 예를 들어 **Athena Query Federation의 릴리스 v2023.8.3**의 릴리스 번호는 2023.8.3입니다. ## 커넥터 버전 찾기 다음 단계에 따라 현재 사용 중인 커넥터의 버전을 확인합니다. **커넥터 버전을 찾으려면** 1. Lambda 애플리케이션의 Lambda 콘솔 페이지에서 **이미지** 탭을 선택합니다. 1. 이미지 탭에서 이미지 URI를 찾습니다. URI는 다음 형식을 따릅니다. ``` Image_location_account.dkr.ecr.us-west-2.amazonaws.com/athena-federation-repository:Version ``` 1. 이미지 URI의 버전 번호는 `year.week_of_year.iteration_of_week` 형식(예: `2021.42.1`)을 따릅니다. 이 숫자는 커넥터 버전을 나타냅니다. ## 새 커넥터 버전 배포 다음 단계에 따라 커넥터의 새 버전을 배포합니다. **새 커넥터 버전을 배포하려면** 1. 최신 Athena Query Federation 버전 찾기 절차에 따라 원하는 버전을 찾습니다. 1. 페더레이션 커넥터 Lambda 함수에서 ImageURI를 찾고 태그를 원하는 버전으로 업데이트합니다. 예제: 시작: ``` 509399631660.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.15.1 ``` 끝: ``` 509399631660.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.26.1 ``` **참고** 현재 버전이 2025.15.1 이전 버전인 경우 다음과 같은 중요한 변경 사항에 유의하세요. 리포지토리 이름이 `athena-federation-repository`로 업데이트되었습니다. 이 업데이트 이전의 버전에서는 명령 재정의가 설정되지 않을 수 있습니다. 복합 핸들러로 설정해야 합니다. # 레거시 연결 ## 최신 Athena Query Federation 버전 찾기 Athena 데이터 소스 커넥터의 최신 버전 번호는 최신 Athena Query Federation 버전에 해당됩니다. 경우에 따라 GitHub 릴리스가 AWS Serverless Application Repository(SAR)에서 제공되는 것보다 조금 더 최신일 수 있습니다. **최신 Athena Query Federation 버전 번호를 찾으려면** 1. GitHub URL [https://github.com/awslabs/aws-athena-query-federation/releases/latest](https://github.com/awslabs/aws-athena-query-federation/releases/latest)를 방문하세요. 1. 기본 페이지 제목의 릴리스 번호를 다음 형식으로 기록합니다. **Athena Query Federation의** **릴리스 v***year*.*week\$1of\$1year*.*iteration\$1of\$1week* 예를 들어 **Athena Query Federation의 릴리스 v2023.8.3**의 릴리스 번호는 2023.8.3입니다. ## 리소스 이름 찾기 업그레이드를 준비하려면 다음 정보를 찾아 기록해야 합니다. 1. 커넥터의 Lambda 함수 이름. 1. Lambda 함수 환경 변수. 1. 커넥터의 Lambda 함수를 관리하는 Lambda 애플리케이션 이름. **Athena 콘솔에서 리소스 이름을 찾으려면** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 이름** 열에서 커넥터의 데이터 소스에 대한 링크를 선택합니다. 1. **데이터 소스 세부 정보** 섹션의 **Lambda 함수**에서 Lambda 함수에 대한 링크를 선택합니다. ![\[Lambda 함수에 대한 링크를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-updating-1.png) 1. **함수** 페이지의 **함수 이름** 열에서 커넥터의 함수 이름을 기록합니다. ![\[함수 이름을 기록합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-updating-2.png) 1. 함수 이름 링크를 선택합니다. 1. **함수 개요** 섹션에서 **구성** 탭을 선택합니다. 1. 왼쪽의 창에서 **환경 변수**를 선택합니다. 1. **환경 변수** 섹션에서 키와 해당 값을 기록합니다. 1. 페이지 맨 위로 스크롤합니다. 1. **이 함수는 애플리케이션에 속해 있습니다. 관리하려면 여기를 클릭합니다.** 메시지에서 **여기를 클릭** 링크를 선택합니다. 1. **serverlessrepo-*your\$1application\$1name*** 페이지에서 **serverlessrepo**를 제외한 애플리케이션 이름을 기록합니다. 예를 들어 애플리케이션 이름이 **serverlessrepo-DynamoDbTestApp**인 경우 사용자 애플리케이션 이름은 **DynamoDbTestApp**입니다. 1. 애플리케이션의 Lambda 콘솔 페이지에서 **사용 중인 커넥터 버전 찾기** 단계를 계속 진행합니다. ## 사용 중인 커넥터의 버전 찾기 다음 단계에 따라 사용 중인 커넥터 버전을 찾습니다. **사용 중인 커넥터 버전을 찾으려면** 1. Lambda 애플리케이션의 Lambda 콘솔 페이지에서 **배포** 탭을 선택합니다. 1. **배포** 탭에서 **SAM 템플릿**을 확장합니다. 1. **CodeUri**를 검색합니다. 1. **키** 필드의 **CodeUri**에서 다음 문자열을 찾습니다. ``` applications-connector_name-versions-year.week_of_year.iteration_of_week/hash_number ``` 다음 예제는 CloudWatch 커넥터의 문자열을 보여줍니다. ``` applications-AthenaCloudwatchConnector-versions-2021.42.1/15151159... ``` 1. *year*.*week\$1of\$1year*.*iteration\$1of\$1week*에 대한 값(예: **2021.42.1**)을 기록합니다. 이 버전은 커넥터의 버전입니다. ## 커넥터의 새 버전 배포 다음 단계에 따라 커넥터의 새 버전을 배포합니다. **커넥터의 새 버전을 배포하려면** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 **데이터 소스 생성**을 선택합니다. 1. 업그레이드할 데이터 소스를 선택하고 **다음**을 선택합니다. 1. **연결 세부 정보** 섹션에서 **Lambda 함수 생성**을 선택합니다. 그러면 업데이트된 애플리케이션을 배포할 수 있는 Lambda 콘솔이 열립니다. ![\[AWS Lambda 콘솔의 커넥터 페이지.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-updating-3.png) 1. 실제로 새 데이터 소스를 생성하지는 않으므로 Athena 콘솔 탭을 닫아도 됩니다. 1. 커넥터의 Lambda 콘솔 페이지에서 다음 단계를 수행합니다. 1. 애플리케이션 이름에서 **serverlessrepo-** 접두사를 제거했는지 확인하고 애플리케이션 이름을 **애플리케이션 이름** 필드에 복사합니다. 1. Lambda 함수 이름을 **AthenaCatalogName** 필드에 복사합니다. 일부 커넥터에서 이 필드는 **LambdaFunctionName**으로 표시됩니다. 1. 기록했던 환경 변수를 해당 필드에 복사합니다. 1. **I acknowledge that this app creates custom IAM roles and resource policies** 옵션을 선택하고 **배포**를 선택합니다. 1. 애플리케이션이 업데이트되었는지 확인하려면 **배포** 탭을 선택합니다. **배포 기록** 섹션에서 업데이트가 완료되었음을 표시합니다. ![\[커넥터 업데이트가 완료되었습니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-updating-4.png) 1. 새 버전 번호를 확인하려면 전과 같이 **SAM 템플릿**을 확장하고 **CodeUri**를 찾은 후에 **키** 필드에서 커넥터 버전 번호를 확인할 수 있습니다. 이제 업데이트된 커넥터를 사용하여 Athena의 페더레이션된 쿼리를 생성할 수 있습니다. # 데이터 소스 연결 편집 또는 삭제 Athena 콘솔을 사용하여 기존 연결에 대한 설명, 호스트, 포트, 데이터베이스 및 기타 속성을 업데이트할 수 있습니다. Athena 콘솔에서 데이터 소스를 삭제할 수도 있습니다. ## 데이터 소스 연결 편집 **데이터 소스 연결을 편집하려면** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 편집할 데이터 소스 연결을 선택합니다. 1. **AWS Glue 연결 세부 정보**에서 **편집**을 선택합니다. 1. **다음**을 선택합니다. 1. ** 편집** 페이지에서 필요에 따라 정보를 업데이트합니다. 사용 가능한 속성은 연결 유형에 따라 다릅니다. **참고** 보안 암호, 유출 위치 또는 AWS KMS 키 ID에 대한 연결 속성을 업데이트할 때 Lambda 실행 역할이 업데이트된 리소스에 여전히 액세스할 수 있는지 확인합니다. 자세한 내용은 AWS Lambda 개발자 안내서의 [실행 역할에서 권한 보기 및 업데이트](https://docs.aws.amazon.com/lambda/latest/dg/permissions-executionrole-update.html)를 참조하세요. + **설명** - 연결에 대한 설명을 편집합니다. + **호스트** - 데이터베이스의 호스트 이름을 편집합니다. + **포트** - 데이터베이스의 포트 번호를 편집합니다. + **데이터베이스** - 데이터베이스의 이름을 편집합니다. + **JDBC 파라미터** - 연결에 필요한 추가 JDBC 파라미터를 편집합니다. + **보안 암호** - AWS Secrets Manager에서 보안 암호를 선택하거나 생성합니다. AWS 보안 암호를 사용하여 JDBC 연결 문자열에서 민감한 정보를 하드코딩하지 않게 합니다. 자세한 내용은 [AWS Secrets Manager란 무엇입니까?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)를 참조하세요. Secrets Manager에서 보안 암호를 생성하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [AWS Secrets Manager 보안 암호 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)을 참조하세요. Athena 페더레이션 쿼리에서 AWS Secrets Manager 기능을 사용하려면 Secrets Manager에 대해 Amazon VPC 프라이빗 엔드포인트를 구성해야 합니다. 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [Secrets Manager VPC 프라이빗 엔드포인트 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)을 참조하세요. + **Amazon S3의 유출 위치** - 계정에서 Amazon S3 버킷 위치를 선택하거나 생성하여 Lambda 함수 응답 크기 제한을 초과하는 데이터를 저장합니다. **참고** 유출된 데이터는 후속 실행에서 재사용되지 않으며 12시간 후에 안전하게 삭제할 수 있습니다. Athena는 이 데이터를 삭제하지 않습니다. Amazon S3 유출 버킷에서 이전 데이터를 삭제하는 객체 수명 주기 정책을 추가하여 이러한 객체를 관리하는 것이 좋습니다. 자세한 내용은 *Amazon S3 사용 설명서*의 [스토리지 수명 주기 관리](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)를 참조하세요. + **S3의 쿼리 결과 암호화** - 다음 중 하나를 선택합니다. + (기본값) **임의로 생성된 키 사용** – Amazon S3로 유출된 데이터는 AES-GCM 인증 암호화 모드와 임의로 생성된 키를 사용하여 암호화됩니다. + **AWS KMS 키 사용** - 더 강력하고 AWS KMS 생성 암호화 키를 선택하거나 생성합니다. 자세한 정보는 *AWS Key Management Service 개발자 안내서*의 [키 생성](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)을 참조하세요. + **끄기** - 유출 데이터를 암호화하지 마세요. + **네트워킹 설정** - 일부 연결에는 가상 프라이빗 클라우드(VPC)가 필요합니다. 액세스하려는 데이터 스토어, 서브넷 및 하나 이상의 보안 그룹이 있는 VPC를 선택하거나 생성합니다. 자세한 내용은 [데이터 소스 커넥터 또는 AWS Glue 연결용 VPC 생성](athena-connectors-vpc-creation.md) 섹션을 참조하세요. **참고** 보안 암호, 유출 위치 또는 AWS KMS 키 ID와 같은 리소스의 연결 속성을 업데이트한 후 Lambda 실행 역할이 업데이트된 리소스에 계속 액세스할 수 있는지 확인합니다. 연결에 대한 네트워크 설정을 업데이트한 후 연결이 데이터 소스와 호환되도록 동일한 설정으로 Lambda 함수를 업데이트해야 합니다. 추가 연결 속성에 대한 자세한 내용은 *AWS Glue 사용 설명서*의 [AWS Glue 연결 속성](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html) 또는 *Amazon Athena 사용 설명서*의 [사용 가능한 데이터 소스 커넥터](connectors-available.md) 섹션을 참조하세요. 1. **저장**을 선택합니다. 데이터 소스 페이지의 **AWS Glue 연결 세부** 정보 섹션에는 커넥터에 대한 업데이트된 정보가 표시됩니다. ## 데이터 소스 삭제 데이터 소스를 삭제하면 Athena 데이터 소스만 삭제되고 Glue 연결, IAM 실행 역할, Lambda 함수와 같은 리소스는 삭제되지 않습니다. **데이터 소스를 삭제하기** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 삭제할 데이터 소스를 선택합니다. 1. **삭제**를 선택합니다. 1. **데이터 소스 삭제** 페이지에서 *확인*을 입력하여 삭제를 확인하고 **삭제**를 선택합니다. 데이터 소스 삭제가 완료되기까지 시간이 걸릴 수 있습니다. 데이터 소스가 삭제되면 성공 알림이 표시됩니다. # 페더레이션 쿼리 실행 하나 이상의 데이터 커넥터를 구성하여 계정에 배포한 후 Athena 쿼리에 사용할 수 있습니다. ## 단일 데이터 소스 쿼리 이 섹션의 예제에서는 [Amazon Athena CloudWatch 커넥터](connectors-cloudwatch.md)를 구성하여 계정에 배포했다고 가정합니다. 다른 커넥터를 사용할 때 동일한 방법을 사용하여 쿼리합니다. **CloudWatch 커넥터를 사용하는 Athena 쿼리를 생성하려면** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. Athena 쿼리 편집기에서 `FROM` 절에 다음 구문을 사용하는 SQL 쿼리를 생성합니다. ``` MyCloudwatchCatalog.database_name.table_name ``` ### 예제 다음 예제에서는 Athena CloudWatch 커넥터를 사용하여 `/var/ecommerce-engine/order-processor` CloudWatch Logs [로그 그룹](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)의 `all_log_streams` 뷰에 연결합니다. `all_log_streams` 뷰는 로그 그룹에 있는 모든 로그 스트림의 뷰입니다. 예제 쿼리는 반환되는 행 수를 100으로 제한합니다. ``` SELECT * FROM "MyCloudwatchCatalog"."/var/ecommerce-engine/order-processor".all_log_streams LIMIT 100; ``` 다음 예제에서는 이전 예제와 동일한 뷰에서 정보를 구문 분석합니다. 이 예제에서는 주문 ID와 로그 수준을 추출하고 `INFO` 수준이 있는 메시지를 필터링합니다. ``` SELECT log_stream as ec2_instance, Regexp_extract(message '.*orderId=(\d+) .*', 1) AS orderId, message AS order_processor_log, Regexp_extract(message, '(.*):.*', 1) AS log_level FROM MyCloudwatchCatalog."/var/ecommerce-engine/order-processor".all_log_streams WHERE Regexp_extract(message, '(.*):.*', 1) != 'INFO' ``` ## 여러 데이터 소스 쿼리 좀 더 복잡한 예제로 다음 데이터 소스를 사용하여 고객 구매와 관련된 데이터를 저장하는 전자 상거래 회사를 가정합니다. + [Amazon RDS for MySQL](https://aws.amazon.com/rds/mysql/): 제품 카탈로그 데이터 저장용 + [Amazon DocumentDB](https://aws.amazon.com/documentdb/): 이메일 주소 및 배송 주소와 같은 고객 계정 데이터 저장용 + [Amazon DynamoDB](https://aws.amazon.com/dynamodb/): 주문 배송 및 추적 데이터 저장용 이 전자 상거래 애플리케이션의 데이터 분석가가 일부 지역의 배송 시간이 현지 기상 조건의 영향을 받았다는 사실을 알게 되었다고 가정합니다. 분석가는 지연된 주문 건수, 영향을 받는 고객의 위치, 영향을 가장 많이 받는 제품을 파악하려고 합니다. 분석가는 정보 소스를 개별적으로 조사하는 대신 Athena를 사용하여 하나의 페더레이션된 쿼리에서 데이터를 결합합니다. **Example** ``` SELECT t2.product_name AS product, t2.product_category AS category, t3.customer_region AS region, count(t1.order_id) AS impacted_orders FROM my_dynamodb.default.orders t1 JOIN my_mysql.products.catalog t2 ON t1.product_id = t2.product_id JOIN my_documentdb.default.customers t3 ON t1.customer_id = t3.customer_id WHERE t1.order_status = 'PENDING' AND t1.order_date between '2022-01-01' AND '2022-01-05' GROUP BY 1, 2, 3 ORDER BY 4 DESC ``` ## 페더레이션 뷰 쿼리 페더레이션된 소스를 쿼리할 때 보기를 사용하여 기본 데이터 소스를 난독화하거나 데이터를 쿼리하는 다른 분석가로부터 복잡한 조인을 숨길 수 있습니다. ### 고려 사항 및 제한 사항 + 페더레이션된 보기에는 Athena 엔진 버전 3이 필요합니다. + 페더레이션된 보기는 기본 데이터 소스가 아닌 AWS Glue에 저장됩니다. + 페더레이션 뷰는 [Glue 데이터 카탈로그로 등록된](register-connection-as-gdc.md) 데이터 소스에서는 지원되지 않습니다. + 페더레이션된 카탈로그로 생성된 보기는 다음 예제와 같이 정규화된 이름 구문을 사용해야 합니다. ``` "ddbcatalog"."default"."customers" ``` + 페더레이션된 소스에서 쿼리를 실행하는 사용자는 페더레이션된 소스를 쿼리할 수 있는 권한이 있어야 합니다. + 페더레이션된 보기에는 `athena:GetDataCatalog` 권한이 필요합니다. 자세한 내용은 [Athena 페더레이션 쿼리에 대한 액세스 허용: 정책 예제](federated-query-iam-access.md) 섹션을 참조하세요. ### 예제 다음 예제에서는 페더레이션된 데이터 소스에 저장된 데이터에서 `customers` 보기를 생성합니다. **Example** ``` CREATE VIEW customers AS SELECT * FROM my_federated_source.default.table ``` 다음 쿼리 예제에서는 기본 페더레이션된 데이터 소스 대신, `customers` 보기를 참조하는 쿼리를 보여줍니다. **Example** ``` SELECT id, SUM(order_amount) FROM customers GROUP by 1 ORDER by 2 DESC LIMIT 50 ``` 다음 예제는 페더레이션된 데이터 소스와 Amazon S3 데이터 소스의 데이터를 결합하는 `order_summary` 보기를 생성합니다. Athena에서 이미 생성된 페더레이션된 소스에서 보기는 `person` 및 `profile` 테이블을 사용합니다. Amazon S3에서 보기는 `purchase` 및 `payment` 테이블을 사용합니다. Amazon S3를 참조하기 위해 명령문에서는 `awsdatacatalog` 키워드를 사용합니다. 페더레이션된 데이터 소스는 정규화된 이름 구문, *federated\$1source\$1name*.*federated\$1source\$1database*.*federated\$1source\$1table*을 사용합니다. **Example** ``` CREATE VIEW default.order_summary AS SELECT * FROM federated_source_name.federated_source_database."person" p JOIN federated_source_name.federated_source_database."profile" pr ON pr.id = p.id JOIN awsdatacatalog.default.purchase i ON p.id = i.id JOIN awsdatacatalog.default.payment pay ON pay.id = p.id ``` ### 추가 리소스 + 원래 소스와 분리되고 다중 사용자 모델에서 온디맨드 분석에 사용할 수 있는 페더레이션된 보기의 예제에 대해서는 *AWS 빅 데이터 블로그*의 [Extend your data mesh with Amazon Athena and federated views](https://aws.amazon.com/blogs/big-data/extend-your-data-mesh-with-amazon-athena-and-federated-views/)를 참조하세요. + Athena에서 보기 작업에 대한 자세한 내용은 [뷰 작업](views.md) 섹션을 참조하세요. # 페더레이션 패스스루 쿼리 사용 Athena에서는 데이터 소스 자체의 쿼리 언어를 사용하여 페더레이션 데이터 소스에서 쿼리를 실행하고 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운할 수 있습니다. 이러한 쿼리를 패스스루 쿼리라고 합니다. 패스스루 쿼리를 실행하려면 Athena 쿼리에서 테이블 함수를 사용합니다. 데이터 소스에서 실행할 패스스루 쿼리를 테이블 함수의 인수 중 하나에 포함시킵니다. 패스스루 쿼리는 Athena SQL을 사용하여 분석할 수 있는 테이블을 반환합니다. ## 지원되는 커넥터 다음 Athena 데이터 소스 커넥터는 패스스루 쿼리를 지원합니다. + [Azure 데이터 레이크 스토리지](connectors-adls-gen2.md) + [Azure Synapse](connectors-azure-synapse.md) + [Cloudera Hive](connectors-cloudera-hive.md) + [Cloudera Impala](connectors-cloudera-impala.md) + [CloudWatch](connectors-cloudwatch.md) + [Db2](connectors-ibm-db2.md) + [Db2 iSeries](connectors-ibm-db2-as400.md) + [DocumentDB](connectors-docdb.md) + [DynamoDB](connectors-dynamodb.md) + [HBase](connectors-hbase.md) + [Google BigQuery](connectors-bigquery.md) + [Hortonworks](connectors-hortonworks.md) + [MySQL](connectors-mysql.md) + [Neptune](connectors-neptune.md) + [OpenSearch](connectors-opensearch.md) + [Oracle](connectors-oracle.md) + [PostgreSQL](connectors-postgresql.md) + [Redshift](connectors-redshift.md) + [SAP HANA](connectors-sap-hana.md) + [Snowflake](connectors-snowflake.md) + [SQL Server](connectors-microsoft-sql-server.md) + [Teradata](connectors-teradata.md) + [Timestream](connectors-timestream.md) + [Vertica](connectors-vertica.md) ## 고려 사항 및 제한 사항 Athena에서 패스스루 쿼리를 사용할 때 다음 사항을 고려하세요. + 쿼리 패스스루는 Athena `SELECT` 문 또는 읽기 작업에만 지원됩니다. + 쿼리 성능은 데이터 소스의 구성에 따라 다를 수 있습니다. + 쿼리 패스스루는 Lake Formation 세분화된 액세스 제어를 지원하지 않습니다. + 패스스루 쿼리는 [Glue 데이터 카탈로그로 등록된](register-connection-as-gdc.md) 데이터 소스에서는 지원되지 않습니다. ## 구문 일반적인 Athena 쿼리 패스스루 구문은 다음과 같습니다. ``` SELECT * FROM TABLE(catalog.system.function_name(arg1 => 'arg1Value'[, arg2 => 'arg2Value', ...])) ``` 다음 사항에 유의하세요. + **catalog** - 대상 Athena 페더레이션 커넥터 이름 또는 데이터 카탈로그 이름입니다. + **system** - 함수가 포함된 네임스페이스입니다. 모든 Athena 커넥터 구현은 이 네임스페이스를 사용합니다. + **function\$1name** - 패스스루 쿼리를 데이터 소스로 푸시하는 함수의 이름입니다. 이를 흔히 `query`라고 부릅니다. 이 조합 `catalog.system.function_name`은 함수의 전체 확인 경로입니다. + **arg1, arg2 등** – 함수 인수입니다. 사용자는 이러한 인수를 함수에 전달해야 합니다. 대부분의 경우에는 데이터 소스로 전달되는 쿼리 문자열입니다. 대부분의 데이터 소스에서 첫 번째이자 유일한 인수 `query`이고 그 뒤에는 화살표 연산자 `=>` 기호와 쿼리 문자열이 붙습니다. ``` SELECT * FROM TABLE(catalog.system.query(query => 'query string')) ``` 간편함을 위해 선택적으로 명명된 `query` 인수와 화살표 연산자 `=>` 기호를 생략할 수 있습니다. ``` SELECT * FROM TABLE(catalog.system.query('query string')) ``` 대상 카탈로그의 컨텍스트 내에서 쿼리를 실행하는 경우 `catalog` 이름을 제거하여 쿼리를 더욱 단순화할 수 있습니다. ``` SELECT * FROM TABLE(system.query('query string')) ``` 데이터 소스에 쿼리 문자열 이상이 필요한 경우 데이터 소스에서 예상하는 순서대로 명명된 인수를 사용합니다. 예를 들어 `arg1 => 'arg1Value'` 표현식에는 첫 번째 인수와 해당 값이 포함됩니다. *arg1*이라는 이름은 데이터 소스에 따라 다르고 커넥터마다 다를 수 있습니다. ``` SELECT * FROM TABLE( system.query( arg1 => 'arg1Value', arg2 => 'arg2Value', arg3 => 'arg3Value' )); ``` 인수 이름을 생략하여 위 문을 단순화할 수도 있습니다. 하지만 메서드의 서명 순서를 따라야 합니다. 함수 서명에 대한 자세한 내용은 각 커넥터의 설명서를 참조하세요. ``` SELECT * FROM TABLE(catalog.system.query('arg1Value', 'arg2Value', 'arg3Value')) ``` 다음 예제와 같이 전체 함수 확인 경로를 활용하여 여러 Athena 커넥터에서 여러 패스스루 쿼리를 실행할 수 있습니다. ``` SELECT c_customer_sk FROM TABLE (postgresql.system.query('select * from customer limit 10')) UNION SELECT c_customer_sk FROM TABLE(dynamodb.system.query('select * from customer')) LIMIT 10 ``` 패스스루 쿼리를 페더레이션된 뷰의 일부로 사용할 수 있습니다. 동일한 제한 사항이 적용됩니다. 자세한 내용은 [페더레이션된 뷰 쿼리](https://docs.aws.amazon.com/athena/latest/ug/running-federated-queries.html#running-federated-queries-federated-views)를 참조하세요. ``` CREATE VIEW catalog.database.ViewName AS SELECT * FROM TABLE ( catalog.system.query('query') ) ``` 특정 커넥터에 사용할 정확한 구문에 대한 자세한 내용은 개별 커넥터 설명서를 참조하세요. ### 따옴표 사용 전달한 쿼리 문자열을 비롯한 인수 값은 다음 예제와 같이 작은따옴표로 묶어야 합니다. ``` SELECT * FROM TABLE(system.query(query => 'SELECT * FROM testdb.persons LIMIT 10')) ``` 쿼리 문자열을 큰따옴표로 묶으면 쿼리가 실패합니다. 다음 쿼리는 COLUMN\$1NOT\$1FOUND: line 1:43: Column 'select \$1 from testdb.persons limit 10' cannot be resolved 오류 메시지와 함께 실패합니다. ``` SELECT * FROM TABLE(system.query(query => "SELECT * FROM testdb.persons LIMIT 10")) ``` 작은따옴표를 이스케이프하려면 원본에 작은따옴표를 추가합니다(예: `terry''s_group`에 `terry's_group`). ## 예제 다음 예제 쿼리는 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다. ``` SELECT * FROM TABLE( catalog.system.query( query => 'SELECT * FROM customer LIMIT 10;' )) ``` 다음 문은 동일한 쿼리를 실행하지만 선택적으로 명명된 `query` 인수와 화살표 연산자 `=>` 기호를 제거합니다. ``` SELECT * FROM TABLE( catalog.system.query( 'SELECT * FROM customer LIMIT 10;' )) ``` 쉽게 재사용할 수 있도록 페더레이션된 뷰 내에 캡슐화할 수도 있습니다. 뷰와 함께 사용하는 경우 전체 함수 확인 경로를 사용해야 합니다. ``` CREATE VIEW AwsDataCatalog.default.example_view AS SELECT * FROM TABLE ( catalog.system.query('SELECT * FROM customer LIMIT 10;') ) ``` ## 쿼리 패스스루 옵트아웃 패스스루 쿼리를 비활성화하려면 `enable_query_passthrough`라는 이름으로 Lambda 환경 변수를 추가하고 `false`로 설정합니다. # 페더레이션 테이블 이름 한정자 이해 Athena는 다음 용어를 사용하여 데이터 객체의 계층 구조를 참조합니다. + **데이터 소스** - 데이터베이스 그룹 + **데이터베이스** - 테이블 그룹 + **테이블** - 행 또는 열 그룹으로 구성된 데이터 때때로 이 객체는 다음과 같이 동등한 대체 이름으로 참조되기도 합니다. + 데이터 소스를 카탈로그라고도 합니다. + 데이터베이스를 스키마라고도 합니다. ## 페더레이션된 데이터 소스의 용어 페더레이션된 데이터 소스를 쿼리하는 경우 기본 데이터 소스가 Athena와 같은 용어를 사용하지 않을 수 있다는 점에 유의합니다. 페더레이션된 쿼리를 작성할 때는 이 차이점을 염두에 두세요. 다음 섹션에서는 Athena의 데이터 객체 용어가 페더레이션된 데이터 소스의 데이터 객체 용어와 어떻게 연관되는지 설명합니다. ### Amazon Redshift Amazon Redshift *데이터베이스*는 Redshift *테이블* 그룹을 포함하는 Redshift *스키마* 그룹입니다. **** | Athena | Redshift | | --- | --- | | Redshift 데이터 소스 | Redshift database를 가리키도록 구성된 Redshift 커넥터 Lambda 함수입니다. | | data\$1source.database.table | database.schema.table | 예제 쿼리 ``` SELECT * FROM Athena_Redshift_connector_data_source.Redshift_schema_name.Redshift_table_name ``` 이 커넥터에 대한 자세한 내용은 [Amazon Athena Redshift 커넥터](connectors-redshift.md) 섹션을 참조하세요. ### Cloudera Hive Cloudera Hive *서버* 또는 *클러스터*는 Cloudera Hive *테이블* 그룹을 포함하는 Cloudera Hive *데이터베이스* 그룹입니다. **** | Athena | Hive | | --- | --- | | Cloudera Hive 데이터 소스 | Cloudera Hive server를 가리키도록 구성된 Cloudera Hive 커넥터 Lambda 함수입니다. | | data\$1source.database.table | server.database.table | 예제 쿼리 ``` SELECT * FROM Athena_Cloudera_Hive_connector_data_source.Cloudera_Hive_database_name.Cloudera_Hive_table_name ``` 이 커넥터에 대한 자세한 내용은 [Amazon Athena Cloudera Hive 커넥터](connectors-cloudera-hive.md) 섹션을 참조하세요. ### Cloudera Impala Impala *서버* 또는 *클러스터*는 Impala *테이블* 그룹을 포함하는 Impala *데이터베이스* 그룹입니다. **** | Athena | Impala | | --- | --- | | Impala 데이터 소스 | Impala server를 가리키도록 구성된 Impala 커넥터 Lambda 함수입니다. | | data\$1source.database.table | server.database.table | 예제 쿼리 ``` SELECT * FROM Athena_Impala_connector_data_source.Impala_database_name.Impala_table_name ``` 이 커넥터에 대한 자세한 내용은 [Amazon Athena Cloudera Impala 커넥터](connectors-cloudera-impala.md) 섹션을 참조하세요. ### MySQL MySQL *서버*는 MySQL *테이블* 그룹을 포함하는 MySQL *데이터베이스* 그룹입니다. **** | Athena | MySQL | | --- | --- | | MySQL 데이터 소스 | MySQL server를 가리키도록 구성된 MySQL 커넥터 Lambda 함수입니다. | | data\$1source.database.table | server.database.table | 예제 쿼리 ``` SELECT * FROM Athena_MySQL_connector_data source.MySQL_database_name.MySQL_table_name ``` 이 커넥터에 대한 자세한 내용은 [Amazon Athena MySQL 커넥터](connectors-mysql.md) 섹션을 참조하세요. ### Oracle Oracle *서버* 또는 *데이터베이스*는 Oracle *테이블* 그룹을 포함하는 Oracle *스키마* 그룹입니다. **** | Athena | Oracle | | --- | --- | | Oracle 데이터 소스 | Oracle server를 가리키도록 구성된 Oracle 커넥터 Lambda 함수입니다. | | data\$1source.database.table | server.schema.table | 예제 쿼리 ``` SELECT * FROM Athena_Oracle_connector_data_source.Oracle_schema_name.Oracle_table_name ``` 이 커넥터에 대한 자세한 내용은 [Amazon Athena Oracle 커넥터](connectors-oracle.md) 섹션을 참조하세요. ### Postgres Postgres *서버* 또는 *클러스터*는 Postgres *데이터베이스* 그룹입니다. Postgres *데이터베이스*는 Postgres *테이블* 그룹을 포함하는 Postgres *스키마* 그룹입니다. **** | Athena | Postgres | | --- | --- | | Postgres 데이터 소스 | Postgres server 및 database를 가리키도록 구성된 Postgres 커넥터 Lambda 함수입니다. | | data\$1source.database.table | server.database.schema.table | 예제 쿼리 ``` SELECT * FROM Athena_Postgres_connector_data_source.Postgres_schema_name.Postgres_table_name ``` 이 커넥터에 대한 자세한 내용은 [Amazon Athena PostgreSQL 커넥터](connectors-postgresql.md) 섹션을 참조하세요. # Athena Query Federation SDK를 사용하여 데이터 소스 커넥터 개발 [Athena Query Federation SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk)를 사용해 자체 데이터 소스 커넥터를 쓸 수 있습니다. Athena Query Federation SDK는 Athena에서 사용자가 작성 및 배포하는 코드에 쿼리 실행 계획의 일부를 위임하는 데 사용할 수 있는 인터페이스 및 연결 프로토콜 집합을 정의합니다. SDK에는 커넥터 제품군과 커넥터 예제가 포함되어 있습니다. 사용자 지정 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다. 직접 사용하기 위해 Amazon Athena의 [사전 구축된 커넥터](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors)를 사용자 지정할 수도 있습니다. GitHub에서 소스 코드의 복사본을 수정한 다음 [Connector publish tool](https://github.com/awslabs/aws-athena-query-federation/wiki/Connector_Publish_Tool)을 사용하여 AWS Serverless Application Repository 패키지를 만들 수 있습니다. 이러한 방식으로 커넥터를 배포한 후에는 Athena 쿼리에 사용할 수 있습니다. SDK를 다운로드하는 방법과 자체 커넥터 작성에 대한 자세한 지침은 GitHub의 [Athena 커넥터 예제](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-example)를 참조하세요. # Apache Spark용 데이터 소스 커넥터 작업 일부 Athena 데이터 소스 커넥터는 Spark DSV2 커넥터로 사용할 수 있습니다. Spark DSV2 커넥터 이름에는 `-dsv2` 접미사(예: `athena-dynamodb-dsv2`)가 있습니다. 다음은 현재 사용 가능한 DSV2 커넥터, 해당 Spark `.format()` 클래스 이름, 해당 Amazon Athena 페더레이션된 쿼리 설명서 링크입니다. | DSV2 커넥터 | Spark .format() 클래스 이름 | 설명서 | | --- | --- | --- | | athena-cloudwatch-dsv2 | com.amazonaws.athena.connectors.dsv2.cloudwatch.CloudwatchTableProvider | [CloudWatch](connectors-cloudwatch.md) | | athena-cloudwatch-metrics-dsv2 | com.amazonaws.athena.connectors.dsv2.cloudwatch.metrics.CloudwatchMetricsTableProvider | [CloudWatch 지표](connectors-cwmetrics.md) | | athena-aws-cmdb-dsv2 | com.amazonaws.athena.connectors.dsv2.aws.cmdb.AwsCmdbTableProvider | [CMDB](connectors-cmdb.md) | | athena-dynamodb-dsv2 | com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider | [DynamoDB](connectors-dynamodb.md) | DSV2 커넥터용 `.jar` 파일을 다운로드하려면 [Amazon Athena Query Federation DSV2](https://github.com/awslabs/aws-athena-query-federation-dsv2) GitHub 페이지를 방문하고 **Releases**, **Release ****, **Assets** 섹션을 참조하세요. ## Spark에 대해 jar 지정 Spark에서 Athena DSV2 커넥터를 사용하려면 사용하는 Spark 환경에 커넥터용 `.jar` 파일을 제출합니다. 다음 섹션에서는 구체적인 사례를 설명합니다. ### Athena for Spark Amazon Athena for Apache Spark에 사용자 지정 `.jar` 파일 및 사용자 지정 구성을 추가하는 방법에 대한 자세한 내용은 [Spark 속성을 사용하여 사용자 지정 구성 지정](notebooks-spark-custom-jar-cfg.md) 섹션을 참조하세요. ### 일반 Spark 커넥터 `.jar` 파일을 Spark로 전달하려면 다음 예제와 같이 `spark-submit` 명령을 사용하고 `--jars` 옵션에 `.jar` 파일을 지정합니다. ``` spark-submit \ --deploy-mode cluster \ --jars https://github.com/awslabs/aws-athena-query-federation-dsv2/releases/download/some_version/athena-dynamodb-dsv2-some_version.jar ``` ### Amazon EMR Spark Amazon EMR에서 `--jars` 파라미터와 함께 `spark-submit` 명령을 실행하려면 Amazon EMR Spark 클러스터에 단계를 추가해야 합니다. Amazon EMR에서 `spark-submit`을 사용하는 방법에 대한 자세한 내용은 *Amazon EMR 릴리스 안내서*의 [Add a Spark step](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-spark-submit-step.html)을 참조하세요. ### AWS Glue ETL Spark AWS Glue ETL의 경우 `.jar` 파일의 GitHub.com URL을 `aws glue start-job-run` 명령의 `--extra-jars` 인수로 전달할 수 있습니다. AWS Glue 설명서에는 Amazon S3 경로를 사용하며 `--extra-jars` 파라미터를 설명하지만, 파라미터는 HTTPS URL을 사용할 수도 있습니다. 자세한 내용은 *AWS Glue 개발자 안내서*의 [Job parameter reference](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html#w5aac32c13c11)를 참조하세요. ## Spark에서 커넥터 쿼리 Apache Spark에서 Athena의 기존 페더레이션된 쿼리와 동일한 쿼리를 제출하려면 `spark.sql()` 함수를 사용합니다. 예를 들어 다음과 같은 Athena 쿼리를 Apache Spark에서 사용하는 경우를 가정합니다. ``` SELECT somecola, somecolb, somecolc FROM ddb_datasource.some_schema_or_glue_database.some_ddb_or_glue_table WHERE somecola > 1 ``` Amazon Athena DynamoDB DSV2 커넥터를 사용하여 Spark에서 동일한 쿼리를 수행하려면 다음 코드를 사용합니다. ``` dynamoDf = (spark.read .option("athena.connectors.schema", "some_schema_or_glue_database") .option("athena.connectors.table", "some_ddb_or_glue_table") .format("com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider") .load()) dynamoDf.createOrReplaceTempView("ddb_spark_table") spark.sql(''' SELECT somecola, somecolb, somecolc FROM ddb_spark_table WHERE somecola > 1 ''') ``` ## 파라미터 지정 Athena 데이터 소스 커넥터의 DSV2 버전은 해당 Athena 데이터 소스 커넥터와 동일한 파라미터를 사용합니다. 파라미터 정보는 해당 Athena 데이터 소스 커넥터의 설명서를 참조하세요. PySpark 코드에서 다음 구문을 사용하여 파라미터를 구성합니다. ``` spark.read.option("athena.connectors.conf.parameter", "value") ``` 예를 들어 다음 코드는 Amazon Athena DynamoDB 커넥터 `disable_projection_and_casing` 파라미터를 `always`로 설정합니다. ``` dynamoDf = (spark.read .option("athena.connectors.schema", "some_schema_or_glue_database") .option("athena.connectors.table", "some_ddb_or_glue_table") .option("athena.connectors.conf.disable_projection_and_casing", "always") .format("com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider") .load()) ``` # Athena에서 Amazon DataZone 사용 [Amazon DataZone](https://aws.amazon.com/datazone)을 사용하여 조직 경계를 넘어 대규모로 데이터를 공유, 검색 및 발견할 수 있습니다. DataZone은 Athena, AWS Glue 및 AWS Lake Formation과 같은 AWS 분석 서비스 전반의 경험을 단순화합니다. 예를 들어, 다양한 데이터 소스에 페타바이트 규모의 데이터가 있는 경우 Amazon DataZone을 사용하여 사람, 데이터 및 도구의 그룹화를 기반으로 비즈니스 사용 사례를 구축할 수 있습니다. 자세한 내용은 [What is Amazon DataZone?](https://docs.aws.amazon.com/datazone/latest/userguide/what-is-datazone.html)을 참조하세요. Athena에서는 쿼리 편집기를 사용하여 DataZone 환경에 액세스하고 쿼리할 수 있습니다. DataZone 환경은 DataZone 프로젝트와 도메인 조합을 지정합니다. Athena 콘솔에서 DataZone 환경을 사용하면 DataZone 환경의 IAM 역할을 수임하게 되며 해당 환경에 속하는 데이터베이스와 테이블만 표시됩니다. 권한은 DataZone에서 지정하는 역할에 따라 결정됩니다. Athena에서는 쿼리 편집기 페이지의 **DataZone 환경** 선택기를 사용하여 DataZone 환경을 선택할 수 있습니다. **Athena에서 DataZone 환경 열기** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. Athena 콘솔 오른쪽 상단의 **작업 그룹** 옆에서 **DataZone 환경**을 선택합니다. **참고** **DataZone 환경** 옵션은 DataZone에서 사용 가능한 도메인이 하나 이상 있는 경우에만 제공됩니다. ![\[DataZone 환경을 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/datazone-using-1.png) 1. **DataZone 환경** 선택기를 사용하여 DataZone 환경을 선택합니다. ![\[DataZone 환경 선택\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/datazone-using-2.png) 1. **DataZone 환경으로 전환** 대화 상자에서 해당 환경이 원하는 환경인지 확인한 다음 **DataZone 환경으로 전환**을 선택합니다. ![\[DataZone 환경으로 변경을 확인합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/datazone-using-3.png) DataZone과 Athena를 시작하는 방법에 대한 자세한 내용은 **Amazon DataZone User Guide의 [Getting started](https://docs.aws.amazon.com/datazone/latest/userguide/getting-started.html) 자습서를 참조하세요. # 외부 Hive 메타스토어 사용 Apache Hive 메타스토어를 사용하는 Amazon S3에서 데이터 세트를 쿼리하기 위해 외부 Hive 메타스토어에 Amazon Athena 데이터 커넥터를 사용할 수 있습니다. 메타데이터를 AWS Glue Data Catalog로 마이그레이션할 필요가 없습니다. Athena 관리 콘솔에서 프라이빗 VPC에 있는 Hive 메타스토어와 통신하는 Lambda 함수를 구성한 다음 메타스토어에 연결합니다. Lambda에서 Hive 메타스토어로의 연결은 프라이빗 Amazon VPC 채널로 보호되며 퍼블릭 인터넷을 사용하지 않습니다. 자체 Lambda 함수 코드를 제공하거나 외부 Hive 메타스토어에 대한 Athena 데이터 커넥터의 기본 구현을 사용할 수 있습니다. **Topics** + [기능 개요](#connect-to-a-data-source-hive-features) + [워크플로](#connect-to-data-source-hive-workflow) + [고려 사항 및 제한 사항](#connect-to-a-data-source-hive-considerations) + [Apache Hive 메타스토어에 Athena 연결](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md) + [AWS Serverless Application Repository를 사용하여 Hive 데이터 소스 커넥터 배포](connect-data-source-sar-hive.md) + [기존 IAM 실행 역할을 사용하여 Athena를 Hive 메타스토어에 연결](connect-data-source-hive-existing-iam-role.md) + [배포된 Hive 메타스토어 커넥터를 사용하도록 Athena 구성](connect-data-source-hive-existing-lambda.md) + [외부 Hive 메타스토어 쿼리에서 카탈로그 이름 생략](datastores-hive-default-catalog.md) + [Hive 뷰 작업](hive-views.md) + [Hive 메타스토어와 함께 AWS CLI 사용](datastores-hive-cli.md) + [Athena 외부 Hive 메타스토어 커넥터 수정](datastores-hive-reference-implementation.md) ## 기능 개요 외부 Hive 메타스토어에 대한 Athena 데이터 커넥터를 사용하여 다음 작업을 수행할 수 있습니다. + Athena 콘솔을 사용하여 사용자 지정 카탈로그를 등록하고 사용자 지정 카탈로그를 사용하여 쿼리를 실행합니다. + 여러 외부 Hive 메타스토어에 대한 Lambda 함수를 정의하고 Athena 쿼리에 조인합니다. + 동일한 Athena 쿼리에서 외부 Hive 메타스토어 및 AWS Glue Data Catalog를 사용합니다. + 쿼리 실행 컨텍스트의 카탈로그를 현재 기본 카탈로그로 지정합니다. 이렇게 하면 쿼리의 데이터베이스 이름에 카탈로그 이름을 접두사로 붙일 필요가 없습니다. `catalog.database.table` 구문을 사용하는 대신 `database.table`을 사용할 수 있습니다. + 다양한 도구를 사용하여 외부 Hive 메타스토어를 참조하는 쿼리를 실행합니다. Athena 콘솔, AWS CLI, AWS SDK, Athena API, 업데이트된 Athena JDBC 및 ODBC 드라이버를 사용할 수 있습니다. 업데이트된 드라이버는 사용자 지정 카탈로그를 지원합니다. ### API 지원 외부 Hive 메타스토어용 Athena 데이터 커넥터에는 카탈로그 등록 API 작업 및 메타데이터 API 작업에 대한 지원이 포함되어 있습니다. + **카탈로그 등록** – 외부 Hive 메타스토어 및 [연합 데이터 원본](federated-queries.md)에 대한 사용자 지정 카탈로그를 등록합니다. + **메타데이터** - 메타데이터 API를 사용하여 AWS Glue에 대한 데이터베이스 및 테이블 정보와 Athena를 통해 등록한 모든 카탈로그를 제공합니다. + **Athena JAVA SDK 클라이언트** - 업데이트된 Athena Java SDK 클라이언트에서 `StartQueryExecution` 작업의 카탈로그에 대한 지원, 메타데이터 API 및 카탈로그 등록을 사용합니다. ### 참조 구현 Athena는 외부 Hive 메타스토어에 연결하는 Lambda 함수에 대한 참조 구현을 제공합니다. 참조 구현은 [Athena Hive 메타스토어](https://github.com/awslabs/aws-athena-hive-metastore)의 오픈 소스 프로젝트로 GitHub에서 제공됩니다. 참조 구현은 AWS Serverless Application Repository(SAR)에서 다음 두 AWS SAM 애플리케이션으로 사용할 수 있습니다. SAR에서 이러한 애플리케이션 중 하나를 사용하여 Lambda 함수를 직접 만들 수 있습니다. + `AthenaHiveMetastoreFunction` - Uber Lambda 함수 `.jar` 파일. "uber" JAR(fat JAR 또는 종속 항목이 있는 JAR이라고도 함)은 하나의 파일에 Java 프로그램과 해당 종속 항목을 모두 포함한 `.jar` 파일입니다. + `AthenaHiveMetastoreFunctionWithLayer` - Lambda 계층 및 thin Lambda 함수 `.jar` 파일. ## 워크플로 다음 다이어그램은 Athena가 외부 Hive 메타스토어와 상호 작용하는 방식을 보여줍니다. ![\[Athena가 외부 Hive 메타스토어와 상호 작용하는 방식.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connect-to-data-source-hive-workflow.png) 이 워크플로우에서는 데이터베이스에 연결된 Hive 메타스토어가 VPC 내에 있습니다. Hive CLI를 사용하는 Hive 메타스토어를 관리하는 데 Hive Server2를 사용합니다. Athena의 외부 Hive 메타스토어를 사용하는 워크플로우에는 다음 단계가 포함됩니다. 1. VPC 내에 있는 Hive 메타스토어에 Athena를 연결하는 Lambda 함수를 생성합니다. 1. Hive 메타스토어에 고유한 카탈로그 이름과 계정에 해당 함수 이름을 등록합니다. 1. 카탈로그 이름을 사용하는 Athena DML 또는 DDL 쿼리를 실행하면 Athena 쿼리 엔진은 카탈로그 이름과 연결된 Lambda 함수 이름을 호출합니다. 1. Lambda 함수는 AWS PrivateLink를 사용하여 VPC의 외부 Hive 메타스토어와 통신하고 메타데이터 요청에 대한 응답을 수신합니다. Athena는 기본 AWS Glue Data Catalog의 데이데이터를 사용하는 방식과 동일하게 외부 Hive 메타스토어의 메타데이터를 사용합니다. ## 고려 사항 및 제한 사항 외부 Hive 메타스토어용 Athena 데이터 커넥터를 사용하는 경우 다음 사항을 고려해야 합니다. + CTAS를 사용하여 외부 Hive 메타스토어에서 테이블을 생성할 수 있습니다. + INSERT INTO를 사용하여 외부 Hive 메타스토어에 데이터를 삽입할 수 있습니다. + 외부 Hive 메타스토어에 대한 DDL 지원은 다음 문으로 제한됩니다. + ALTER DATABASE SET DBPROPERTIES + ALTER TABLE ADD COLUMNS + ALTER TABLE ADD PARTITION + ALTER TABLE DROP PARTITION + ALTER TABLE RENAME PARTITION + ALTER TABLE REPLACE COLUMNS + ALTER TABLE SET LOCATION + ALTER TABLE SET TBLPROPERTIES + 데이터베이스 생성 + CREATE TABLE + CREATE TABLE AS + DESCRIBE TABLE + DROP DATABASE + DROP TABLE + SHOW COLUMNS + SHOW CREATE TABLE + SHOW PARTITIONS + SHOW SCHEMAS + SHOW TABLES + SHOW TBLPROPERTIES + 보유할 수 있는 등록된 카탈로그의 최대 수는 1,000개입니다. + Hive 메타스토어에 대한 Kerberos 인증은 지원되지 않습니다. + JDBC 드라이버와 함께 [연합 쿼리](federated-queries.md)나 외부 Hive 메타스토어를 사용하려면 JDBC 연결 문자열에 `MetadataRetrievalMethod=ProxyAPI`를 포함해야 합니다. JDBC 드라이버에 대한 자세한 내용은 [JDBC로 Amazon Athena에 연결](connect-with-jdbc.md) 섹션을 참조하세요. + Hive 숨김 열 `$path`, `$bucket`, `$file_size`, `$file_modified_time`, `$partition`, `$row_id`는 세분화된 액세스 제어 필터링에 사용할 수 없습니다. + Hive 숨김 시스템 테이블(예: `example_table$partitions` 또는 `example_table$properties`)은 세분화된 액세스 제어에서 지원되지 않습니다. ### 권한 사전 구축된 사용자 지정 데이터 커넥터가 올바르게 작동하려면 다음 리소스에 액세스해야 할 수 있습니다. 사용하는 커넥터의 정보를 확인하여 VPC를 올바르게 구성했는지 확인합니다. Athena에서 쿼리를 실행하고 데이터 원본 커넥터를 만드는 데 필요한 IAM 권한에 대한 자세한 내용은 [외부 Hive 메타스토어용 Athena 데이터 커넥터에 대한 액세스 허용](hive-metastore-iam-access.md) 및 [외부 Hive 메타스토어에 대한 Lambda 함수 액세스 허용](hive-metastore-iam-access-lambda.md) 단원을 참조하세요. + **Amazon S3** – 쿼리 결과를 Amazon S3의 Athena 쿼리 결과 위치에 작성하는 것 외에도 데이터 커넥터는 Amazon S3의 유출 버킷에 작성합니다. 이 Amazon S3 위치에 대한 연결 및 권한이 필요합니다. 자세한 내용은 이 주제의 후반부에서 [Amazon S3의 분산 위치](#connect-to-data-source-hive-spill-location) 단원을 참조하세요. + **Athena** – 쿼리 상태를 확인하고 오버스캔을 방지하려면 액세스가 필요합니다. + **AWS Glue** - 커넥터가 보충 또는 기본 메타데이터에 AWS Glue를 사용하는 경우 액세스가 필요합니다. + **AWS Key Management Service** + **정책** - Hive 메타스토어, Athena Query Federation 및 UDF에는 [AWS 관리형 정책: AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy) 외의 정책이 필요합니다. 자세한 내용은 [Athena의 자격 증명 및 액세스 관리](security-iam-athena.md) 단원을 참조하세요. ### Amazon S3의 분산 위치 Athena 함수 응답 크기에는 [제한](https://docs.aws.amazon.com/lambda/latest/dg/limits.html)이 있기 때문에 임계값을 초과하는 응답은 Lambda 함수를 생성할 때 지정한 Amazon S3 위치로 분산됩니다. Athena는 이러한 응답을 Amazon S3로부터 직접 읽습니다. **참고** Athena는 Amazon S3의 응답 파일을 제거하지 않습니다. 응답 파일을 자동으로 삭제하도록 보존 정책을 설정하는 것이 좋습니다. # Apache Hive 메타스토어에 Athena 연결 Apache Hive 메타스토어에 Athena를 연결하려면 Lambda 함수를 만들고 구성해야 합니다. 기본 구현의 경우 Athena 관리 콘솔에서 시작하는 모든 필수 단계를 수행할 수 있습니다. **참고** 다음 절차를 수행하려면 Lambda 함수에 대한 사용자 지정 IAM 역할을 생성할 권한이 있어야 합니다. 사용자 지정 역할을 만들 수 있는 권한이 없는 경우 Athena [참조 구현](connect-to-data-source-hive.md#connect-to-a-data-source-hive-features-reference-implementation)을 사용하여 Lambda 함수를 별도로 만든 다음 AWS Lambda 콘솔에서 함수에 대한 기존 IAM 역할을 선택합니다. 자세한 내용은 [기존 IAM 실행 역할을 사용하여 Athena를 Hive 메타스토어에 연결](connect-data-source-hive-existing-iam-role.md) 단원을 참조하세요. **Hive 메타스토어에 Athena를 연결하려면** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. **데이터 소스 및 카탈로그**를 선택합니다. 1. 콘솔 오른쪽 위에서 **데이터 원본 생성(Create data source)**을 선택합니다. 1. **데이터 원본 선택(Choose data sources)** 페이지에서 **데이터 원본(Data source)**에 대해 **S3 - Apache Hive 메타스토어(S3 - Apache Hive metastore)**를 선택합니다. 1. **다음**을 선택합니다. 1. **데이터 원본 세부 정보(Data source details)** 섹션의 **데이터 원본 이름(Data source name)**에 Athena에서 데이터 원본을 쿼리할 때 SQL 문에 사용할 이름을 입력합니다. 이름은 127자까지 입력할 수 있으며 계정 내에서 고유해야 합니다. 생성 후에는 변경할 수 없습니다. 유효한 문자는 a-z, A-Z, 0-9, \$1(밑줄), @(앰퍼샌드) 및 -(하이픈)입니다. `awsdatacatalog`, `hive`, `jmx`, `system` 이름은 Athena에 예약되어 있으므로 데이터 원본 이름에 사용할 수 없습니다. 1. **Lambda 함수(Lambda function)**에서 **새 Lambda 함수 생성(Create a new Lambda function)**을 선택한 다음**AWS Lambda에서 새 Lambda 함수 생성(Create a new Lambda function)**을 선택합니다. AWS Lambda 콘솔에서 **AthenaHiveMetastoreFunction** 페이지가 열립니다. 이 페이지에는 커넥터에 대한 자세한 정보가 포함되어 있습니다. ![\[AWS Lambda 콘솔의 AthenaHiveMetastoreFunction 페이지.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connect-to-data-source-hive-4.png) 1. **애플리케이션 설정(Application settings)**에서 Lambda 함수에 대한 파라미터를 입력합니다. + **LambdaFuncName** – 함수의 이름을 제공합니다. **myHiveMetastore**를 예로 들 수 있습니다. + **SpillLocation** – Lambda 함수 응답 크기가 4MB를 초과하는 경우 분산 메타데이터를 보관할 이 계정의 Amazon S3 위치를 지정합니다. + **HMSUris** – 포트 9083에서 Thrift 프로토콜을 사용하는 Hive 메타스토어 호스트의 URI를 입력합니다. `thrift://:9083` 구문을 사용합니다. + **LambdaMemory** - 128MB \$1 3008MB 사이의 값을 지정합니다. Lambda 함수는 사용자가 구성하는 메모리 양에 비례하여 할당된 CPU 주기입니다. 기본값은 1024입니다. + **LambdaTimeout** – 허용되는 최대 Lambda 호출 실행 시간을 1초 단위로 1\$1900초 범위에서 지정합니다(900초는 15분). 기본값은 300초(5분)입니다. + **VPCSecurityGroupIds** – Hive 메타스토어에 대한 VPC 보안 그룹 ID 목록을 입력합니다(쉼표로 구분). + **VPCSubnetIds** – Hive 메타스토어에 대한 VPC 서브넷 ID 목록을 입력합니다(쉼표로 구분). 1. **이 앱은 사용자 지정 IAM 역할을 생성한다는 데 동의합니다(I acknowledge that this app creates custom IAM roles)**를 선택하고 **배포(Deploy)**를 선택합니다. ![\[AWS Lambda 콘솔에서 Lambda 함수 앱 배포.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connect-to-data-source-hive-4a.png) 배포가 완료되면 함수가 Lambda 애플리케이션 목록에 나타납니다. 이제 Hive 메타스토어 기능이 계정에 배포되었으므로 이를 사용하도록 Athena를 구성할 수 있습니다. 1. 콘솔의 **데이터 원본 입력(Enter data sources)** 페이지로 돌아갑니다. 1. **Lambda 함수** 섹션에서 Lambda 검색 상자 옆에 있는 새로 고침 아이콘을 선택합니다. 사용 가능한 함수 목록을 새로 고치면 새로 만든 함수가 목록에 나타납니다. 1. Lambda 콘솔에서 방금 생성한 함수의 이름을 선택합니다. Lambda 함수의 ARN이 표시됩니다. 1. (선택 사항) **태그(Tags)**에 대해 이 데이터 원본과 연결할 키-값 페어를 추가합니다. 태그에 대한 자세한 내용은 [Athena 리소스 태깅](tags.md) 섹션을 참조하세요. 1. **다음**을 선택합니다. 1. **검토 및 생성** 페이지에서 데이터 원본 세부 정보를 검토한 다음 **데이터 원본 생성**을 선택합니다. 1. 데이터 원본 페이지의 **데이터 원본 세부 정보** 섹션에는 새 커넥터에 대한 정보가 표시됩니다. 이제 지정한 **데이터 원본 이름(Data source name)**을 사용하여 SQL 쿼리에서 Hive 메타스토어를 참조할 수 있습니다. SQL 쿼리에서 다음 예제 구문을 사용하여 `hms-catalog-1`을 앞에서 지정한 카탈로그 이름으로 바꿉니다. ``` SELECT * FROM hms-catalog-1.CustomerData.customers ``` 1. 생성한 데이터 원본 보기, 편집 또는 삭제에 대한 자세한 내용은 [데이터 소스 관리](data-sources-managing.md) 섹션을 참조하세요. # AWS Serverless Application Repository를 사용하여 Hive 데이터 소스 커넥터 배포 Hive용 Athena 데이터 원본 커넥터를 배포하려면 Athena 콘솔로 시작하는 대신 [AWS Serverless Application Repository](https://aws.amazon.com/serverless/serverlessrepo/)를 사용합니다. AWS Serverless Application Repository로 사용할 커넥터를 찾고 커넥터에 필요한 파라미터를 제공한 다음 계정에 커넥터를 배포합니다. 그런 다음 커넥터를 배포한 후 Athena 콘솔을 사용하여 Athena에서 데이터 원본을 사용할 수 있도록 합니다. **AWS Serverless Application Repository를 사용하여 Hive용 데이터 원본 커넥터를 계정에 배포하려면** 1. AWS Management Console에 로그인하고 **서버리스 앱 리포지토리**를 엽니다. 1. 탐색 창에서 **사용 가능한 애플리케이션**을 선택합니다. 1. **사용자 지정 IAM 역할 또는 리소스 정책을 만드는 앱 표시(Show apps that create custom IAM roles or resource policies)** 옵션을 선택합니다. 1. 검색 상자에 **Hive**을(를) 입력합니다. 나타나는 커넥터에는 다음 두 가지가 포함됩니다. + **AthenaHiveMetastoreFunction** – Uber Lambda 함수 `.jar` 파일. + **AthenaHiveMetastoreFunctionWithLayer** – Lambda 계층 및 thin Lambda 함수 `.jar` 파일. 두 애플리케이션은 동일한 기능을 가지며 구현만 다릅니다. 둘 중 하나를 사용하여 Hive 메타스토어에 Athena를 연결하는 Lambda 함수를 만들 수 있습니다. 1. 삭제할 커넥터의 이름을 선택합니다. 이 자습서에서는 **AthenaHiveMetastoreFunction**을 사용합니다. ![\[Hive용 Athena 데이터 원본 커넥터의 이름을 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connect-data-source-sar-hive-1.png) 1. **애플리케이션 설정(Application settings)**에서 Lambda 함수에 대한 파라미터를 입력합니다. + **LambdaFuncName** – 함수의 이름을 제공합니다. **myHiveMetastore**를 예로 들 수 있습니다. + **SpillLocation** – Lambda 함수 응답 크기가 4MB를 초과하는 경우 분산 메타데이터를 보관할 이 계정의 Amazon S3 위치를 지정합니다. + **HMSUris** – 포트 9083에서 Thrift 프로토콜을 사용하는 Hive 메타스토어 호스트의 URI를 입력합니다. `thrift://:9083` 구문을 사용합니다. + **LambdaMemory** - 128MB \$1 3008MB 사이의 값을 지정합니다. Lambda 함수는 사용자가 구성하는 메모리 양에 비례하여 할당된 CPU 주기입니다. 기본값은 1024입니다. + **LambdaTimeout** – 허용되는 최대 Lambda 호출 실행 시간을 1초 단위로 1\$1900초 범위에서 지정합니다(900초는 15분). 기본값은 300초(5분)입니다. + **VPCSecurityGroupIds** – Hive 메타스토어에 대한 VPC 보안 그룹 ID 목록을 입력합니다(쉼표로 구분). + **VPCSubnetIds** – Hive 메타스토어에 대한 VPC 서브넷 ID 목록을 입력합니다(쉼표로 구분). 1. **애플리케이션 세부 정보(Application details)** 페이지의 오른쪽 아래에서 **이 앱에서 사용자 지정 IAM 역할을 생성하는 것을 인정합니다(I acknowledge that this app creates custom IAM roles)**를 선택하고 **배포(Deploy)**를 선택합니다. 이때 Lambda 함수를 사용하여 Hive 메타스토어에 연결하도록 Athena를 구성할 수 있습니다. 단계는 [배포된 Hive 메타스토어 커넥터를 사용하도록 Athena 구성](connect-data-source-hive-existing-lambda.md)를 참조하세요. # 기존 IAM 실행 역할을 사용하여 Athena를 Hive 메타스토어에 연결 기존 IAM 역할을 사용하는 Lambda 함수로 외부 Hive 메타스토어를 Athena에 연결하려면 외부 Hive 메타스토어용 Athena 커넥터의 Athena 참조 구현을 사용합니다. 3가지 주요 단계는 다음과 같습니다. 1. **[복제 및 구축](#connect-data-source-hive-existing-iam-role-clone-and-build-the-lambda-function)** - Athena 참조 구현을 복제하고 Lambda 함수 코드를 포함하는 JAR 파일을 구축합니다. 1. **[AWS Lambda 콘솔](#connect-data-source-hive-existing-iam-role-aws-lambda-console)** - AWS Lambda 콘솔에서 Lambda 함수를 생성하고 기존 IAM 실행 역할을 할당한 다음, 생성한 함수 코드를 업로드합니다. 1. **[Amazon Athena 콘솔](connect-data-source-hive-existing-lambda.md)** - Amazon Athena 콘솔에서, Athena 쿼리에서 외부 Hive 메타스토어를 참조하는 데 사용할 수 있는 데이터 원본 이름을 생성합니다. 사용자 지정 IAM 역할을 생성할 수 있는 권한이 이미 있는 경우 Athena 콘솔과 AWS Serverless Application Repository를 사용한 간편한 워크플로를 사용하여 Lambda 함수를 만들고 구성합니다. 자세한 내용은 [Apache Hive 메타스토어에 Athena 연결](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md) 섹션을 참조하세요. ## 사전 조건 + Git이 시스템에 설치되어 있어야 합니다. + [Apache Maven](https://maven.apache.org/)이 설치되어 있어야 합니다. + Lambda 함수에 할당할 수 있는 IAM 실행 역할이 있습니다. 자세한 내용은 [외부 Hive 메타스토어에 대한 Lambda 함수 액세스 허용](hive-metastore-iam-access-lambda.md) 단원을 참조하세요. ## Lambda 함수 복제 및 구축 Athena 참조 구현을 위한 함수 코드는 GitHub의 [awslabs/aws-athena-hive-metastore](https://github.com/awslabs/aws-athena-hive-metastore)에 있는 Maven 프로젝트입니다. 프로젝트에 대한 자세한 내용은 GitHub의 해당 README 파일 또는 본 문서의 [Athena 외부 Hive 메타스토어 커넥터 수정](datastores-hive-reference-implementation.md) 주제를 참조하세요. **Lambda 함수 코드를 복제하고 빌드하려면** 1. Athena 참조 구현을 복제하려면 다음 명령을 입력합니다. ``` git clone https://github.com/awslabs/aws-athena-hive-metastore ``` 1. 다음 명령을 실행하여 Lambda 함수를 위한 `.jar` 파일을 빌드합니다. ``` mvn clean install ``` 프로젝트가 성공적으로 빌드되면 다음 `.jar` 파일이 프로젝트의 대상 폴더에 생성됩니다. `hms-lambda-func-1.0-SNAPSHOT-withdep.jar` 다음 단원에서는 AWS Lambda 콘솔을 사용하여 이 파일을 Amazon Web Services 계정에 업로드합니다. ## AWS Lambda 콘솔에서 Lambda 함수 생성 및 구성 이 단원에서는 AWS Lambda 콘솔을 사용하여 기존 IAM 실행 역할을 사용하는 함수를 생성합니다. 함수에 대한 VPC를 구성한 후 함수 코드를 업로드하고 함수의 환경 변수를 구성합니다. ### Lambda 함수 생성 이 단원에서는 AWS Lambda 콘솔에서 기존 IAM 실행 역할을 사용하는 함수를 생성합니다. **기존 IAM 역할을 사용하는 Lambda 함수를 만들려면** 1. AWS Management Console에 로그인하고 [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/)에서 AWS Lambda 콘솔을 엽니다. 1. 탐색 창에서 **함수**를 선택합니다. 1. **함수 생성**을 선택합니다. 1. **새로 작성**을 선택합니다. 1. **함수 이름(Function name)**에 Lambda 함수의 이름(예: **EHMSBasedLambda**)을 입력합니다. 1. **런타임(Runtime)**에서 **Java 8**을 선택합니다. 1. **권한(Permissions)**에서 **기본 실행 역할 변경(Change default execution role)**을 확장합니다. 1. **실행 역할**에서 **기존 역할 사용**을 선택합니다. 1. **기존 역할(Existing role)**에서 Lambda 함수가 Athena에 사용할 IAM 역할을 선택합니다(이 예제에서는 `AthenaLambdaExecutionRole`이라는 역할 사용). 1. **Advanced settings(고급 설정)**를 확장합니다. 1. **네트워크 활성화(Enable Network)**를 선택합니다. 1. **VPC**에서 함수가 액세스할 VPC를 선택합니다. 1. **서브넷(Subnets)**에서 Lambda가 사용할 VPC 서브넷을 선택합니다. 1. **보안 그룹(Security groups)**에서 Lambda가 사용할 VPC 보안 그룹을 선택합니다. 1. **함수 생성**을 선택합니다. AWS Lambda 콘솔에서 함수의 구성 페이지를 열고 함수 생성을 시작합니다. ### 코드 업로드 및 Lambda 함수 구성 콘솔에서 함수가 성공적으로 생성되었음을 알리면 함수 코드를 업로드하고 환경 변수를 구성할 준비가 된 것입니다. **Lambda 함수 코드를 업로드하고 해당 환경 변수를 구성하려면** 1. Lambda 콘솔에서 지정한 함수 페이지의 **코드(Code)** 탭에 있는지 확인합니다. 1. **코드 소스(Code source)**에서 **다음에서 업로드(Upload from)**를 선택한 다음 **.zip 또는 .jar 파일(.zip or .jar file)**을 선택합니다. 1. 이전에 생성한 `hms-lambda-func-1.0-SNAPSHOT-withdep.jar` 파일을 업로드합니다. 1. Lambda 함수 페이지에서 **구성(Configuration)** 탭을 선택합니다. 1. 왼쪽의 창에서 **환경 변수(Environment variables)**를 선택합니다. 1. **환경 변수** 섹션에서 **편집**을 선택합니다. ![\[편집(Edit)을 선택해 Lambda 함수의 환경 변수를 편집합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connect-data-source-hive-existing-iam-role-5.png) 1. **환경 변수 편집(Edit environment variables)** 페이지에서 **환경 변수 추가(Add environment variable)** 옵션을 사용하여 다음 환경 변수 키 및 값을 추가합니다. + **HMS\$1URIS** – 다음 구문을 사용하여 포트 9083에서 Thrift 프로토콜을 사용하는 Hive 메타스토어 호스트의 URI를 입력합니다. ``` thrift://:9083 ``` + **SPILL\$1LOCATION** – Lambda 함수 응답 크기가 4MB를 초과하는 경우 분산 메타데이터를 보관할 Amazon Web Services 계정의 Amazon S3 위치를 지정합니다. ![\[Lambda 함수 환경 변수의 값 지정\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connect-data-source-hive-existing-iam-role-6.png) 1. **저장**을 선택합니다. 이제 Lambda 함수를 사용하여 Hive 메타스토어에 연결하도록 Athena를 구성할 준비가 되었습니다. 단계는 [배포된 Hive 메타스토어 커넥터를 사용하도록 Athena 구성](connect-data-source-hive-existing-lambda.md)를 참조하세요. # 배포된 Hive 메타스토어 커넥터를 사용하도록 Athena 구성 `AthenaHiveMetastoreFunction`과 같은 Lambda 데이터 원본 커넥터를 계정에 배포한 후 이를 사용하도록 Athena를 구성할 수 있습니다. 이를 위해 Athena 쿼리에 사용할 외부 Hive 메타스토어를 참조하는 데이터 원본 이름을 생성합니다. **기존 Lambda 함수를 사용하여 Hive 메타스토어에 Athena 연결** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. **데이터 소스 및 카탈로그**를 선택합니다. 1. **데이터 소스 및 카탈로그** 페이지에서 **데이터 소스 생성**을 선택합니다. 1. **데이터 원본 선택(Choose data sources)** 페이지에서 **데이터 원본(Data source)**에 대해 **S3 - Apache Hive 메타스토어(S3 - Apache Hive metastore)**를 선택합니다. 1. **다음**을 선택합니다. 1. **데이터 원본 세부 정보(Data source details)** 섹션의 **데이터 원본 이름(Data source name)**에 Athena에서 데이터 원본을 쿼리할 때 SQL 문에 사용할 이름을 입력합니다(예: `MyHiveMetastore`). 이름은 127자까지 입력할 수 있으며 계정 내에서 고유해야 합니다. 생성 후에는 변경할 수 없습니다. 유효한 문자는 a-z, A-Z, 0-9, \$1(밑줄), @(앰퍼샌드) 및 -(하이픈)입니다. `awsdatacatalog`, `hive`, `jmx`, `system` 이름은 Athena에 예약되어 있으므로 데이터 원본 이름에 사용할 수 없습니다. 1. **연결 세부 정보** 섹션에서, **Lambda 함수 선택 또는 입력** 상자를 사용해 방금 만든 함수의 이름을 선택합니다. Lambda 함수의 ARN이 표시됩니다. 1. (선택 사항) **태그(Tags)**에 대해 이 데이터 원본과 연결할 키-값 페어를 추가합니다. 태그에 대한 자세한 내용은 [Athena 리소스 태깅](tags.md) 섹션을 참조하세요. 1. **다음**을 선택합니다. 1. **검토 및 생성** 페이지에서 데이터 원본 세부 정보를 검토한 다음 **데이터 원본 생성**을 선택합니다. 1. 데이터 원본 페이지의 **데이터 원본 세부 정보** 섹션에는 새 커넥터에 대한 정보가 표시됩니다. 이제 Athena에서는 지정한 **데이터 원본 이름(Data source name)**을 사용하여 SQL 쿼리에서 Hive 메타스토어를 참조할 수 있습니다. SQL 쿼리에서 다음 예제 구문을 사용하여 `ehms-catalog`를 앞에서 지정한 데이터 원본 이름으로 바꿉니다. ``` SELECT * FROM ehms-catalog.CustomerData.customers ``` 1. 생성한 데이터 원본을 보거나 편집하거나 삭제하려면 [데이터 소스 관리](data-sources-managing.md) 단원을 참조하세요. # 외부 Hive 메타스토어 쿼리에서 카탈로그 이름 생략 외부 Hive 메타스토어에서 DML 및 DDL 쿼리 실행 시, 쿼리 편집기에서 카탈로그 이름을 선택한 경우 해당 카탈로그 이름을 생략하여 쿼리 구문을 간소화할 수 있습니다. 이 기능에는 특정 제한 사항이 적용됩니다. ## DML 문 **등록된 카탈로그를 사용하여 쿼리를 실행하려면** 1. 다음 예와 같이 `[[data_source_name].database_name].table_name` 구문을 사용하여 데이터베이스 앞에 데이터 원본 이름을 배치할 수 있습니다. ``` select * from "hms-catalog-1".hms_tpch.customer limit 10; ``` 1. 사용하려는 데이터 원본이 쿼리 편집기에서 이미 선택되어 있으면 다음 예와 같이 쿼리에서 해당 이름을 생략할 수 있습니다. ``` select * from hms_tpch.customer limit 10: ``` ![\[기본 데이터 원본을 사용하는 DML 쿼리\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/datastores-hive-default-catalog-2.png) 1. 쿼리에서 여러 데이터 원본을 사용하는 경우 기본 데이터 원본 이름만 생략할 수 있으며 기본이 아닌 데이터 원본에 대해 전체 이름을 지정해야 합니다. 예를 들어 쿼리 편집기에서 `AwsDataCatalog`가 기본 데이터 원본으로 선택되었다고 가정합니다. 다음 쿼리 발췌문의 `FROM` 문은 처음 두 데이터 원본 이름을 완전히 정규화하지만 세 번째 데이터 원본의 이름은 AWS Glue 데이터 카탈로그에 있으므로 생략합니다. ``` ... FROM ehms01.hms_tpch.customer, "hms-catalog-1".hms_tpch.orders, hms_tpch.lineitem ... ``` ## DDL 문 다음 Athena DDL 문은 카탈로그 이름 접두사를 지원합니다. 다른 DDL 문의 카탈로그 이름 접두사로 인해 구문 오류가 발생합니다. ``` SHOW TABLES [IN [catalog_name.]database_name] ['regular_expression'] SHOW TBLPROPERTIES [[catalog_name.]database_name.]table_name [('property_name')] SHOW COLUMNS IN [[catalog_name.]database_name.]table_name SHOW PARTITIONS [[catalog_name.]database_name.]table_name SHOW CREATE TABLE [[catalog_name.][database_name.]table_name DESCRIBE [EXTENDED | FORMATTED] [[catalog_name.][database_name.]table_name [PARTITION partition_spec] [col_name ( [.field_name] | [.'$elem$'] | [.'$key$'] | [.'$value$'] )] ``` DML 문과 마찬가지로 쿼리 편집기에서 데이터 원본과 데이터베이스를 선택할 때 쿼리에서 데이터 원본과 데이터베이스 접두사를 생략할 수 있습니다. 다음 이미지에서는 `hms-catalog-1` 데이터 원본 및 `hms_tpch` 데이터베이스가 쿼리 편집기에서 선택되어 있습니다. `show create table customer` 문은 `hms-catalog-1` 접두사와 `hms_tpch` 데이터베이스 이름이 쿼리 자체에서 생략된 경우에도 성공합니다. ![\[기본 카탈로그를 사용하는 DDL 문.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/datastores-hive-default-catalog-4.png) ## JDBC 연결 문자열에 기본 데이터 원본 지정 Athena JDBC 드라이버를 사용하여 Athena를 외부 Hive 메타스토어에 연결할 때 `Catalog` 파라미터를 사용하여 [SQL workbench](https://www.sql-workbench.eu/index.html)와 같은 SQL 편집기에서 연결 문자열의 기본 데이터 원본 이름을 지정할 수 있습니다. **참고** 최신 Athena JDBC 드라이버를 다운로드하려면 [Athena와 함께 JDBC 드라이버 사용](https://docs.aws.amazon.com/athena/latest/ug/connect-with-jdbc.html)을 참조하세요. 다음 연결 문자열은 기본 데이터 원본 *hms-catalog-name*을 지정합니다. ``` jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://amzn-s3-demo-bucket/lambda/results/;Workgroup=AmazonAthenaPreviewFunctionality;Catalog=hms-catalog-name; ``` 다음 이미지는 SQL Workbench에 구성된 샘플 JDBC 연결 URL을 보여줍니다. ![\[SQL Workbench에서 JDBC 연결 URL 구성.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/datastores-hive-default-catalog-jdbc-1.jpg) # Hive 뷰 작업 Athena를 사용하여 외부 Apache Hive 메타스토어의 기존 뷰를 쿼리할 수 있습니다. Athena는 원본 뷰를 변경하거나 변환을 저장하지 않고 런타임에서 즉석으로 뷰를 변환합니다. 예를 들어 다음과 같이 Athena에서 지원되지 않는 구문(`LATERAL VIEW explode()` 등)을 사용하는 Hive 뷰가 있다고 가정합니다. ``` CREATE VIEW team_view AS SELECT team, score FROM matches LATERAL VIEW explode(scores) m AS score ``` Athena는 Hive 뷰 쿼리 문자열을 다음과 같이 Athena가 실행할 수 있는 문으로 변환합니다. ``` SELECT team, score FROM matches CROSS JOIN UNNEST(scores) AS m (score) ``` 외부 Hive 메타스토어를 Athena에 연결하는 방법에 대한 자세한 내용은 [외부 Hive 메타스토어 사용](connect-to-data-source-hive.md) 단원을 참조하세요. ## 고려 사항 및 제한 사항 Athena에서 Hive 뷰를 쿼리할 때 다음 사항을 고려해 보세요. + Athena는 Hive 뷰 생성을 지원하지 않습니다. 외부 Hive 메타스토어에 Hive 뷰를 만든 다음 Athena에서 쿼리할 수 있습니다. + Athena는 Hive 뷰에 대한 사용자 지정 UDF를 지원하지 않습니다. + Athena 콘솔의 알려진 문제로 인해 Hive 뷰는 뷰 목록 대신 테이블 목록 아래에 표시됩니다. + 변환 과정은 자동이지만 특정 Hive 함수는 Hive 뷰에 대해 지원되지 않거나 특별한 처리가 필요합니다. 자세한 내용은 다음 섹션을 참조하세요. ## Hive 함수 지원 제한 이 섹션에서는 Athena가 Hive 뷰에 대해 지원하지 않거나 특별한 처리가 필요한 Hive 함수에 대해 설명합니다. 현재 Athena는 주로 Hive 2.2.0의 함수를 지원하므로 상위 버전(예: Hive 4.0.0)에서만 사용할 수 있는 함수는 사용할 수 없습니다. Hive 함수의 전체 목록은 [Hive 언어 설명서 UDF](https://cwiki.apache.org/confluence/display/hive/languagemanual+udf)를 참조하십시오. ### 집계 함수 #### 특별한 처리가 필요한 집계 함수 Hive 뷰에 대한 다음 집계 함수는 특별한 처리가 필요합니다. + **Avg** - `avg(INT i)` 대신 `avg(CAST(i AS DOUBLE))`을 사용하세요. #### 지원되지 않는 집계 함수 다음 Hive 집계 함수는 Athena에서 Hive 뷰에 대해 지원되지 않습니다. ``` covar_pop histogram_numeric ntile percentile percentile_approx ``` `regr_count`, `regr_r2`, `regr_sxx`와 같은 회귀 함수는 Athena에서 Hive 뷰에 대해 지원되지 않습니다. ### 지원되지 않는 날짜 함수 다음 Hive 날짜 함수는 Athena에서 Hive 뷰에 대해 지원되지 않습니다. ``` date_format(date/timestamp/string ts, string fmt) day(string date) dayofmonth(date) extract(field FROM source) hour(string date) minute(string date) month(string date) quarter(date/timestamp/string) second(string date) weekofyear(string date) year(string date) ``` ### 지원되지 않는 마스킹 함수 `mask()`, `mask_first_n()`와 같은 Hive 마스킹 함수는 Athena에서 Hive 뷰에 대해 지원되지 않습니다. ### 기타 함수 #### 특별한 처리가 필요한 기타 함수 Hive 뷰에 대한 다음 기타 함수는 특별한 처리가 필요합니다. + **md5** - Athena는 `md5(binary)`를 지원하지만 `md5(varchar)`는 지원하지 않습니다. + **Explode** - Athena는 다음 구문으로 사용되는 경우 `explode`를 지원합니다. ``` LATERAL VIEW [OUTER] EXPLODE() ``` + **Posexplode** - Athena는 다음 구문으로 사용되는 경우 `posexplode`를 지원합니다. ``` LATERAL VIEW [OUTER] POSEXPLODE() ``` `(pos, val)` 출력에서 Athena는 `pos` 열을 `BIGINT`로 취급합니다. 이 때문에 오래된 뷰를 피하기 위해 `pos` 열을 `BIGINT`로 캐스팅해야 할 수 있습니다. 다음 예는 이 기법을 보여 줍니다. ``` SELECT CAST(c AS BIGINT) AS c_bigint, d FROM table LATERAL VIEW POSEXPLODE() t AS c, d ``` #### 지원되지 않는 기타 함수 다음 Hive 함수는 Athena에서 Hive 뷰에 대해 지원되지 않습니다. ``` aes_decrypt aes_encrypt current_database current_user inline java_method logged_in_user reflect sha/sha1/sha2 stack version ``` ### 연산자 #### 특별한 처리가 필요한 연산자 Hive 뷰에 대한 다음 연산자는 특별한 처리가 필요합니다. + **모드(Mod) 연산자(%)** - `DOUBLE` 형식이 암시적으로 `DECIMAL(x,y)`로 캐스팅되기 때문에 다음 구문은 View is stale 오류 메시지를 반환할 수 있습니다. ``` a_double % 1.0 AS column ``` 이 문제를 해결하려면 다음 예제와 같이 `CAST`를 사용하세요. ``` CAST(a_double % 1.0 as DOUBLE) AS column ``` + **나누기 연산자(/)** - Hive에서 `int`를 `int`로 나누면 `double`을 생성합니다. Athena에서는 동일한 연산이 잘린 `int`을 생성합니다. #### 지원되지 않는 연산자 Athena는 다음 연산자를 Hive 뷰에 대해 지원하지 않습니다. **\$1A** – 비트 `NOT` **A ^ b** – 비트 `XOR` **A & b** – 비트 `AND` **A \$1 b** – 비트 `OR` **A <=> b** – null이 아닌 피연산자에 대해 같음(`=`) 연산자와 동일한 결과를 반환합니다. 둘 다 `NULL`인 경우 `TRUE`를, 둘 중 하나가 `NULL`인 경우 `FALSE`를 반환합니다. ### 문자열 함수 #### 특별한 처리가 필요한 문자열 함수 Hive 뷰에 대한 다음 Hive 문자열 함수는 특별한 처리가 필요합니다. + **chr(bigint\$1double a)** – Hive는 음수 인수를 허용하지만 Athena는 그렇지 않습니다. + **instr(string str, string substr)** – `instr` 함수에 대한 Athena 매핑이 `INT` 대신 `BIGINT`를 반환하므로 다음 구문을 사용하세요. ``` CAST(instr(string str, string substr) as INT) ``` 이 단계가 없으면 뷰가 오래된 것으로 간주됩니다. + **length(string a)** – `length` 함수에 대한 Athena 매핑이 `INT` 대신 `BIGINT`를 반환하므로 뷰가 오래된 것으로 간주되지 않도록 다음 구문을 사용하세요. ``` CAST(length(string str) as INT) ``` #### 지원되지 않는 문자열 함수 다음 Hive 문자열 함수는 Athena에서 Hive 뷰에 대해 지원되지 않습니다. ``` ascii(string str) character_length(string str) decode(binary bin, string charset) encode(string src, string charset) elt(N int,str1 string,str2 string,str3 string,...) field(val T,val1 T,val2 T,val3 T,...) find_in_set(string str, string strList) initcap(string A) levenshtein(string A, string B) locate(string substr, string str[, int pos]) octet_length(string str) parse_url(string urlString, string partToExtract [, string keyToExtract]) printf(String format, Obj... args) quote(String text) regexp_extract(string subject, string pattern, int index) repeat(string str, int n) sentences(string str, string lang, string locale) soundex(string A) space(int n) str_to_map(text[, delimiter1, delimiter2]) substring_index(string A, string delim, int count) ``` ### 지원되지 않는 XPath 함수 `xpath`, `xpath_short`, `xpath_int`와 같은 Hive XPath 함수는 Athena에서 Hive 뷰에 대해 지원되지 않습니다. ## 문제 해결 Athena에서 Hive 뷰를 사용할 때 다음과 같은 문제가 발생할 수 있습니다. + **View ** is stale** – 이 메시지는 일반적으로 Hive와 Athena 뷰 간의 형식 불일치를 나타냅니다. [Hive LanguageManual UDF](https://cwiki.apache.org/confluence/display/hive/languagemanual+udf)와 [Presto functions and operators](https://prestodb.io/docs/current/functions.html)(Presto 함수 및 연산자) 설명서에서 동일한 함수가 서로 다른 특징을 갖는 경우 일치하지 않는 데이터 형식을 캐스팅해 보세요. + **Function not registered** – Athena가 현재 함수를 지원하지 않습니다. 자세한 내용은 이 문서 앞부분의 정보를 참조하십시오. # Hive 메타스토어와 함께 AWS CLI 사용 `aws athena` CLI 명령을 사용하여 Athena에서 사용하는 Hive 메타스토어 데이터 카탈로그를 관리할 수 있습니다. Athena에서 사용할 카탈로그를 하나 이상 정의한 후에는 `aws athena` DDL 및 DML 명령에서 해당 카탈로그를 참조할 수 있습니다. ## AWS CLI를 사용하여 Hive 메타스토어 카탈로그 관리 ### 카탈로그 등록: Create-data-catalog 데이터 카탈로그를 등록하려면 `create-data-catalog` 명령을 사용합니다. `name` 파라미터를 사용하여 카탈로그에 사용할 이름을 지정합니다. Lambda 함수의 ARN을 `parameters` 인수의 `metadata-function` 옵션에 전달합니다. 새 카탈로그에 대한 태그를 만들려면 하나 이상의 공백으로 구분된 `Key=key,Value=value` 인수 페어와 함께 `tags` 파라미터를 사용합니다. 다음 예제에서는 `hms-catalog-1`이라는 Hive 메타스토어 카탈로그를 등록합니다. 명령은 가독성을 위해 형식이 지정되었습니다. ``` $ aws athena create-data-catalog --name "hms-catalog-1" --type "HIVE" --description "Hive Catalog 1" --parameters "metadata-function=arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3,sdk-version=1.0" --tags Key=MyKey,Value=MyValue --region us-east-1 ``` ### 카탈로그 세부 정보 표시: Get-data-catalog 카탈로그의 세부 정보를 표시하려면 다음 예제와 같이 카탈로그 이름을 `get-data-catalog` 명령에 전달합니다. ``` $ aws athena get-data-catalog --name "hms-catalog-1" --region us-east-1 ``` 다음 샘플 결과는 JSON 형식입니다. ``` { "DataCatalog": { "Name": "hms-catalog-1", "Description": "Hive Catalog 1", "Type": "HIVE", "Parameters": { "metadata-function": "arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3", "sdk-version": "1.0" } } } ``` ### 등록된 카탈로그 나열: List-data-catalogs 등록된 카탈로그를 나열하려면 다음 예제와 같이 `list-data-catalogs` 명령을 사용하고 필요에 따라 리전을 지정합니다. 나열된 카탈로그에는 항상 AWS Glue가 포함되어 있습니다. ``` $ aws athena list-data-catalogs --region us-east-1 ``` 다음 샘플 결과는 JSON 형식입니다. ``` { "DataCatalogs": [ { "CatalogName": "AwsDataCatalog", "Type": "GLUE" }, { "CatalogName": "hms-catalog-1", "Type": "HIVE", "Parameters": { "metadata-function": "arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3", "sdk-version": "1.0" } } ] } ``` ### 카탈로그 업데이트: Update-data-catalog 데이터 카탈로그를 업데이트하려면 다음 예제와 같이 `update-data-catalog` 명령을 사용합니다. 명령은 가독성을 위해 형식이 지정되었습니다. ``` $ aws athena update-data-catalog --name "hms-catalog-1" --type "HIVE" --description "My New Hive Catalog Description" --parameters "metadata-function=arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-new,sdk-version=1.0" --region us-east-1 ``` ### 카탈로그 삭제: Delete-data-catalog 데이터 카탈로그를 삭제하려면 다음 예제와 같이 `delete-data-catalog` 명령을 사용합니다. ``` $ aws athena delete-data-catalog --name "hms-catalog-1" --region us-east-1 ``` ### 데이터베이스 세부 정보 표시: Get-database 데이터베이스의 세부 정보를 표시하려면 다음 예제와 같이 카탈로그 및 데이터베이스의 이름을 `get-database` 명령에 전달합니다. ``` $ aws athena get-database --catalog-name hms-catalog-1 --database-name mydb ``` 다음 샘플 결과는 JSON 형식입니다. ``` { "Database": { "Name": "mydb", "Description": "My database", "Parameters": { "CreatedBy": "Athena", "EXTERNAL": "TRUE" } } } ``` ### 카탈로그의 데이터베이스 나열: List-databases 카탈로그의 데이터베이스를 나열하려면 다음 예제와 같이 `list-databases` 명령을 사용하고 필요에 따라 리전을 지정합니다. ``` $ aws athena list-databases --catalog-name AwsDataCatalog --region us-west-2 ``` 다음 샘플 결과는 JSON 형식입니다. ``` { "DatabaseList": [ { "Name": "default" }, { "Name": "mycrawlerdatabase" }, { "Name": "mydatabase" }, { "Name": "sampledb", "Description": "Sample database", "Parameters": { "CreatedBy": "Athena", "EXTERNAL": "TRUE" } }, { "Name": "tpch100" } ] } ``` ### 테이블 세부 정보 표시: Get-table-metadata 열 이름 및 데이터 형식을 포함하여 테이블의 메타데이터를 표시하려면 다음 예제와 같이 카탈로그 이름, 데이터베이스 이름 및 테이블 이름을 `get-table-metadata` 명령에 전달합니다. ``` $ aws athena get-table-metadata --catalog-name AwsDataCatalog --database-name mydb --table-name cityuseragent ``` 다음 샘플 결과는 JSON 형식입니다. ``` { "TableMetadata": { "Name": "cityuseragent", "CreateTime": 1586451276.0, "LastAccessTime": 0.0, "TableType": "EXTERNAL_TABLE", "Columns": [ { "Name": "city", "Type": "string" }, { "Name": "useragent1", "Type": "string" } ], "PartitionKeys": [], "Parameters": { "COLUMN_STATS_ACCURATE": "false", "EXTERNAL": "TRUE", "inputformat": "org.apache.hadoop.mapred.TextInputFormat", "last_modified_by": "hadoop", "last_modified_time": "1586454879", "location": "s3://amzn-s3-demo-bucket/", "numFiles": "1", "numRows": "-1", "outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat", "rawDataSize": "-1", "serde.param.serialization.format": "1", "serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe", "totalSize": "61" } } } ``` ### 데이터베이스의 모든 테이블에 대한 메타데이터 표시: List-table-metadata 데이터베이스의 모든 테이블에 대한 메타데이터를 표시하려면 카탈로그 이름 및 데이터베이스 이름을 `list-table-metadata` 명령에 전달합니다. `list-table-metadata` 명령은 테이블 이름을 지정하지 않는다는 점을 제외하면 `get-table-metadata` 명령과 유사합니다. 결과 수를 제한하려면 다음 예제와 같이 `--max-results` 옵션을 사용할 수 있습니다. ``` $ aws athena list-table-metadata --catalog-name AwsDataCatalog --database-name sampledb --region us-east-1 --max-results 2 ``` 다음 샘플 결과는 JSON 형식입니다. ``` { "TableMetadataList": [ { "Name": "cityuseragent", "CreateTime": 1586451276.0, "LastAccessTime": 0.0, "TableType": "EXTERNAL_TABLE", "Columns": [ { "Name": "city", "Type": "string" }, { "Name": "useragent1", "Type": "string" } ], "PartitionKeys": [], "Parameters": { "COLUMN_STATS_ACCURATE": "false", "EXTERNAL": "TRUE", "inputformat": "org.apache.hadoop.mapred.TextInputFormat", "last_modified_by": "hadoop", "last_modified_time": "1586454879", "location": "s3://amzn-s3-demo-bucket/", "numFiles": "1", "numRows": "-1", "outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat", "rawDataSize": "-1", "serde.param.serialization.format": "1", "serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe", "totalSize": "61" } }, { "Name": "clearinghouse_data", "CreateTime": 1589255544.0, "LastAccessTime": 0.0, "TableType": "EXTERNAL_TABLE", "Columns": [ { "Name": "location", "Type": "string" }, { "Name": "stock_count", "Type": "int" }, { "Name": "quantity_shipped", "Type": "int" } ], "PartitionKeys": [], "Parameters": { "EXTERNAL": "TRUE", "inputformat": "org.apache.hadoop.mapred.TextInputFormat", "location": "s3://amzn-s3-demo-bucket/", "outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat", "serde.param.serialization.format": "1", "serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe", "transient_lastDdlTime": "1589255544" } } ], "NextToken": "eyJsYXN0RXZhbHVhdGVkS2V5Ijp7IkhBU0hfS0VZIjp7InMiOiJ0Ljk0YWZjYjk1MjJjNTQ1YmU4Y2I5OWE5NTg0MjFjYTYzIn0sIlJBTkdFX0tFWSI6eyJzIjoiY2xlYXJpbmdob3VzZV9kYXRhIn19LCJleHBpcmF0aW9uIjp7InNlY29uZHMiOjE1ODkzNDIwMjIsIm5hbm9zIjo2NTUwMDAwMDB9fQ==" } ``` ## DDL 및 DML 문 실행 AWS CLI를 사용하여 DDL 및 DML 문을 실행할 때 다음 두 가지 방법 중 하나로 Hive 메타스토어 카탈로그의 이름을 전달할 수 있습니다. + 이를 지원하는 문으로 직접 전달 + `--query-execution-context` `Catalog` 파라미터를 사용하여 전달 ### DDL 문 다음 예제에서는 `show create table` DDL 문의 일부로 카탈로그 이름을 직접 전달합니다. 명령은 가독성을 위해 형식이 지정되었습니다. ``` $ aws athena start-query-execution --query-string "show create table hms-catalog-1.hms_tpch_partitioned.lineitem" --result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results" ``` 다음 예제 DDL `show create table` 문은 `--query-execution-context`의 `Catalog` 파라미터를 사용하여 Hive 메타스토어 카탈로그 이름 `hms-catalog-1`을 전달합니다. 명령은 가독성을 위해 형식이 지정되었습니다. ``` $ aws athena start-query-execution --query-string "show create table lineitem" --query-execution-context "Catalog=hms-catalog-1,Database=hms_tpch_partitioned" --result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results" ``` ### DML 문 다음 예제 DML `select` 문은 카탈로그 이름을 쿼리에 직접 전달합니다. 명령은 가독성을 위해 형식이 지정되었습니다. ``` $ aws athena start-query-execution --query-string "select * from hms-catalog-1.hms_tpch_partitioned.customer limit 100" --result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results" ``` 다음 예제 DML `select` 문은 `--query-execution-context`의 `Catalog` 파라미터를 사용하여 Hive 메타스토어 카탈로그 이름 `hms-catalog-1`을 전달합니다. 명령은 가독성을 위해 형식이 지정되었습니다. ``` $ aws athena start-query-execution --query-string "select * from customer limit 100" --query-execution-context "Catalog=hms-catalog-1,Database=hms_tpch_partitioned" --result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results" ``` # Athena 외부 Hive 메타스토어 커넥터 수정 특별한 요구 사항이 있는 경우 외부 Hive 메타스토어용 Athena 커넥터를 용도에 맞게 수정할 수 있습니다. Athena는 GitHub.com에서 외부 Hive 메타스토어용 커넥터의 참조 구현을 제공합니다([https://github.com/awslabs/aws-athena-hive-metastore](https://github.com/awslabs/aws-athena-hive-metastore)). 대부분의 사용 사례는 참조 구현을 수정할 필요가 없습니다. 그러나 필요한 경우 소스 코드를 수정하고 직접 아티팩트를 빌드할 수 있습니다. 참조 구현은 다음과 같은 모듈이 있는 [Apache Maven](https://maven.apache.org/) 프로젝트입니다. + `hms-service-api` – Lambda 함수와 Athena 서비스 클라이언트 간의 API 작업을 포함합니다. 이러한 API 작업은 `HiveMetaStoreService` 인터페이스에 정의되어 있습니다. 이는 서비스 계약이므로 이 모듈에서는 아무 것도 변경하지 마세요. + `hms-lambda-handler` – 모든 Hive 메타스토어 API 호출을 처리하는 기본 Lambda 핸들러 집합입니다. 클래스 `MetadataHandler`는 모든 API 호출의 디스패처입니다. 이 패키지는 변경할 필요가 없습니다. + `hms-lambda-func` – 다음 구성 요소가 있는 예제 Lambda 함수입니다. + `HiveMetaStoreLambdaFunc` – `MetadataHandler`를 확장하는 예제 Lambda 함수입니다. + `ThriftHiveMetaStoreClient` – Hive 메타스토어와 통신하는 Thrift 클라이언트입니다. 이 클라이언트는 Hive 2.3.0용으로 작성되었습니다. 다른 Hive 버전을 사용하는 경우, 응답 객체가 호환되도록 이 클래스를 업데이트해야 할 수 있습니다. + `ThriftHiveMetaStoreClientFactory` – Lambda 함수의 동작을 제어합니다. 예를 들어 `getHandlerProvider()` 메서드를 재정의하여 자체 핸들러 공급자 집합을 제공할 수 있습니다. + `hms.properties` – Lambda 함수를 구성합니다. 대부분의 경우 다음 두 속성만 업데이트가 필요합니다. + `hive.metastore.uris` - `thrift://:9083` 형식의 Hive 메타스토어의 URI입니다. + `hive.metastore.response.spill.location`: 응답 객체의 크기가 지정된 임계값(예: 4MB)을 초과하는 경우 응답 객체를 저장할 Amazon S3 위치입니다. 임계값은 `hive.metastore.response.spill.threshold` 속성에 정의됩니다. 기본값을 변경하지 않는 것이 좋습니다. **참고** 이 두 속성은 [Lambda 환경 변수](https://docs.aws.amazon.com/lambda/latest/dg/env_variables.html) `HMS_URIS` 및 `SPILL_LOCATION`에 의해 재정의될 수 있습니다. 다른 Hive 메타스토어 또는 유출 위치에서 Lambda 함수를 사용하려는 경우 이 함수의 소스 코드를 다시 컴파일하는 대신 이러한 변수를 사용합니다. + `hms-lambda-layer` – `hms-service-api`, `hms-lambda-handler` 및 해당 종속 항목을 `.zip` 파일에 넣는 Maven 어셈블리 프로젝트입니다. `.zip` 파일은 여러 Lambda 함수에서 사용할 수 있도록 Lambda 계층으로 등록됩니다. + `hms-lambda-rnp` - Lambda 함수의 응답을 기록한 다음 이를 사용하여 응답을 재생합니다. 이 모델을 사용하여 테스트용 Lambda 응답을 시뮬레이션할 수 있습니다. ## 아티팩트 직접 구축 소스 코드를 수정한 후에는 직접 아티팩트를 빌드하고 Amazon S3 위치에 아티팩트를 업로드할 수 있습니다. 아티팩트를 빌드하기 전에 `hms-lambda-func` 모듈의 `hms.properties` 파일에서 `hive.metastore.uris` 및 `hive.metastore.response.spill.location` 속성을 업데이트합니다. 아티팩트를 빌드하려면 Apache Maven이 설치되어 있어야 하며 `mvn install` 명령을 실행해야 합니다. 그러면 `hms-lambda-layer` 모듈에서 `target`이라는 출력 폴더에 계층 `.zip` 파일이 생성되고 `hms-lambd-func` 모듈에서 Lambda 함수 `.jar` 파일이 생성됩니다. # 데이터 소스 관리 Athena 콘솔의 **데이터 소스 및 카탈로그** 페이지를 사용하여 생성한 데이터 소스를 관리할 수 있습니다. **데이터 원본을 보려면** 1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home)에서 Athena 콘솔을 엽니다. 1. 콘솔 탐색 창이 표시되지 않으면 왼쪽의 확장 메뉴를 선택합니다. ![\[확장 메뉴를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/nav-pane-expansion.png) 1. 탐색 창에서 **데이터 소스 및 카탈로그**를 선택합니다. 1. 데이터 원본 목록에서 보려는 데이터 원본의 이름을 선택합니다. **참고** **Data source name**(데이터 소스 이름) 열의 항목은 [ListDataCatalogs](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDataCatalogs.html) API 작업 및 [list-data-catalogs](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/list-data-catalogs.html) CLI 명령의 출력에 해당합니다. **데이터 원본을 편집하려면** 1. **데이터 소스 및 카탈로그** 페이지에서 다음을 수행합니다. + 카탈로그 이름 옆에 있는 버튼을 선택한 다음 **작업(Actions)**, **편집(Edit)**을 선택합니다. + 데이터 원본의 이름을 선택합니다. 세부 정보 페이지에서 **작업(Actions)**, **편집(Edit)**을 선택합니다. 1. **편집(Edit)** 페이지에서 데이터 원본에 대해 다른 Lambda 함수를 선택하거나, 설명을 변경하거나, 사용자 정의 태그를 추가할 수 있습니다. 태그에 대한 자세한 내용은 [Athena 리소스 태깅](tags.md) 섹션을 참조하세요. 1. **Save**(저장)를 선택합니다. 1. **AwsDataCatalog** 데이터 원본을 편집하려면 **AwsDataCatalog** 링크를 선택하여 세부 정보 페이지를 엽니다. 그런 다음 세부 정보 페이지에서 카탈로그를 편집할 수 있는 AWS Glue 콘솔에 대한 링크를 선택합니다. **데이터 원본 공유** 데이터 원본 공유에 대한 자세한 내용을 보려면 다음 링크를 방문하세요. + 비 Hive Lambda 기반 데이터 원본은 [교차 계정 페더레이션 쿼리 활성화](xacct-fed-query-enable.md) 섹션을 참조하세요. + AWS Glue Data Catalog는 [AWS Glue 데이터 카탈로그에 대한 크로스 계정 액세스 구성](security-iam-cross-account-glue-catalog-access.md) 섹션을 참조하세요. **데이터 소스를 삭제하기** 1. **데이터 소스 및 카탈로그** 페이지에서 다음을 수행합니다. + 카탈로그 이름 옆에 있는 버튼을 선택하고 **작업(Actions)**, **삭제(Delete)**를 선택합니다. + 데이터 원본의 이름을 선택한 다음 세부 정보 페이지에서 **작업(Actions)**, **삭제(Delete)**를 선택합니다. **참고** **AwsDataCatalog**는 계정의 기본 데이터 원본이며 삭제할 수 없습니다. 데이터 원본을 삭제하면 해당 데이터 카탈로그, 테이블 및 뷰가 쿼리 편집기에서 제거된다는 경고가 표시됩니다. 데이터 원본을 사용한 저장된 쿼리가 더 이상 Athena에서 실행되지 않습니다. 1. 삭제를 확인하려면 데이터 원본의 이름을 입력한 다음 **삭제(Delete)**를 선택합니다.