# 사용 가능한 데이터 소스 커넥터
<a name="connectors-available"></a>

이 섹션에는 Athena 외부의 다양한 데이터 원본을 쿼리하는 데 사용할 수 있는 사전 구축된 Amazon S3 데이터 원본 커넥터가 나열되어 있습니다. Athena 쿼리에서 커넥터를 사용하려면 커넥터를 구성하여 계정에 배포합니다.

## 고려 사항 및 제한 사항
<a name="connectors-available-considerations"></a>
+ 일부 사전 구축된 커넥터는 커넥터를 사용하기 전에 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의 대소문자 해석기 모드
<a name="case-resolver-modes"></a>

Federation SDK는 스키마 및 테이블 이름에 대해 다음과 같은 표준화된 대소문자 해석기 모드를 지원합니다.
+ `NONE` - 지정된 스키마 및 테이블 이름의 대소문자를 변경하지 않습니다.
+ `LOWER` - 지정된 스키마와 테이블 이름을 모두 소문자로 표시합니다.
+ `UPPER` - 지정된 스키마 및 테이블 이름을 모두 대문자로 표시합니다.
+ `ANNOTATION` -이 모드는 이전 버전과의 호환성을 위해서만 유지되며 기존 Snowflake 및 SAP HANA 커넥터에서만 지원됩니다.
+ `CASE_INSENSITIVE_SEARCH` - 스키마 및 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다.

## 대소문자 해석기 모드에 대한 커넥터 지원
<a name="connector-support-matrix"></a>

### 기본 모드 지원
<a name="basic-mode-support"></a>

모든 JDBC 커넥터는 다음 기본 모드를 지원합니다.
+ `NONE`
+ `LOWER`
+ `UPPER`

### 주석 모드 지원
<a name="annotation-mode-support"></a>

다음 커넥터만 `ANNOTATION` 모드를 지원합니다.
+ Snowflake
+ SAP HANA

**참고**  
ANNOTATION 대신 CASE\$1INSENSITIVE\$1SEARCH를 사용하는 것이 좋습니다.

### 대소문자를 구분하지 않는 검색 지원
<a name="case-insensitive-search-support"></a>

다음 커넥터는 `CASE_INSENSITIVE_SEARCH`를 지원합니다.
+ DataLake Gen2
+ Snowflake
+ Oracle
+ Synapse
+ MySQL
+ PostgreSQL
+ Redshift
+ ClickHouse
+ SQL Server
+ DB2

## 대소문자 해석기 제한 사항
<a name="case-resolver-limitations"></a>

대소문자 해석기 모드를 사용할 때는 다음 제한 사항에 유의하세요.
+ `LOWER` 모드를 사용할 때 스키마 이름과 스키마 내의 모든 테이블은 소문자여야 합니다.
+ `UPPER` 모드를 사용할 때 스키마 이름과 스키마 내의 모든 테이블은 대문자여야 합니다.
+ `CASE_INSENSITIVE_SEARCH` 사용 시
  + 스키마 이름은 고유해야 합니다.
  + 스키마 내의 테이블 이름은 고유해야 합니다(예: "Apple"과 "APPLE"을 동시에 사용할 수 없음).
+ Glue 통합 제한 사항:
  + Glue는 소문자 이름만 지원합니다.
  + Lambda 함수를 GlueDataCatalog/LakeFormation에 등록할 때는 `NONE` 또는 `LOWER` 모드만 작동합니다.

## 추가 정보
<a name="connectors-available-additional-resources"></a>
+ 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 커넥터
<a name="connectors-adls-gen2"></a>

[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에 의해 전달될 수 있습니다.

## 사전 조건
<a name="connectors-datalakegentwo-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-adls-gen2-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.
+ 필터 조건의 날짜 및 타임스탬프 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다.

## 용어
<a name="connectors-adls-gen2-terms"></a>

다음은 Azure Data Lake Storage Gen2 커넥터와 관련된 용어입니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-adls-gen2-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="adls-gen2-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="adls-gen2-legacy"></a>

#### 연결 문자열
<a name="connectors-adls-gen2-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
datalakegentwo://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-adls-gen2-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | DataLakeGen2MuxCompositeHandler | 
| 메타데이터 핸들러 | DataLakeGen2MuxMetadataHandler | 
| 레코드 핸들러 | DataLakeGen2MuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-adls-gen2-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-adls-gen2-providing-credentials"></a>

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
```

#### 단일 연결 핸들러 사용
<a name="connectors-adls-gen2-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Azure Data Lake Storage Gen2 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | DataLakeGen2CompositeHandler | 
| 메타데이터 핸들러 | DataLakeGen2MetadataHandler | 
| 레코드 핸들러 | DataLakeGen2RecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-adls-gen2-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Azure Data Lake Storage Gen2 인스턴스에 대한 속성 예제입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 | 

#### 유출 파라미터
<a name="connectors-adls-gen2-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-adls-gen2-data-type-support"></a>

다음 표에 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 | 

## 파티션 및 분할
<a name="connectors-adls-gen2-partitions-and-splits"></a>

Azure Data Lake Storage Gen2는 데이터 파일 저장을 위해 Hadoop 호환 Gen2 blob 스토리지를 사용합니다. 이러한 파일의 데이터는 Azure Synapse 엔진에서 쿼리됩니다. Azure Synapse 엔진은 파일 시스템에 저장된 Gen2 데이터를 외부 테이블로 처리합니다. 파티션은 데이터 형식에 따라 구현됩니다. 데이터가 이미 Gen 2 스토리지 시스템 내에서 분할되고 배포된 경우 커넥터는 데이터를 단일 분할로 검색합니다.

## 성능
<a name="connectors-adls-gen2-performance"></a>

Azure Data Lake Storage Gen2 커넥터는 한 번에 여러 쿼리를 실행할 경우 쿼리 성능이 느려지고 제한이 적용될 수 있습니다.

쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Azure Data Lake Storage Gen2 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다.

### Predicates
<a name="connectors-datalakegentwo-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-datalakegentwo-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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%');
```

## 패스스루 쿼리
<a name="connectors-datalakegentwo-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-datalakegentwo-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-datalakegentwo-additional-resources"></a>

최신 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 커넥터
<a name="connectors-azure-synapse"></a>

[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의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-synapse-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-azure-synapse-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.
+ 필터 조건에서 `Date` 및 `Timestamp` 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다.
+ `Real` 및 `Float` 형식의 음수 값을 검색하려면 `<=` 또는 `>=` 연산자를 사용합니다.
+ `binary`, `varbinary`, `image` 및 `rowversion` 데이터 형식은 지원되지 않습니다.

## 용어
<a name="connectors-azure-synapse-terms"></a>

다음 용어는 Synapse 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-azure-synapse-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-azure-synapse-gc"></a>

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만 지원합니다.

### 레거시 연결(권장)
<a name="connectors-azure-synapse-legacy"></a>

#### 연결 문자열
<a name="connectors-azure-synapse-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
synapse://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-azure-synapse-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | SynapseMuxCompositeHandler | 
| 메타데이터 핸들러 | SynapseMuxMetadataHandler | 
| 레코드 핸들러 | SynapseMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-azure-synapse-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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=<database\$1name>;\$1\$1secret1\$1name\$1 | 
| synapse\$1catalog1\$1connection\$1string | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=<database\$1name>;\$1\$1secret1\$1name\$1 | 
| synapse\$1catalog2\$1connection\$1string | synapse://jdbc:synapse://synapse2.hostname:port;databaseName=<database\$1name>;\$1\$1secret2\$1name\$1 | 

##### 자격 증명 제공
<a name="connectors-azure-synapse-providing-credentials"></a>

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=<database_name>;${secret_name}
```

커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다.

```
synapse://jdbc:synapse://hostname:port;databaseName=<database_name>;user=<user>;password=<password>
```

#### 단일 연결 핸들러 사용
<a name="connectors-azure-synapse-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Synapse 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | SynapseCompositeHandler | 
| 메타데이터 핸들러 | SynapseMetadataHandler | 
| 레코드 핸들러 | SynapseRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-azure-synapse-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Synapse 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | synapse://jdbc:sqlserver://hostname:port;databaseName=<database\$1name>;\$1\$1secret\$1name\$1 | 

#### Active Directory 인증 구성
<a name="connectors-azure-synapse-configuring-active-directory-authentication"></a>

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)

##### 연결 문자열 수정
<a name="connectors-azure-synapse-modifying-the-connection-string"></a>

커넥터에 대해 Active Directory 인증을 활성화하려면 다음 구문을 사용하여 연결 문자열을 수정합니다.

```
synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryPassword;{secret_name}
```

##### ActiveDirectoryServicePrincipal 사용
<a name="connectors-azure-synapse-using-activedirectoryserviceprincipal"></a>

Amazon Athena Azure Synapse 커넥터는 `ActiveDirectoryServicePrincipal`도 지원합니다. 이를 활성화하려면 다음과 같이 연결 문자열을 수정합니다.

```
synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryServicePrincipal;{secret_name}
```

`secret_name`의 경우 애플리케이션 또는 클라이언트 ID를 사용자 이름으로, 암호에 서비스 보안 주체 ID의 암호를 지정합니다.

#### 유출 파라미터
<a name="connectors-azure-synapse-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-azure-synapse-data-type-support"></a>

다음 표에 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 | 

## 파티션 및 분할
<a name="connectors-azure-synapse-partitions-and-splits"></a>

파티션은 `varchar` 형식의 단일 파티션 열로 표시됩니다. Synapse는 범위 파티셔닝을 지원하므로 파티셔닝은 Synapse 메타데이터 테이블에서 파티션 열과 파티션 범위를 추출하여 구현됩니다. 이러한 범위 값은 분할을 생성하는 데 사용됩니다.

## 성능
<a name="connectors-azure-synapse-performance"></a>

열 하위 집합을 선택하면 쿼리 런타임이 크게 느려집니다. 이 커넥터는 동시성으로 인해 상당한 제한을 나타냅니다.

쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Synapse 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다.

### Predicates
<a name="connectors-synapse-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-synapse-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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%');
```

## 패스스루 쿼리
<a name="connectors-synapse-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-synapse-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-synapse-additional-resources"></a>
+ 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 커넥터
<a name="connectors-cloudera-hive"></a>

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를 통해 수행됩니다.

## 사전 조건
<a name="connectors-hive-prerequisites"></a>
+ 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) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-cloudera-hive-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.

## 용어
<a name="connectors-cloudera-hive-terms"></a>

다음 용어는 Cloudera Hive 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-cloudera-hive-parameters"></a>

이 섹션의 파라미터를 사용하여 Cloudera Hive 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="connectors-cloudera-hive-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-cloudera-hive-legacy"></a>

#### 연결 문자열
<a name="connectors-cloudera-hive-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
hive://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-cloudera-hive-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | HiveMuxCompositeHandler | 
| 메타데이터 핸들러 | HiveMuxMetadataHandler | 
| 레코드 핸들러 | HiveMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-cloudera-hive-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 보안 인증 정보 제공
<a name="connectors-cloudera-hive-credentials"></a>

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 속성을 인식합니다.

#### 단일 연결 핸들러 사용
<a name="connectors-cloudera-hive-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Cloudera Hive 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | HiveCompositeHandler | 
| 메타데이터 핸들러 | HiveMetadataHandler | 
| 레코드 핸들러 | HiveRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-cloudera-hive-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Cloudera Hive 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| 기본값 | hive://jdbc:hive2://hive1:10000/default;secret=\$1\$1Test/RDS/hive1\$1 | 

#### 유출 파라미터
<a name="connectors-cloudera-hive-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-cloudera-hive-data-type-support"></a>

다음 표에 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` 열로 처리됩니다.

## 파티션 및 분할
<a name="connectors-cloudera-hive-partitions-and-splits"></a>

파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다.

## 성능
<a name="connectors-cloudera-hive-performance"></a>

Cloudera Hive는 정적 파티션을 지원합니다. Athena Cloudera Hive 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 정적 파티셔닝을 사용하는 것이 좋습니다. Cloudera Hive 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

Athena Cloudera Hive 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다.

### LIMIT 절
<a name="connectors-hive-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-hive-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-hive-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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;
```

## 패스스루 쿼리
<a name="connectors-hive-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-hive-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-hive-additional-resources"></a>

최신 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 커넥터
<a name="connectors-cloudera-impala"></a>

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를 통해 수행됩니다.

## 사전 조건
<a name="connectors-impala-prerequisites"></a>
+ 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) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-cloudera-impala-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.

## 용어
<a name="connectors-cloudera-impala-terms"></a>

다음 용어는 Cloudera Impala 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-cloudera-impala-parameters"></a>

이 섹션의 파라미터를 사용하여 Cloudera Impala 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="connectors-cloudera-impala-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-cloudera-impala-legacy"></a>

#### 연결 문자열
<a name="connectors-cloudera-impala-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 Impala 클러스터에 연결합니다.

```
impala://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-cloudera-impala-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | ImpalaMuxCompositeHandler | 
| 메타데이터 핸들러 | ImpalaMuxMetadataHandler | 
| 레코드 핸들러 | ImpalaMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-cloudera-impala-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-cloudera-impala-providing-credentials"></a>

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 속성을 인식합니다.

#### 단일 연결 핸들러 사용
<a name="connectors-cloudera-impala-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Cloudera Impala 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | ImpalaCompositeHandler | 
| 메타데이터 핸들러 | ImpalaMetadataHandler | 
| 레코드 핸들러 | ImpalaRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-cloudera-impala-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Cloudera Impala 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | impala://jdbc:impala://Impala1host:21050/?secret=\$1\$1Test/impala1host\$1 | 

#### 유출 파라미터
<a name="connectors-cloudera-impala-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-cloudera-impala-data-type-support"></a>

다음 표에 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` 열로 처리됩니다.

## 파티션 및 분할
<a name="connectors-cloudera-impala-partitions-and-splits"></a>

파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다.

## 성능
<a name="connectors-cloudera-impala-performance"></a>

Cloudera Impala는 정적 파티션을 지원합니다. Athena Cloudera Impala 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 정적 파티셔닝을 사용하는 것이 좋습니다. Cloudera Impala 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

Athena Cloudera Impala 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다.

### LIMIT 절
<a name="connectors-impala-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-impala-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-impala-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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;
```

## 패스스루 쿼리
<a name="connectors-impala-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-impala-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-impala-additional-resources"></a>

최신 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 커넥터
<a name="connectors-cloudwatch"></a>

Amazon Athena CloudWatch 커넥터를 통해 Amazon Athena는 CloudWatch와 통신할 수 있고, 이로써 SQL을 사용하여 로그 데이터를 쿼리할 수 있습니다.

이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다.

커넥터는 LoggRoups를 스키마로 매핑하고 각 LogStream을 테이블로 매핑합니다. 또한 커넥터는 LogGroup에 모든 LogStream을 포함하는 특별 `all_log_streams` 뷰도 매핑합니다. 이 뷰를 사용하면 각 LogStream을 개별적으로 검색하는 대신 LogGroup의 모든 로그를 한 번에 쿼리할 수 있습니다.

## 사전 조건
<a name="connectors-cloudwatch-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 파라미터
<a name="connectors-cloudwatch-parameters"></a>

이 섹션의 파라미터를 사용하여 CloudWatch 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="connectors-cloudwatch-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-cloudwatch-legacy"></a>
+ **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밀리초입니다.

## 데이터베이스 및 테이블
<a name="connectors-cloudwatch-databases-and-tables"></a>

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
```

## 필수 권한
<a name="connectors-cloudwatch-required-permissions"></a>

이 커넥터에 필요한 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 읽기/쓰기** – 커넥터는 이 권한을 사용하여 로그 데이터를 읽고 진단 로그를 작성합니다.

## 성능
<a name="connectors-cloudwatch-performance"></a>

Athena CloudWatch 커넥터는 쿼리에 필요한 로그 스트림 스캔을 병렬화하여 CloudWatch에 대한 쿼리를 최적화하려고 시도합니다. 특정 기간 필터에 대해 조건자 푸시다운은 Lambda 함수와 CloudWatch Logs 내에서 모두 수행됩니다.

최상의 성능을 얻으려면 로그 그룹 이름과 로그 스트림 이름에 소문자만 사용합니다. 대/소문자를 혼합하여 사용하면 커넥터에서 대소문자를 구분하지 않고 검색하므로 더욱 컴퓨팅 집약적입니다.

**참고**  
 CloudWatch 커넥터는 대문자 데이터베이스 이름을 지원하지 않습니다.

## 패스스루 쿼리
<a name="connectors-cloudwatch-passthrough-queries"></a>

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'
            ))
```

## 라이선스 정보
<a name="connectors-cloudwatch-license-information"></a>

Amazon Athena CloudWatch 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다.

## 추가 리소스
<a name="connectors-cloudwatch-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch)를 참조하세요.

# Amazon Athena CloudWatch 지표 커넥터
<a name="connectors-cwmetrics"></a>

Amazon Athena CloudWatch 지표 커넥터를 사용하면 Amazon Athena에서 SQL로 CloudWatch 지표 데이터를 쿼리할 수 있습니다.

이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다.

Athena 자체에서 CloudWatch에 쿼리 지표를 게시하는 방법에 대한 자세한 내용은 [CloudWatch 및 EventBridge를 사용하여 쿼리 모니터링 및 비용 제어](workgroups-control-limits.md) 섹션을 참조하세요.

## 사전 조건
<a name="connectors-cwmetrics-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 파라미터
<a name="connectors-cwmetrics-parameters"></a>

이 섹션의 파라미터를 사용하여 CloudWatch Metrics 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="connectors-cwmetrics-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-cwmetrics-legacy"></a>
+ **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밀리초입니다.

## 데이터베이스 및 테이블
<a name="connectors-cwmetrics-databases-and-tables"></a>

Athena CloudWatch 지표 커넥터는 네임스페이스, 차원, 지표 및 지표 값을 `default`라는 단일 스키마의 두 테이블에 매핑합니다.

### 지표 테이블
<a name="connectors-cwmetrics-the-metrics-table"></a>

`metrics` 테이블에는 네임스페이스, 세트 및 이름의 조합으로 고유하게 정의된 사용 가능한 지표가 포함됩니다. `metrics` 테이블에는 다음 열이 있습니다.
+ **namespace** – 네임스페이스를 포함하는 `VARCHAR`입니다.
+ **metric\$1name** – 지표 이름을 포함하는 `VARCHAR`입니다.
+ **dimensions** – `dim_name (VARCHAR)` 및 `dim_value (VARCHAR)`로 구성된 `STRUCT` 객체의 `LIST`입니다.
+ **statistic** – 지표에 사용할 수 있는 `VARCH` 통계의 `LIST`입니다(예: `p90`, `AVERAGE` 등).

### metric\$1samples 테이블
<a name="connectors-cwmetrics-the-metric_samples-table"></a>

`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`).

## 필수 권한
<a name="connectors-cwmetrics-required-permissions"></a>

이 커넥터에 필요한 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 쓰기** - 커넥터는 이 액세스 권한을 사용하여 진단 로그를 작성합니다.

## 성능
<a name="connectors-cwmetrics-performance"></a>

Athena CloudWatch 지표 커넥터는 쿼리에 필요한 로그 스트림 스캔을 병렬화하여 CloudWatch 지표에 대한 쿼리를 최적화하려고 시도합니다. 특정 기간, 지표, 네임스페이스 및 차원 필터에 대해 조건자 푸시다운은 Lambda 함수와 CloudWatch Logs 내에서 모두 수행됩니다.

## 라이선스 정보
<a name="connectors-cwmetrics-license-information"></a>

Amazon Athena CloudWatch 지표 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다.

## 추가 리소스
<a name="connectors-cwmetrics-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch-metrics)를 참조하세요.

# Amazon Athena AWS CMDB 커넥터
<a name="connectors-cmdb"></a>

Amazon Athena AWS CMDB 커넥터를 통해 Athena는 다양한 AWS 서비스와 통신할 수 있고, 이로써 SQL을 사용하여 쿼리할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-cmdb-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md)을 참조하세요.

## 파라미터
<a name="connectors-cmdb-parameters"></a>

이 섹션의 파라미터를 사용하여 AWS CMDB 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="connectors-cmdb-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-cmdb-legacy"></a>

**참고**  
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 이미지 테이블에 대한 쿼리에 소유자 필터가 포함되어 있지 않으면 결과에 모든 공개 이미지가 포함됩니다.

## 데이터베이스 및 테이블
<a name="connectors-cmdb-databases-and-tables"></a>

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 객체의 세부 정보를 포함합니다.

## 필수 권한
<a name="connectors-cmdb-required-permissions"></a>

이 커넥터에 필요한 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 인스턴스를 설명합니다.

## 성능
<a name="connectors-cmdb-performance"></a>

현재 Athena AWS CMDB 커넥터는 병렬 스캔을 지원하지 않습니다. 조건자 푸시다운은 Lambda 함수 내에서 수행됩니다. 가능한 경우 부분 조건자는 쿼리 중인 서비스로 푸시됩니다. 예를 들어, 특정 Amazon EC2 인스턴스의 세부 정보에 대한 쿼리는 특정 인스턴스 ID로 EC2 API를 호출하여 대상 설명 작업을 실행합니다.

## 라이선스 정보
<a name="connectors-cmdb-license-information"></a>

Amazon Athena AWS CMDB 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다.

## 추가 리소스
<a name="connectors-cmdb-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-aws-cmdb)를 참조하세요.

# Amazon Athena IBM Db2 커넥터
<a name="connectors-ibm-db2"></a>

Db2용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 JDBC를 사용하여 IBM Db2 데이터베이스에 대해 SQL 쿼리를 실행할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-dbtwo-prerequisites"></a>
+ 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) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-ibm-db2-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.
+ 필터 조건의 날짜 및 타임스탬프 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다.

## 용어
<a name="connectors-ibm-db2-terms"></a>

다음 용어는 Db2 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-ibm-db2-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-ibm-db2-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-ibm-db2-legacy"></a>

#### 연결 문자열
<a name="connectors-ibm-db2-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
dbtwo://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-ibm-db2-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | Db2MuxCompositeHandler | 
| 메타데이터 핸들러 | Db2MuxMetadataHandler | 
| 레코드 핸들러 | Db2MuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-ibm-db2-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-ibm-db2-providing-credentials"></a>

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;
```

#### 단일 연결 핸들러 사용
<a name="connectors-ibm-db2-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Db2 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | Db2CompositeHandler | 
| 메타데이터 핸들러 | Db2MetadataHandler | 
| 레코드 핸들러 | Db2RecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-ibm-db2-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Db2 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | dbtwo://jdbc:db2://hostname:port/database\$1name:\$1\$1secret\$1name\$1  | 

#### 유출 파라미터
<a name="connectors-ibm-db2-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-ibm-db2-data-type-support"></a>

다음 표에 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 | 

## 파티션 및 분할
<a name="connectors-ibm-db2-partitions-and-splits"></a>

파티션은 하나 이상의 `varchar` 형식 파티션 열로 표시됩니다. Db2 커넥터는 다음 조직 체계를 사용하여 파티션을 생성합니다.
+ 해시별 배포
+ 범위별 파티션
+ 차원별 구성

커넥터는 하나 이상의 Db2 메타데이터 테이블에서 파티션 수, 열 이름과 같은 파티션 세부 정보를 검색합니다. 분할은 식별된 파티션 수를 기준으로 생성됩니다.

## 성능
<a name="connectors-ibm-db2-performance"></a>

Athena Db2 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다.

### LIMIT 절
<a name="connectors-dbtwo-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-dbtwo-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-dbtwo-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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;
```

## 패스스루 쿼리
<a name="connectors-dbtwo-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-dbtwo-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-dbtwo-additional-resources"></a>

최신 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) 커넥터
<a name="connectors-ibm-db2-as400"></a>

Db2 AS/400용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 JDBC를 사용하여 IBM Db2 AS/400(Db2 iSeries) 데이터베이스에 대해 SQL 쿼리를 실행할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-db2as400-prerequisites"></a>
+ 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) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-ibm-db2-as400-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.
+ 필터 조건의 날짜 및 타임스탬프 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다.

## 용어
<a name="connectors-ibm-db2-as400-terms"></a>

다음 용어는 Db2 AS/400 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-ibm-db2-as400-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-ibm-db2-as400-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-ibm-db2-as400-legacy"></a>

#### 연결 문자열
<a name="connectors-ibm-db2-as400-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
db2as400://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-ibm-db2-as400-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | Db2MuxCompositeHandler | 
| 메타데이터 핸들러 | Db2MuxMetadataHandler | 
| 레코드 핸들러 | Db2MuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-ibm-db2-as400-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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://<ip\$1address>;<properties>;:\$1\$1<secret name>\$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://<ip\$1address>;user=<username>;password=<password>;<properties>; | 

##### 자격 증명 제공
<a name="connectors-ibm-db2-as400-providing-credentials"></a>

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://<ip_address>;<properties>;:${<secret_name>};
```

커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다.

```
db2as400://jdbc:as400://<ip_address>;user=<username>;password=<password>;<properties>;
```

#### 단일 연결 핸들러 사용
<a name="connectors-ibm-db2-as400-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Db2 AS/400 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | Db2CompositeHandler | 
| 메타데이터 핸들러 | Db2MetadataHandler | 
| 레코드 핸들러 | Db2RecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-ibm-db2-as400-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Db2 AS/400 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | db2as400://jdbc:as400://<ip\$1address>;<properties>;:\$1\$1<secret\$1name>\$1; | 

#### 유출 파라미터
<a name="connectors-ibm-db2-as400-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-ibm-db2-as400-data-type-support"></a>

다음 표에 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 | 

## 파티션 및 분할
<a name="connectors-ibm-db2-as400-partitions-and-splits"></a>

파티션은 하나 이상의 `varchar` 형식 파티션 열로 표시됩니다. Db2 AS/400 커넥터는 다음 구성 체계를 사용하여 파티션을 생성합니다.
+ 해시별 배포
+ 범위별 파티션
+ 차원별 구성

커넥터는 하나 이상의 Db2 AS/400 메타데이터 테이블에서 파티션 수, 열 이름과 같은 파티션 세부 정보를 검색합니다. 분할은 식별된 파티션 수를 기준으로 생성됩니다.

## 성능
<a name="connectors-db2-as400-performance"></a>

성능 개선을 위해 다음 예제와 같이 조건자 푸시다운을 사용하여 Athena에서 쿼리합니다.

```
SELECT * FROM "lambda:<LAMBDA_NAME>"."<SCHEMA_NAME>"."<TABLE_NAME>" 
 WHERE integercol = 2147483647
```

```
SELECT * FROM "lambda: <LAMBDA_NAME>"."<SCHEMA_NAME>"."<TABLE_NAME>" 
 WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878'
```

## 패스스루 쿼리
<a name="connectors-db2as400-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-db2as400-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-db2as400-additional-resources"></a>

최신 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 커넥터
<a name="connectors-docdb"></a>

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의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-docdb-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 파라미터
<a name="connectors-docdb-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-docdb-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-docdb-legacy"></a>
+ **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`입니다. 쿼리에 대문자 스키마 또는 테이블 이름이 포함된 경우에 사용합니다.

#### 연결 문자열 지정
<a name="connectors-docdb-specifying-connection-strings"></a>

커넥터에서 사용하는 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      
```

##### 보안 암호 사용
<a name="connectors-docdb-using-secrets"></a>

필요에 따라 연결 문자열 세부 정보 값의 일부 또는 전체에 대해 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>` 값을 가진 일반 텍스트 보안 암호로 저장되어야 합니다 `{username:<username>,password:<password>}`로 저장된 보안 암호는 연결 문자열에 제대로 전달되지 않습니다.

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

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

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

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

## 보충 메타데이터 검색
<a name="supplemental-metadata"></a>

보충 메타데이터를 검색하려면 다음 단계에 따라 Glue 데이터베이스 및 테이블을 구성합니다.

### Glue 데이터베이스 설정
<a name="setup-glue-database"></a>

1. DocumentDB 컬렉션과 이름이 동일한 Glue 데이터베이스를 생성합니다.

1. 위치 URI 필드에 `docdb-metadata-flag`를 입력합니다.

### Glue 테이블 구성
<a name="setup-glue-table"></a>

Glue 테이블에 다음 파라미터를 추가합니다.
+ `docdb-metadata-flag = true`
+ `columnMapping = apple=APPLE`

  이 예제에서 `apple`은 Glue의 소문자 열 이름을 나타내고 `APPLE`은 DocumentDB 컬렉션의 실제 대소문자 구분 열 이름을 나타냅니다.

### 메타데이터 검색 확인
<a name="verify-metadata-retrieval"></a>

1. 쿼리를 실행합니다.

1. Lambda 함수의 CloudWatch 로그에서 메타데이터 검색이 성공했는지 확인합니다. 검색이 성공하면 다음 로그 항목이 표시됩니다.

   ```
   doGetTable: Retrieved schema for table[TableName{schemaName=test, tableName=profiles}] from AWS Glue.
   ```

**참고**  
테이블에 이미 `columnMapping` 필드가 구성되어 있는 경우 테이블 속성에 `docdb-metadata-flag = true` 파라미터를 추가하기만 하면 됩니다.

## AWS Glue에서 데이터베이스 및 테이블 설정
<a name="connectors-docdb-setting-up-databases-and-tables-in-aws-glue"></a>

커넥터의 기본 제공 스키마 추론 기능은 제한된 수의 문서를 스캔하고 데이터 형식의 하위 세트만 지원하므로 메타데이터에 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에 적합한 데이터 형식을 사용해야 합니다.

## 데이터 형식 지원
<a name="connectors-docdb-data-type-support"></a>

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

### 스키마 추론 데이터 형식
<a name="connectors-docdb-schema-inference-data-types"></a>

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 데이터 유형
<a name="connectors-docdb-glue-data-types"></a>

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


****  

| AWS Glue | Apache Arrow | 
| --- | --- | 
| int | INT | 
| bigint | BIGINT | 
| double | FLOAT8 | 
| 실수 | FLOAT4 | 
| 부울 | BIT | 
| 이진수 | VARBINARY | 
| 문자열 | VARCHAR | 
| List | LIST | 
| 구조체 | STRUCT | 

## 필수 권한
<a name="connectors-docdb-required-permissions"></a>

이 커넥터에 필요한 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에 인터페이스를 연결하고 분리하는 기능이 커넥터에 필요합니다.

## 성능
<a name="connectors-docdb-performance"></a>

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

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

## 패스스루 쿼리
<a name="connectors-docdb-passthrough-queries"></a>

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"}'
        ))
```

## 추가 리소스
<a name="connectors-docdb-additional-resources"></a>
+ [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 커넥터
<a name="connectors-dynamodb"></a>

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에 대한 읽기 액세스 권한을 가지고 있어야 합니다.

## 사전 조건
<a name="connectors-dynamodb-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-dynamodb-limitations"></a>

DynamoDB 연결을 Glue Catalog 및 Lake Formation으로 마이그레이션하면 소문자 테이블과 열 이름만 인식됩니다.

## 파라미터
<a name="connectors-dynamodb-parameters"></a>

이 섹션의 파라미터를 사용하여 DynamoDB 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="ddb-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="ddb-legacy"></a>

**참고**  
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에서 데이터베이스 및 테이블 설정
<a name="connectors-dynamodb-setting-up-databases-and-tables-in-aws-glue"></a>

커넥터의 기본 제공 스키마 추론 기능이 제한되어 있으므로 메타데이터에 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. **저장**을 선택합니다.

## 필수 권한
<a name="connectors-dynamodb-required-permissions"></a>

이 커넥터에 필요한 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 작업을 사용합니다.

## 성능
<a name="connectors-dynamodb-performance"></a>

Athena DynamoDB 커넥터는 병렬 스캔을 지원하고 DynamoDB 쿼리의 일부로 조건자 푸시다운을 시도합니다. `X`개의 고유 값이 있는 해시 키 조건자는 DynamoDB에 대한 `X`개의 쿼리 호출을 생성합니다. 다른 모든 조건자 시나리오에서는 `Y`개의 스캔 호출이 발생합니다. 여기서 `Y`는 테이블 크기와 프로비저닝된 처리량을 기반으로 경험적으로 결정됩니다. 그러나 열 하위 세트를 선택할 때 쿼리 실행 런타임이 길어지는 경우가 있습니다.

`LIMIT` 절 및 간단한 조건자가 푸시다운되면 스캔하는 데이터가 줄어들 수 있으며 이에 따라 쿼리 실행 런타임이 감소할 수 있습니다.

### LIMIT 절
<a name="connectors-dynamodb-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-dynamodb-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-dynamodb-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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/)를 참조하세요.

## 패스스루 쿼리
<a name="connectors-dynamodb-passthrough-queries"></a>

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''
        ))
```

## 문제 해결
<a name="connectors-dynamodb-troubleshooting"></a>

### 정렬 키 열의 다중 필터
<a name="connectors-dynamodb-troubleshooting-sort-key-filters"></a>

**오류 메시지**: KeyConditionExpressions must only contain one condition per key

**원인**: 이 문제는 Athena 엔진 버전 3의 경우 DynamoDB 정렬 키 열에 하한 및 상한 필터가 모두 있는 쿼리에서 발생할 수 있습니다. DynamoDB는 정렬 키에 대해 둘 이상의 필터 조건을 지원하지 않으므로 커넥터가 두 조건이 모두 적용된 쿼리를 푸시다운하려고 하면 오류가 발생합니다.

**솔루션**: 커넥터를 버전 2023.11.1 이상으로 업데이트합니다. 커넥터 업데이트에 대한 지침은 [데이터 소스 커넥터 업데이트](connectors-updating.md) 섹션을 참조하세요.

## 비용
<a name="connectors-dynamodb-costs"></a>

커넥터 사용 비용은 사용되는 기본 AWS 리소스에 따라 다릅니다. 스캔을 사용하는 쿼리는 많은 [읽기 용량 단위(RCU)](https://aws.amazon.com/dynamodb/pricing/provisioned/)를 사용할 수 있으므로 [Amazon DynamoDB 요금 정보](https://aws.amazon.com/dynamodb/pricing/)를 신중하게 고려하세요.

## 추가 리소스
<a name="connectors-dynamodb-additional-resources"></a>
+ 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 커넥터
<a name="connectors-bigquery"></a>

Google [BigQuery](https://cloud.google.com/bigquery/)용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 Google BigQuery 데이터에 대해 SQL 쿼리를 실행할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-bigquery-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-bigquery-limitations"></a>
+ 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)를 참조하세요.

## 파라미터
<a name="connectors-bigquery-parameters"></a>

이 섹션의 파라미터를 사용하여 Google BigQuery 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="bigquery-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="bigquery-legacy"></a>

**참고**  
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에 액세스하려는 경우 이 파라미터를 사용합니다.

## 분할 및 뷰
<a name="connectors-bigquery-splits-and-views"></a>

BigQuery 커넥터는 BigQuery Storage Read API를 사용하여 테이블을 쿼리하고, BigQuery Storage API는 뷰를 지원하지 않기 때문에 커넥터는 뷰의 단일 분할에 BigQuery 클라이언트를 사용합니다.

## 성능
<a name="connectors-bigquery-performance"></a>

테이블 쿼리를 위해 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 절
<a name="connectors-bigquery-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### 상위 N개 쿼리
<a name="connectors-bigquery-performance-top-n-queries"></a>

상위 `N`개 쿼리는 결과 세트의 순서와 반환되는 행 수에 대한 한도를 지정합니다. 이 유형의 쿼리를 사용하여 데이터 세트에 대해 상위 `N`개의 최댓값 또는 상위 `N`개의 최솟값을 결정할 수 있습니다. 상위 `N`개의 푸시다운을 통해 커넥터는 Athena에 `N`개의 정렬된 행만 반환합니다.

### Predicates
<a name="connectors-bigquery-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-bigquery-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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;
```

## 패스스루 쿼리
<a name="connectors-bigquery-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-bigquery-license-information"></a>

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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-bigquery-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-google-bigquery)를 참조하세요.

# Amazon Athena Google Cloud Storage 커넥터
<a name="connectors-gcs"></a>

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/)을 참조하세요.

## 사전 조건
<a name="connectors-gcs-prerequisites"></a>
+ 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) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-gcs-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.
+ 현재 커넥터는 파티션 열(AWS Glue 테이블 스키마의 `string` 또는 `varchar`)에 대해 `VARCHAR` 유형만 지원합니다. 다른 파티션 필드 유형은 Athena에서 쿼리할 때 오류가 발생합니다.

## 용어
<a name="connectors-gcs-terms"></a>

다음 용어는 GCS 커넥터와 관련이 있습니다.
+ **핸들러** - GCS 버킷에 액세스하는 Lambda 핸들러입니다. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - GCS 버킷에서 메타데이터를 검색하는 Lambda 핸들러입니다.
+ **레코드 핸들러** - GCS 버킷에서 데이터 레코드를 검색하는 Lambda 핸들러입니다.
+ **복합 핸들러** - GCS 버킷에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러입니다.

## 지원되는 파일 형식
<a name="connectors-gcs-supported-file-types"></a>

GCS 커넥터는 Parquet 및 CSV 파일 형식을 지원합니다.

**참고**  
동일한 GCS 버킷 또는 경로에 CSV 및 Parquet 파일을 모두 배치하지 않도록 합니다. 그렇게 하면 Parquet 파일을 CSV로 읽거나 그 반대로 읽으려고 할 때 런타임 오류가 발생할 수 있습니다.

## 파라미터
<a name="connectors-gcs-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-gcs-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-gcs-legacy"></a>
+ **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에서 데이터베이스 및 테이블 설정
<a name="connectors-gcs-setting-up-databases-and-tables-in-glue"></a>

GCS 커넥터의 기본 제공 스키마 추론 기능은 제한적이기 때문에 메타데이터에 AWS Glue를 사용하는 것이 좋습니다. 다음 절차는 Athena에서 액세스할 수 있는 AWS Glue에서 데이터베이스와 테이블을 생성하는 방법을 보여줍니다.

### AWS Glue에서 데이터베이스 생성
<a name="connectors-gcs-creating-a-database-in-glue"></a>

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에서 테이블 생성
<a name="connectors-gcs-creating-a-table-in-glue"></a>

이제 데이터베이스용 테이블을 생성할 수 있습니다. 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에서 테이블 스키마 정의
<a name="connectors-gcs-defining-a-table-schema-in-glue"></a>

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에서 테이블 속성에 파티션 패턴 추가
<a name="connectors-gcs-adding-a-partition-pattern-to-table-properties-in-glue"></a>

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에서 쿼리할 수 있습니다.

## 데이터 형식 지원
<a name="connectors-gcs-data-type-support"></a>

다음 표에 CSV 및 Parquet에 대해 지원되는 데이터 형식이 나와 있습니다.

### CSV
<a name="connectors-gcs-csv"></a>


****  

| **데이터의 특성** | **추론된 데이터 형식** | 
| --- | --- | 
| 데이터가 숫자처럼 보임 | BIGINT | 
| 데이터가 문자열처럼 보임 | VARCHAR | 
| 데이터가 부동 소수점(float, double 또는 decimal)처럼 보임 | DOUBLE | 
| 데이터가 날짜처럼 보임 | 타임스탬프 | 
| 데이터에 true/false 값이 포함됨 | BOOL | 

### PARQUET
<a name="connectors-gcs-parquet"></a>


****  

| **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 | 

## 필수 권한
<a name="connectors-gcs-required-permissions"></a>

이 커넥터에 필요한 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에 대한 액세스 권한이 필요합니다.

## 성능
<a name="connectors-gcs-performance"></a>

테이블 스키마에 파티션 필드가 포함되어 있고 `partition.pattern` 테이블 속성이 올바르게 구성된 경우 쿼리의 `WHERE` 절에 파티션 필드를 포함할 수 있습니다. 이러한 쿼리의 경우 GCS 커넥터는 파티션 열을 사용하여 GCS 폴더 경로를 구체화하고 GCS 폴더에서 불필요한 파일을 스캔하지 않도록 합니다.

Parquet 데이터 세트의 경우 열 하위 세트를 선택하면 스캔되는 데이터가 줄어듭니다. 이로 인해 일반적으로 열 프로젝션이 적용될 때 쿼리 실행 런타임이 짧아집니다.

CSV 데이터 세트의 경우 열 프로젝션이 지원되지 않으며 스캔되는 데이터의 양을 줄이지 않습니다.

`LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자를 제공하지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. GCS 커넥터는 적용된 `LIMIT` 절에 관계없이 작은 데이터 세트보다 큰 데이터 세트에 대해 더 많은 데이터를 스캔합니다. 예를 들어, 쿼리 `SELECT * LIMIT 10000`은 더 작은 기본 데이터 세트보다 더 큰 기본 데이터 세트에 대해 더 많은 데이터를 스캔합니다.

### 라이선스 정보
<a name="connectors-gcs-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

### 추가 리소스
<a name="connectors-gcs-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-gcs)를 참조하세요.

# Amazon Athena HBase 커넥터
<a name="connectors-hbase"></a>

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의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-hbase-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 파라미터
<a name="connectors-hbase-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-hbase-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-hbase-legacy"></a>
+ **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`입니다. 쿼리에 대문자 테이블 이름이 포함된 경우에 사용합니다.

#### 연결 문자열 지정
<a name="connectors-hbase-specifying-connection-strings"></a>

커넥터에서 사용하는 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
```

##### 보안 암호 사용
<a name="connectors-hbase-using-secrets"></a>

필요에 따라 연결 문자열 세부 정보 값의 일부 또는 전체에 대해 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에서 데이터베이스 및 테이블 설정
<a name="connectors-hbase-setting-up-databases-and-tables-in-aws-glue"></a>

커넥터의 기본 제공 스키마 추론은 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에 적합한 데이터 형식을 사용해야 합니다.

### 열 패밀리 모델링
<a name="connectors-hbase-modeling-column-families"></a>

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)


## 데이터 형식 지원
<a name="connectors-hbase-data-type-support"></a>

커넥터는 모든 HBase 값을 기본 바이트 유형으로 검색합니다. 그런 다음 AWS Glue 데이터 카탈로그에서 테이블을 정의한 방법에 따라 값을 다음 테이블의 Apache Arrow 데이터 형식 중 하나로 매핑합니다.


****  

| AWS Glue 데이터 유형 | Apache Arrow 데이터 형식 | 
| --- | --- | 
| int | INT | 
| bigint | BIGINT | 
| double | FLOAT8 | 
| 실수 | FLOAT4 | 
| 부울 | BIT | 
| 이진수 | VARBINARY | 
| 문자열 | VARCHAR | 

**참고**  
AWS Glue를 사용하여 메타데이터를 보충하지 않는 경우 커넥터의 스키마 추론은 데이터 형식 `BIGINT`, `FLOAT8` 및 `VARCHAR`만 사용합니다.

## 필수 권한
<a name="connectors-hbase-required-permissions"></a>

이 커넥터에 필요한 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에 인터페이스를 연결하고 분리하는 기능이 커넥터에 필요합니다.

## 성능
<a name="connectors-hbase-performance"></a>

Athena HBase 커넥터는 각 리전 서버를 병렬로 읽어 HBase 인스턴스에 대한 쿼리 병렬화를 시도합니다. 쿼리에서 스캔하는 데이터를 줄이기 위해 Athena HBase 커넥터에서 조건자 푸시다운을 수행합니다.

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

HBase는 쿼리 실패가 발생하기 쉽고 쿼리 실행 시간이 가변적입니다. 쿼리가 성공하려면 쿼리를 여러 번 다시 시도해야 할 수 있습니다. HBase 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

## 패스스루 쿼리
<a name="connectors-hbase-passthrough-queries"></a>

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'')'
        ))
```

## 라이선스 정보
<a name="connectors-hbase-license-information"></a>

Amazon Athena HBase 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다.

## 추가 리소스
<a name="connectors-hbase-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hbase)를 참조하세요.

# Amazon Athena Hortonworks 커넥터
<a name="connectors-hortonworks"></a>

Hortonworks용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 Cloudera [Hortonworks](https://www.cloudera.com/products/hdp.html) 데이터 플랫폼에 대해 SQL 쿼리를 실행할 수 있습니다. 커넥터는 Athena SQL 쿼리를 동일한 HiveQL 구문으로 변환합니다.

이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다.

## 사전 조건
<a name="connectors-hive-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-hortonworks-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.

## 용어
<a name="connectors-hortonworks-terms"></a>

다음 용어는 Hortonworks Hive 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-hortonworks-parameters"></a>

이 섹션의 파라미터를 사용하여 Hortonworks Hive 커넥터를 구성합니다.

### 연결 문자열
<a name="connectors-hortonworks-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
hive://${jdbc_connection_string}
```

### 멀티플렉싱 핸들러 사용
<a name="connectors-hortonworks-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | HiveMuxCompositeHandler | 
| 메타데이터 핸들러 | HiveMuxMetadataHandler | 
| 레코드 핸들러 | HiveMuxRecordHandler | 

#### 멀티플렉싱 핸들러 파라미터
<a name="connectors-hortonworks-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

#### 자격 증명 제공
<a name="connectors-hortonworks-providing-credentials"></a>

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 속성을 인식합니다.

### 단일 연결 핸들러 사용
<a name="connectors-hortonworks-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Hortonworks Hive 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | HiveCompositeHandler | 
| 메타데이터 핸들러 | HiveMetadataHandler | 
| 레코드 핸들러 | HiveRecordHandler | 

#### 단일 연결 핸들러 파라미터
<a name="connectors-hortonworks-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Hortonworks Hive 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | hive://jdbc:hive2://hive1host:10000/default?secret=\$1\$1Test/RDS/hive1host\$1 | 

### 유출 파라미터
<a name="connectors-hortonworks-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-hortonworks-data-type-support"></a>

다음 표에 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` 열로 처리됩니다.

## 파티션 및 분할
<a name="connectors-hortonworks-partitions-and-splits"></a>

파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다.

## 성능
<a name="connectors-hortonworks-performance"></a>

Hortonworks Hive는 정적 파티션을 지원합니다. Athena Hortonworks Hive 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 정적 파티셔닝을 사용하는 것이 좋습니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. Hortonworks Hive 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

Athena Hortonworks Hive 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다.

### LIMIT 절
<a name="connectors-hive-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-hive-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-hive-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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;
```

## 패스스루 쿼리
<a name="connectors-hive-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-hive-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-hive-additional-resources"></a>

최신 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 커넥터
<a name="connectors-kafka"></a>

Apache Kafka용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 Apache Kafka 주제에서 SQL 쿼리를 실행할 수 있습니다. 이 커넥터를 사용하여 Athena에서 [Apache Kafka](https://kafka.apache.org/) 주제를 테이블로, 메시지를 행으로 볼 수 있습니다.

이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다.

## 사전 조건
<a name="connectors-kafka-prerequisites"></a>

Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-kafka-limitations"></a>
+ 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 메시지 메타데이터에 대한 액세스를 지원하지 않습니다.

## 용어
<a name="connectors-kafka-terms"></a>
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **Kafka 엔드포인트** - Kafka 인스턴스에 연결하는 텍스트 문자열입니다.

## 클러스터 호환성
<a name="connectors-kafka-cluster-compatibility"></a>

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에 연결
<a name="connectors-kafka-connecting-to-confluent"></a>

Confluent에 연결하려면 다음 단계를 수행해야 합니다.

1. Confluent에서 API 키를 생성합니다.

1. Confluent API 키의 사용자 이름과 암호를 AWS Secrets Manager에 저장합니다.

1. Kafka 커넥터에 `secrets_manager_secret` 환경 변수의 보안 암호 이름을 입력합니다.

1. 이 문서의 [Kafka 커넥터 설정](#connectors-kafka-setup) 섹션에 나온 단계를 수행합니다.

## 지원되는 인증 방법
<a name="connectors-kafka-supported-authentication-methods"></a>

커넥터에서 지원되는 인증 방법은 다음과 같습니다.
+ [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) 섹션을 참조하세요.

## 지원되는 입력 데이터 형식
<a name="connectors-kafka-supported-input-data-formats"></a>

커넥터에서 지원되는 입력 데이터 형식은 다음과 같습니다.
+ JSON
+ CSV
+ AVRO
+ PROTOBUF(프로토콜 버퍼)

## 파라미터
<a name="connectors-kafka-parameters"></a>

이 섹션의 파라미터를 사용하여 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)를 참조하세요.

## 데이터 형식 지원
<a name="connectors-kafka-data-type-support"></a>

다음 표에 Kafka와 Apache Arrow에 대해 지원되는 해당 데이터 형식이 나와 있습니다.


****  

| Kafka | 화살표 | 
| --- | --- | 
| CHAR | VARCHAR | 
| VARCHAR | VARCHAR | 
| TIMESTAMP | MILLISECOND | 
| DATE | DAY | 
| BOOLEAN | BOOL | 
| SMALLINT | SMALLINT | 
| INTEGER | INT | 
| BIGINT | BIGINT | 
| DECIMAL | FLOAT8 | 
| DOUBLE | FLOAT8 | 

## 파티션 및 분할
<a name="connectors-kafka-partitions-and-splits"></a>

Kafka 주제는 파티션으로 분할됩니다. 각 파티션은 순서대로 정렬됩니다. 파티션의 각 메시지에는 offset이라는 증분 ID가 있습니다.** 각 Kafka 파티션은 병렬 처리를 위해 다시 여러 영역으로 분할됩니다. 데이터는 Kafka 클러스터에 구성된 보존 기간 동안 사용할 수 있습니다.

## 모범 사례
<a name="connectors-kafka-best-practices"></a>

다음 예와 같이 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 커넥터 설정
<a name="connectors-kafka-setup"></a>

커넥터를 사용하려면 먼저 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의 스키마 예
<a name="connectors-kafka-setup-schema-examples"></a>

스키마를 [AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)에 업로드할 경우 이 단원의 예제 형식을 사용하세요.

#### JSON 유형 스키마 예
<a name="connectors-kafka-setup-schema-examples-json"></a>

다음 예제에서 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 유형 스키마 예
<a name="connectors-kafka-setup-schema-examples-csv"></a>

다음 예제에서 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 유형 스키마 예
<a name="connectors-kafka-setup-schema-examples-avro"></a>

다음 예제는 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 유형 스키마 예
<a name="connectors-kafka-setup-schema-examples-protobuf"></a>

다음 예제는 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 커넥터에 대한 인증 구성
<a name="connectors-kafka-setup-configuring-authentication"></a>

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
<a name="connectors-kafka-setup-configuring-authentication-tls"></a>

클러스터가 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
<a name="connectors-kafka-setup-configuring-authentication-sasl-scram"></a>

클러스터에서 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)을 참조하세요.

## 라이선스 정보
<a name="connectors-kafka-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-kafka-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-kafka)를 참조하세요.

# Amazon Athena MSK 커넥터
<a name="connectors-msk"></a>

[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를 통해 수행됩니다.

## 사전 조건
<a name="connectors-msk-prerequisites"></a>

Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-msk-limitations"></a>
+ 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 메시지 메타데이터에 대한 액세스를 지원하지 않습니다.

## 용어
<a name="connectors-msk-terms"></a>
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **Kafka 엔드포인트** - Kafka 인스턴스에 연결하는 텍스트 문자열입니다.

## 클러스터 호환성
<a name="connectors-msk-cluster-compatibility"></a>

MSK 커넥터는 다음과 같은 클러스터 유형과 함께 사용할 수 있습니다.
+ **MSK 프로비저닝 클러스터** - 클러스터 용량을 수동으로 지정, 모니터링 및 조정합니다.
+ **MSK 서버리스 클러스터** - 애플리케이션 I/O가 확장되면 자동으로 확장되는 온디맨드 용량을 제공합니다.
+ **독립 실행형 Kafka** - Kafka에 대한 직접 연결(인증된 연결 또는 인증되지 않은 연결)입니다.

## 지원되는 인증 방법
<a name="connectors-msk-supported-authentication-methods"></a>

커넥터에서 지원되는 인증 방법은 다음과 같습니다.
+ [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) 섹션을 참조하세요.

## 지원되는 입력 데이터 형식
<a name="connectors-msk-supported-input-data-formats"></a>

커넥터에서 지원되는 입력 데이터 형식은 다음과 같습니다.
+ JSON
+ CSV

## 파라미터
<a name="connectors-msk-parameters"></a>

이 섹션의 파라미터를 사용하여 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)

## 데이터 형식 지원
<a name="connectors-msk-data-type-support"></a>

다음 표에 Kafka와 Apache Arrow에 대해 지원되는 해당 데이터 형식이 나와 있습니다.


****  

| Kafka | 화살표 | 
| --- | --- | 
| CHAR | VARCHAR | 
| VARCHAR | VARCHAR | 
| TIMESTAMP | MILLISECOND | 
| DATE | DAY | 
| BOOLEAN | BOOL | 
| SMALLINT | SMALLINT | 
| INTEGER | INT | 
| BIGINT | BIGINT | 
| DECIMAL | FLOAT8 | 
| DOUBLE | FLOAT8 | 

## 파티션 및 분할
<a name="connectors-msk-partitions-and-splits"></a>

Kafka 주제는 파티션으로 분할됩니다. 각 파티션은 순서대로 정렬됩니다. 파티션의 각 메시지에는 offset이라는 증분 ID가 있습니다.** 각 Kafka 파티션은 병렬 처리를 위해 다시 여러 영역으로 분할됩니다. 데이터는 Kafka 클러스터에 구성된 보존 기간 동안 사용할 수 있습니다.

## 모범 사례
<a name="connectors-msk-best-practices"></a>

다음 예와 같이 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 커넥터 설정
<a name="connectors-msk-setup"></a>

커넥터를 사용하려면 먼저 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의 스키마 예
<a name="connectors-msk-setup-schema-examples"></a>

스키마를 [AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)에 업로드할 경우 이 단원의 예제 형식을 사용하세요.

#### JSON 유형 스키마 예
<a name="connectors-msk-setup-schema-examples-json"></a>

다음 예제에서 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 유형 스키마 예
<a name="connectors-msk-setup-schema-examples-csv"></a>

다음 예제에서 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 커넥터에 대한 인증 구성
<a name="connectors-msk-setup-configuring-authentication"></a>

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
<a name="connectors-msk-setup-configuring-authentication-sasl-iam"></a>

클러스터에서 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
<a name="connectors-msk-setup-configuring-authentication-tls"></a>

클러스터가 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
<a name="connectors-msk-setup-configuring-authentication-sasl-scram"></a>

클러스터에서 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)


## 라이선스 정보
<a name="connectors-msk-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-msk-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-msk)를 참조하세요.

# Amazon Athena MySQL 커넥터
<a name="connectors-mysql"></a>

Amazon Athena는 Amazon Athena Lambda MySQL 커넥터를 통해 MySQL 데이터베이스에 액세스할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-mysql-prerequisites"></a>
+ 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) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-mysql-limitations"></a>
+ 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으로 마이그레이션하면 소문자 테이블과 열 이름만 인식됩니다.

## 용어
<a name="connectors-mysql-terms"></a>

다음 용어는 MySQL 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-mysql-parameters"></a>

이 섹션의 파라미터를 사용하여 MySQL 커넥터를 구성합니다.

**참고**  
2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다.

### Glue 연결(권장)
<a name="connectors-mysql-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-mysql-connection-legacy"></a>

아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다.

#### 연결 문자열
<a name="connectors-mysql-connection-string"></a>

다음 형식의 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 날짜 값 금지' 오류)를 참조하세요.

#### 멀티플렉싱 핸들러 사용
<a name="connectors-mysql-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | MySqlMuxCompositeHandler | 
| 메타데이터 핸들러 | MySqlMuxMetadataHandler | 
| 레코드 핸들러 | MySqlMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-mysql-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-mysql-providing-credentials"></a>

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 속성을 인식합니다.

#### 단일 연결 핸들러 사용
<a name="connectors-mysql-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 MySQL 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | MySqlCompositeHandler | 
| 메타데이터 핸들러 | MySqlMetadataHandler | 
| 레코드 핸들러 | MySqlRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-mysql-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 MySQL 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | mysql://mysql1.host:3306/default?secret=Test/RDS/MySql1 | 

#### 유출 파라미터
<a name="connectors-mysql-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-mysql-data-type-support"></a>

다음 표에 JDBC와 Arrow의 해당 데이터 형식이 나와 있습니다.


****  

| JDBC | 화살표 | 
| --- | --- | 
| 부울 | Bit | 
| Integer | Tiny | 
| Short | Smallint | 
| Integer | 정수 | 
| Long | Bigint | 
| 실수 | Float4 | 
| 배정밀도 실수 | Float8 | 
| 날짜 | DateDay | 
| 타임스탬프 | DateMilli | 
| 문자열 | Varchar | 
| 바이트 | Varbinary | 
| BigDecimal | 10진수 | 
| ARRAY | List | 

## 파티션 및 분할
<a name="connectors-mysql-partitions-and-splits"></a>

파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다.

## 성능
<a name="connectors-mysql-performance"></a>

MySQL은 기본 파티션을 지원합니다. Athena MySQL 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다.

Athena MySQL 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다.

### LIMIT 절
<a name="connectors-mysql-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-mysql-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-mysql-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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/)를 참조하세요.

## 패스스루 쿼리
<a name="connectors-mysql-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-mysql-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-mysql-additional-resources"></a>

최신 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 커넥터
<a name="connectors-neptune"></a>

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에 대한 읽기 액세스 권한을 가지고 있어야 합니다.

## 사전 조건
<a name="connectors-neptune-prerequisites"></a>

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 커넥터 배포)를 참조하세요.

## 제한 사항
<a name="connectors-neptune-limitations"></a>

현재 Neptune 커넥터에는 다음과 같은 제한 사항이 있습니다.
+ 프라이머리 키(ID)를 비롯한 예측 열은 지원되지 않습니다.

## Neptune 클러스터 설정
<a name="connectors-neptune-setting-up-a-neptune-cluster"></a>

사용하려는 기존 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 설정
<a name="connectors-neptune-setting-up-an-aws-glue-data-catalog"></a>

기존의 관계형 데이터 스토어와 달리 Neptune 그래프 DB 노드 및 엣지는 세트 스키마를 사용하지 않습니다. 항목마다 필드와 데이터 형식이 다를 수 있습니다. 그러나 Neptune 커넥터는 AWS Glue Data Catalog에서 메타데이터를 검색하기 때문에 필요한 스키마가 포함된 테이블이 있는 AWS Glue 데이터베이스를 생성해야 합니다. AWS Glue 데이터베이스 및 테이블을 생성한 후 커넥터는 Athena에서 쿼리할 수 있는 테이블 목록을 채울 수 있습니다.

### 대소문자를 구분하지 않는 열 일치 활성화
<a name="connectors-neptune-glue-case-insensitive-column-matching"></a>

AWS Glue에서 열 이름이 모두 소문자인 경우에도 Neptune 테이블의 열 이름을 올바른 대소문자로 확인하려면 대소문자를 구분하지 않도록 Neptune 커넥터를 구성할 수 있습니다.

이 기능을 활성화하려면 Neptune 커넥터 Lambda 함수의 `enable_caseinsensitivematch` 환경 변수를 `true`로 설정합니다.

### 대소문자를 구분하는 테이블 이름의 경우 AWS Glue glabel 테이블 파라미터 지정
<a name="connectors-neptune-glue-glabel-parameter-for-table-names"></a>

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)를 참조하세요.

## 성능
<a name="connectors-neptune-performance"></a>

쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Neptune 커넥터에서 조건자 푸시다운을 수행합니다. 그러나 조건자에서 프라이머리 키를 사용하면 쿼리가 실패하게 됩니다. `LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자를 제공하지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. Neptune 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

## 패스스루 쿼리
<a name="connectors-neptune-passthrough-queries"></a>

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()' 
        ))
```

## 추가 리소스
<a name="connectors-neptune-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune)를 참조하세요.

# Amazon Athena OpenSearch 커넥터
<a name="connectors-opensearch"></a>

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에 대한 읽기 액세스 권한을 가지고 있어야 합니다.

## 사전 조건
<a name="connectors-opensearch-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 용어
<a name="connectors-opensearch-terms"></a>

다음 용어는 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) 섹션을 참조하세요.

## 파라미터
<a name="connectors-opensearch-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="opensearch-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="opensearch-legacy"></a>
+ **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에서 데이터베이스 및 테이블 설정
<a name="connectors-opensearch-setting-up-databases-and-tables-in-aws-glue"></a>

커넥터는 AWS Glue 또는 OpenSearch를 사용하여 메타데이터 정보를 가져옵니다. AWS Glue 테이블을 보충 메타데이터 정의 소스로 설정할 수 있습니다. 이 기능을 활성화하려면 보충하려는 소스의 도메인 및 인덱스와 일치하는 AWS Glue 데이터베이스 및 테이블을 정의합니다. 커넥터는 지정된 인덱스에 대한 매핑을 검색하여 OpenSearch 인스턴스에 저장된 메타데이터 정의를 활용할 수도 있습니다.

### OpenSearch에서 배열에 대한 메타데이터 정의
<a name="connectors-opensearch-defining-metadata-for-arrays-in-opensearch"></a>

OpenSearch에는 전용 배열 데이터 형식이 없습니다. 데이터 형식이 같으면 모든 필드에 0개 이상의 값이 포함될 수 있습니다. OpenSearch를 메타데이터 정의 소스로 사용하려면 목록 또는 배열로 간주될 필드에 대해 Athena와 함께 사용되는 모든 인덱스에 대해 `_meta` 속성을 정의해야 합니다. 이 단계를 완료하지 못하면 쿼리는 목록 필드의 첫 번째 요소만 반환합니다. `_meta` 속성을 지정할 때 필드 이름은 중첩 JSON 구조에 대해 정규화되어야 합니다(예: `address.street` 여기서 `street`는 `address` 구조 내부의 중첩 필드임).

다음 예제는 `movies` 테이블에 `actor` 및 `genre` 목록을 정의합니다.

```
PUT movies/_mapping 
{ 
  "_meta": { 
    "actor": "list", 
    "genre": "list" 
  } 
}
```

### 데이터 타입
<a name="connectors-opensearch-data-types"></a>

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 | 

#### 데이터 형식에 대한 참고 사항
<a name="connectors-opensearch-data-type-considerations-and-limitations"></a>
+ 현재 커넥터는 앞의 표에 나열된 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 쿼리 실행
<a name="connectors-opensearch-running-sql-queries"></a>

다음은 이 커넥터에서 사용할 수 있는 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
```

## 성능
<a name="connectors-opensearch-performance"></a>

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)
```

## 패스스루 쿼리
<a name="connectors-opensearch-passthrough-queries"></a>

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''}}}}"
        ))
```

## 추가 리소스
<a name="connectors-opensearch-additional-resources"></a>
+ 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 커넥터
<a name="connectors-oracle"></a>

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의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-oracle-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-oracle-limitations"></a>
+ 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=<number of decimal places>`를 지정합니다.

## 용어
<a name="connectors-oracle-terms"></a>

다음 용어는 Oracle 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-oracle-parameters"></a>

이 섹션의 파라미터를 사용하여 Oracle 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="oracle-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="oracle-legacy"></a>

**참고**  
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에서 스키마 및 테이블 이름에 대해 대소문자를 구분하지 않는 검색을 수행합니다. 쿼리에 커넥터의 기본 대소문자와 일치하지 않는 스키마 또는 테이블 이름이 포함된 경우 이 값을 사용합니다.

#### 연결 문자열
<a name="connectors-oracle-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
oracle://${jdbc_connection_string}
```

**참고**  
암호에 특수 문자(예: `some.password`)가 포함된 경우 연결 문자열에 암호를 전달할 때 암호를 큰따옴표로 묶습니다(예: `"some.password"`). 이렇게 하지 않으면 Invalid Oracle URL specified 오류가 발생할 수 있습니다.

#### 단일 연결 핸들러 사용
<a name="connectors-oracle-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Oracle 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | OracleCompositeHandler | 
| 메타데이터 핸들러 | OracleMetadataHandler | 
| 레코드 핸들러 | OracleRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-oracle-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| 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=<HOST\$1NAME>)(PORT=))(CONNECT\$1DATA=(SID=))(SECURITY=(SSL\$1SERVER\$1CERT\$1DN=))) | 

#### 자격 증명 제공
<a name="connectors-oracle-providing-credentials"></a>

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 속성을 인식합니다.

#### 멀티플렉싱 핸들러 사용
<a name="connectors-oracle-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | OracleMuxCompositeHandler | 
| 메타데이터 핸들러 | OracleMuxMetadataHandler | 
| 레코드 핸들러 | OracleMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-oracle-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

## 데이터 형식 지원
<a name="connectors-oracle-data-type-support"></a>

다음 표에 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 | 

## 파티션 및 분할
<a name="connectors-oracle-partitions-and-splits"></a>

파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다.

## 성능
<a name="connectors-oracle-performance"></a>

Oracle은 기본 파티션을 지원합니다. Athena Oracle 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. Oracle 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다. 하지만 쿼리 런타임이 길어지는 경향이 있습니다.

쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Oracle 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다.

### Predicates
<a name="connectors-oracle-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-oracle-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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%');
```

## 패스스루 쿼리
<a name="connectors-oracle-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-oracle-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-oracle-additional-resources"></a>

최신 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 커넥터
<a name="connectors-postgresql"></a>

Amazon Athena PostgreSQL 커넥터를 사용하면 Athena에서 PostgreSQL 데이터베이스에 액세스할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-postgres-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-postgresql-limitations"></a>
+ 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)를 참조하세요.

## 용어
<a name="connectors-postgresql-terms"></a>

다음 용어는 PostgreSQL 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-postgresql-parameters"></a>

이 섹션의 파라미터를 사용하여 PostgreSQL 커넥터를 구성합니다.

**참고**  
2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다.

### Glue 연결(권장)
<a name="connectors-postgresql-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-postgresql-connection-legacy"></a>

아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다.

#### 연결 문자열
<a name="connectors-postgresql-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
postgres://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-postgresql-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | PostGreSqlMuxCompositeHandler | 
| 메타데이터 핸들러 | PostGreSqlMuxMetadataHandler | 
| 레코드 핸들러 | PostGreSqlMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-postgresql-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-postgresql-providing-credentials"></a>

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 활성화
<a name="connectors-postgresql-ssl"></a>

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
```

#### 단일 연결 핸들러 사용
<a name="connectors-postgresql-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 PostgreSQL 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | PostGreSqlCompositeHandler | 
| 메타데이터 핸들러 | PostGreSqlMetadataHandler | 
| 레코드 핸들러 | PostGreSqlRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-postgresql-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 PostgreSQL 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | postgres://jdbc:postgresql://postgres1.host:5432/default?secret=\$1\$1Test/RDS/PostgreSQL1\$1 | 

#### 유출 파라미터
<a name="connectors-postgresql-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-postgresql-data-type-support"></a>

다음 표에 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` 형식은 다차원 배열(`<data_type>[][]` 또는 중첩 배열)은 지원되지 않는다는 제약 조건이 있는 PostgreSQL 커넥터에 대해 지원됩니다. 지원되지 않는 `ARRAY` 데이터 형식이 있는 열은 문자열 요소의 배열(`array<varchar>`)로 변환됩니다.

## 파티션 및 분할
<a name="connectors-postgresql-partitions-and-splits"></a>

파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다.

## 성능
<a name="connectors-postgresql-performance"></a>

PostgreSQL은 기본 파티션을 지원합니다. Athena PostgreSQL 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다.

Athena PostgreSQL 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. 그러나 열 하위 세트를 선택할 때 쿼리 실행 런타임이 길어지는 경우가 있습니다.

### LIMIT 절
<a name="connectors-postgres-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-postgres-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-postgres-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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;
```

## 패스스루 쿼리
<a name="connectors-postgres-passthrough-queries"></a>

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'
        ))
```

## 추가 리소스
<a name="connectors-postgresql-additional-resources"></a>

최신 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 커넥터
<a name="connectors-redis"></a>

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)를 지원합니다.

## 사전 조건
<a name="connectors-redis-prerequisites"></a>
+ 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) 섹션을 참조하세요.

## 파라미터
<a name="connectors-redis-parameters"></a>

이 섹션의 파라미터를 사용하여 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에서 데이터베이스 및 테이블 설정
<a name="connectors-redis-setting-up-databases-and-tables-in-glue"></a>

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)를 참조하세요.

## 데이터 타입
<a name="connectors-redis-data-types"></a>

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 | 

## 필수 권한
<a name="connectors-redis-required-permissions"></a>

이 커넥터에 필요한 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에 인터페이스를 연결하고 분리하는 기능이 커넥터에 필요합니다.

## 성능
<a name="connectors-redis-performance"></a>

Athena Redis OSS 커넥터는 사용자가 정의한 테이블 유형(예: zset 키 또는 접두사 키)에 따라 Redis OSS 인스턴스에 대한 쿼리 병렬화를 시도합니다.

쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Redis 커넥터에서 조건자 푸시다운을 수행합니다. 그러나 프라이머리 키에 대한 조건자를 포함하는 쿼리는 시간 초과로 실패합니다. `LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자를 제공하지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. Redis 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

## 패스스루 쿼리
<a name="connectors-redis-passthrough-queries"></a>

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 => '[]'
))
```

## 라이선스 정보
<a name="connectors-redis-license-information"></a>

Amazon Athena Redis 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다.

## 추가 리소스
<a name="connectors-redis-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redis)를 참조하세요.

# Amazon Athena Redshift 커넥터
<a name="connectors-redshift"></a>

Amazon Athena Redshift 커넥터를 사용하면 Amazon Athena에서 Amazon Redshift 데이터베이스 및 Redshift Serverless 뷰를 포함하는 Amazon Redshift Serverless 데이터베이스에 액세스할 수 있습니다. 이 페이지에 설명된 JDBC 연결 문자열 구성 설정을 사용하여 두 서비스 중 하나에 연결할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-redshift-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-redshift-limitations"></a>
+ 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` 형식의 후행 공백은 유의미한 것으로 취급합니다.

## 용어
<a name="connectors-redshift-terms"></a>

다음 용어는 Redshift 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-redshift-parameters"></a>

이 섹션의 파라미터를 사용하여 Redshift 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="redshift-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="redshift-legacy"></a>

**참고**  
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 계정에서 메타데이터를 가져오려고 시도합니다.

#### 연결 문자열
<a name="connectors-redshift-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
redshift://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-redshift-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | RedshiftMuxCompositeHandler | 
| 메타데이터 핸들러 | RedshiftMuxMetadataHandler | 
| 레코드 핸들러 | RedshiftMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-redshift-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-redshift-providing-credentials"></a>

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 속성을 인식합니다.

## 데이터 형식 지원
<a name="connectors-redshift-data-type-support"></a>

다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다.


****  

| JDBC | 화살표 | 
| --- | --- | 
| 부울 | Bit | 
| Integer | Tiny | 
| Short | Smallint | 
| Integer | 정수 | 
| Long | Bigint | 
| 실수 | Float4 | 
| 배정밀도 실수 | Float8 | 
| 날짜 | DateDay | 
| 타임스탬프 | DateMilli | 
| 문자열 | Varchar | 
| 바이트 | Varbinary | 
| BigDecimal | 10진수 | 
| ARRAY | List | 

## 파티션 및 분할
<a name="connectors-redshift-partitions-and-splits"></a>

Redshift는 외부 파티션을 지원하지 않습니다. 성능 관련 문제에 대한 자세한 내용을 알아보려면 [성능](#connectors-redshift-performance) 섹션을 참조하세요.

## 성능
<a name="connectors-redshift-performance"></a>

Athena Redshift 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, `ORDER BY` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. 그러나 열 하위 세트를 선택할 때 쿼리 실행 런타임이 길어지는 경우가 있습니다. Amazon Redshift는 여러 쿼리를 동시에 실행할 때 특히 쿼리 실행 속도 저하에 취약합니다.

### LIMIT 절
<a name="connectors-redshift-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### 상위 N개 쿼리
<a name="connectors-redshift-performance-top-n-queries"></a>

상위 `N`개 쿼리는 결과 세트의 순서와 반환되는 행 수에 대한 한도를 지정합니다. 이 유형의 쿼리를 사용하여 데이터 세트에 대해 상위 `N`개의 최댓값 또는 상위 `N`개의 최솟값을 결정할 수 있습니다. 상위 `N`개의 푸시다운을 통해 커넥터는 Athena에 `N`개의 정렬된 행만 반환합니다.

### Predicates
<a name="connectors-redshift-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-redshift-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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/)를 참조하세요.

## 패스스루 쿼리
<a name="connectors-redshift-passthrough-queries"></a>

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'
        ))
```

## 추가 리소스
<a name="connectors-redshift-additional-resources"></a>

최신 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 커넥터
<a name="connectors-sap-hana"></a>

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-saphana-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-sap-hana-limitations"></a>
+ 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"
  ```

## 용어
<a name="connectors-sap-hana-terms"></a>

다음 용어는 SAP HANA 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-sap-hana-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-sap-hana-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-sap-hana-legacy"></a>

#### 연결 문자열
<a name="connectors-sap-hana-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
saphana://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-sap-hana-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | SaphanaMuxCompositeHandler | 
| 메타데이터 핸들러 | SaphanaMuxMetadataHandler | 
| 레코드 핸들러 | SaphanaMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-sap-hana-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-sap-hana-providing-credentials"></a>

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 속성을 인식합니다.

#### 단일 연결 핸들러 사용
<a name="connectors-sap-hana-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 SAP HANA 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | SaphanaCompositeHandler | 
| 메타데이터 핸들러 | SaphanaMetadataHandler | 
| 레코드 핸들러 | SaphanaRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-sap-hana-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 SAP HANA 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | saphana://jdbc:sap://saphana1.host:port/?secret=Test/RDS/Saphana1 | 

#### 유출 파라미터
<a name="connectors-sap-hana-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-sap-hana-data-type-support"></a>

다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다.


****  

| JDBC | 화살표 | 
| --- | --- | 
| 부울 | Bit | 
| Integer | Tiny | 
| Short | Smallint | 
| Integer | 정수 | 
| Long | Bigint | 
| 실수 | Float4 | 
| 배정밀도 실수 | Float8 | 
| 날짜 | DateDay | 
| 타임스탬프 | DateMilli | 
| 문자열 | Varchar | 
| 바이트 | Varbinary | 
| BigDecimal | 10진수 | 
| ARRAY | List | 

## 데이터 형식 변환
<a name="connectors-sap-hana-data-type-conversions"></a>

JDBC에서 Arrow로의 변환 외에도 커넥터는 SAP HANA 소스와 Athena 데이터 형식이 호환되도록 다른 특정 변환을 수행합니다. 이러한 변환은 쿼리가 성공적으로 실행되도록 하는 데 도움이 됩니다. 다음 표에 이러한 변환이 나와 있습니다.


****  

| 소스 데이터 형식(SAP HANA) | 변환된 데이터 형식(Athena) | 
| --- | --- | 
| DECIMAL | BIGINT | 
| INTEGER | INT | 
| DATE | DATEDAY | 
| TIMESTAMP | DATEMILLI | 

지원되지 않는 다른 모든 데이터 형식은 `VARCHAR`로 변환됩니다.

## 파티션 및 분할
<a name="connectors-sap-hana-partitions-and-splits"></a>

파티션은 `Integer` 형식의 단일 파티션 열로 표시됩니다. 열에는 SAP HANA 테이블에 정의된 파티션의 이름이 들어 있습니다. 파티션 이름이 없는 테이블의 경우 단일 파티션에 해당하는 \$1가 반환됩니다. 파티션은 분할과 동일합니다.


****  

| 이름 | Type | 설명 | 
| --- | --- | --- | 
| PART\$1ID | Integer | SAP HANA의 명명된 파티션. | 

## 성능
<a name="connectors-sap-hana-performance"></a>

SAP HANA는 기본 파티션을 지원합니다. Athena SAP HANA 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. 이 커넥터는 동시성으로 인해 상당한 제한을 나타나며 경우에 따라 쿼리 오류가 발생할 수 있습니다.

Athena SAP HANA 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다.

### LIMIT 절
<a name="connectors-saphana-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-saphana-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-saphana-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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;
```

## 패스스루 쿼리
<a name="connectors-saphana-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-saphana-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-saphana-additional-resources"></a>

최신 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 커넥터
<a name="connectors-snowflake"></a>

[Snowflake](https://www.snowflake.com/)용 Amazon Athena 커넥터를 사용하면 Amazon Athena가 JDBC를 사용하여 Snowflake SQL 데이터베이스 또는 RDS 인스턴스에 저장된 데이터에 대해 SQL 쿼리를 실행할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-snowflake-prerequisites"></a>

Athena 콘솔 또는 `CreateDataCatalog` API 작업을 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-snowflake-limitations"></a>
+ 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`)를 사용하여 대소문자 구분 동작을 제어할 수 있습니다.

## 용어
<a name="connectors-snowflake-terms"></a>

다음 용어는 Snowflake 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-snowflake-parameters"></a>

이 섹션의 파라미터를 사용하여 Snowflake 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="snowflake-gc"></a>

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) 섹션을 참조하세요.

### 레거시 연결
<a name="snowflake-legacy"></a>

**참고**  
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)를 사용하는 경우 성능이 향상될 수 있습니다.

#### 연결 문자열
<a name="connectors-snowflake-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
snowflake://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-snowflake-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | SnowflakeMuxCompositeHandler | 
| 메타데이터 핸들러 | SnowflakeMuxMetadataHandler | 
| 레코드 핸들러 | SnowflakeMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-snowflake-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-snowflake-providing-credentials"></a>

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* 형식의 사용자 이름과 암호를 허용합니다.

#### 단일 연결 핸들러 사용
<a name="connectors-snowflake-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Snowflake 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | SnowflakeCompositeHandler | 
| 메타데이터 핸들러 | SnowflakeMetadataHandler | 
| 레코드 핸들러 | SnowflakeRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-snowflake-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Snowflake 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | snowflake://jdbc:snowflake://snowflake1.host:port/?secret=Test/RDS/Snowflake1 | 

#### 유출 파라미터
<a name="connectors-snowflake-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-snowflake-data-type-support"></a>

다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다.


****  

| JDBC | 화살표 | 
| --- | --- | 
| 부울 | Bit | 
| Integer | Tiny | 
| Short | Smallint | 
| Integer | 정수 | 
| Long | Bigint | 
| 실수 | Float4 | 
| 배정밀도 실수 | Float8 | 
| 날짜 | DateDay | 
| 타임스탬프 | DateMilli | 
| 문자열 | Varchar | 
| 바이트 | Varbinary | 
| BigDecimal | 10진수 | 
| ARRAY | List | 

## 데이터 형식 변환
<a name="connectors-snowflake-data-type-conversions"></a>

JDBC에서 Arrow로의 변환 외에도 커넥터는 Snowflake 소스와 Athena 데이터 형식이 호환되도록 다른 특정 변환을 수행합니다. 이러한 변환은 쿼리가 성공적으로 실행되도록 하는 데 도움이 됩니다. 다음 표에 이러한 변환이 나와 있습니다.


****  

| 소스 데이터 형식(Snowflake) | 변환된 데이터 형식(Athena) | 
| --- | --- | 
| TIMESTAMP | TIMESTAMPMILLI | 
| DATE | TIMESTAMPMILLI | 
| INTEGER | INT | 
| DECIMAL | BIGINT | 
| TIMESTAMP\$1NTZ | TIMESTAMPMILLI | 

지원되지 않는 다른 모든 데이터 형식은 `VARCHAR`로 변환됩니다.

## 파티션 및 분할
<a name="connectors-snowflake-partitions-and-splits"></a>

파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다.

이 합성 열과 파티션을 생성하려면 Athena에 프라이머리 키를 정의해야 합니다. 하지만 Snowflake는 프라이머리 키 제약 조건을 적용하지 않으므로 고유성을 직접 적용해야 합니다. 그렇지 않으면 Athena는 단일 분할을 기본값으로 설정하게 됩니다.

## 성능
<a name="connectors-snowflake-performance"></a>

최적의 성능을 위해 가능하면 쿼리에 필터를 사용합니다. 또한 파티션 배포가 균일한 방대한 데이터 세트를 검색하려면 기본 파티셔닝을 사용하는 것이 좋습니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. Snowflake 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

Athena Snowflake 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다.

### LIMIT 절
<a name="connectors-snowflake-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-snowflake-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-snowflake-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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로 인증
<a name="connectors-snowflake-authentication"></a>

키 페어 인증 또는 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)을 참조하세요.

## 사전 조건
<a name="connectors-snowflake-authentication-prerequisites"></a>

시작하기 전에 다음 필수 조건을 완료합니다.
+ 관리 권한이 있는 Snowflake 계정 액세스입니다.
+ Athena 커넥터 전용 Snowflake 사용자 계정입니다.
+ 키 페어 인증을 위한 OpenSSL 또는 동등한 키 생성 도구입니다.
+ AWS Secrets Manager에 액세스하여 보안 암호를 생성하고 관리합니다.
+ OAuth 인증을 위한 OAuth 흐름을 완료하는 웹 브라우저입니다.

## 키 페어 인증 구성
<a name="connectors-snowflake-keypair-authentication"></a>

이 프로세스에는 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 인증 구성
<a name="connectors-snowflake-oauth-authentication"></a>

이 인증 방법을 사용하면 자동 자격 증명 새로 고침 기능을 통해 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://<your_account>.snowflakecomputing.com/oauth/authorize?client_id=<OAUTH_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=<authorizationcode>
      ```
**참고**  
권한 부여 코드는 제한된 시간 동안 유효하며 한 번만 사용할 수 있습니다.

1. **AWS Secrets Manager에 OAuth 자격 증명 저장**

   다음 구조를 사용하여 AWS Secrets Manager에서 보안 암호를 생성합니다.

   ```
   {
     "redirect_uri": "https://localhost:8080/oauth/callback",
     "client_secret": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY",
     "token_url": "https://<your_account>.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을 가져옵니다.

## 패스스루 쿼리
<a name="connectors-snowflake-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-snowflake-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-snowflake-additional-resources"></a>

최신 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 커넥터
<a name="connectors-microsoft-sql-server"></a>

[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의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-sqlserver-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-microsoft-sql-server-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.
+ 필터 조건에서 `Date` 및 `Timestamp` 데이터 형식을 적절한 데이터 형식으로 캐스팅해야 합니다.
+ `Real` 및 `Float` 형식의 음수 값을 검색하려면 `<=` 또는 `>=` 연산자를 사용합니다.
+ `binary`, `varbinary`, `image` 및 `rowversion` 데이터 형식은 지원되지 않습니다.

## 용어
<a name="connectors-microsoft-sql-server-terms"></a>

다음 용어는 SQL Server 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-microsoft-sql-server-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-microsoft-sql-server-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-microsoft-sql-server-legacy"></a>

#### 연결 문자열
<a name="connectors-microsoft-sql-server-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
sqlserver://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-microsoft-sql-server-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | SqlServerMuxCompositeHandler | 
| 메타데이터 핸들러 | SqlServerMuxMetadataHandler | 
| 레코드 핸들러 | SqlServerMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-microsoft-sql-server-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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=<database\$1name>;\$1\$1secret1\$1name\$1 | 
| sqlserver\$1catalog1\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=<database\$1name>;\$1\$1secret1\$1name\$1 | 
| sqlserver\$1catalog2\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver2.hostname:port;databaseName=<database\$1name>;\$1\$1secret2\$1name\$1 | 

##### 자격 증명 제공
<a name="connectors-microsoft-sql-server-providing-credentials"></a>

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=<database_name>;${secret_name}
```

커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다.

```
sqlserver://jdbc:sqlserver://hostname:port;databaseName=<database_name>;user=<user>;password=<password>
```

#### 단일 연결 핸들러 사용
<a name="connectors-microsoft-sql-server-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 SQL Server 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | SqlServerCompositeHandler | 
| 메타데이터 핸들러 | SqlServerMetadataHandler | 
| 레코드 핸들러 | SqlServerRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-microsoft-sql-server-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 SQL Server 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | sqlserver://jdbc:sqlserver://hostname:port;databaseName=<database\$1name>;\$1\$1secret\$1name\$1 | 

#### 유출 파라미터
<a name="connectors-microsoft-sql-server-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-microsoft-sql-server-data-type-support"></a>

다음 표에 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 | 

## 파티션 및 분할
<a name="connectors-microsoft-sql-server-partitions-and-splits"></a>

파티션은 `varchar` 형식의 단일 파티션 열로 표시됩니다. SQL Server 커넥터의 경우 파티션 함수에 따라 테이블에 파티션이 적용되는 방식이 결정됩니다. 파티션 함수 및 열 이름 정보는 SQL Server 메타데이터 테이블에서 검색됩니다. 그런 다음 사용자 지정 쿼리가 파티션을 가져옵니다. 분할은 수신된 개별 파티션 수를 기준으로 생성됩니다.

## 성능
<a name="connectors-microsoft-sql-server-performance"></a>

열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. SQL Server 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

쿼리에서 스캔하는 데이터를 줄이기 위해 Athena SQL Server 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다.

### Predicates
<a name="connectors-sqlserver-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-sqlserver-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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%');
```

## 패스스루 쿼리
<a name="connectors-sqlserver-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-sqlserver-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-sqlserver-additional-resources"></a>

최신 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 커넥터
<a name="connectors-teradata"></a>

 Teradata용 Amazon Athena 커넥터를 사용하면 Athena가 Teradata 데이터베이스에 저장된 데이터에 대해 SQL 쿼리를 실행할 수 있습니다.

이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다.

## 사전 조건
<a name="connectors-teradata-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-teradata-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.

## 용어
<a name="connectors-teradata-terms"></a>

다음 용어는 Teradata 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-teradata-parameters"></a>

이 섹션의 파라미터를 사용하여 Teradata 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="connectors-teradata-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-teradata-legacy"></a>

#### 연결 문자열
<a name="connectors-teradata-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
teradata://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-teradata-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | TeradataMuxCompositeHandler | 
| 메타데이터 핸들러 | TeradataMuxMetadataHandler | 
| 레코드 핸들러 | TeradataMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-teradata-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$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 | 

##### 자격 증명 제공
<a name="connectors-teradata-providing-credentials"></a>

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* 형식의 사용자 이름과 암호를 허용합니다.

#### 단일 연결 핸들러 사용
<a name="connectors-teradata-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Teradata 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | TeradataCompositeHandler | 
| 메타데이터 핸들러 | TeradataMetadataHandler | 
| 레코드 핸들러 | TeradataRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-teradata-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 Teradata 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,secret=Test/RDS/Teradata1 | 

#### 유출 파라미터
<a name="connectors-teradata-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-teradata-data-type-support"></a>

다음 표에 JDBC와 Apache Arrow의 해당 데이터 형식이 나와 있습니다.


****  

| JDBC | 화살표 | 
| --- | --- | 
| 부울 | Bit | 
| Integer | Tiny | 
| Short | Smallint | 
| Integer | 정수 | 
| Long | Bigint | 
| 실수 | Float4 | 
| 배정밀도 실수 | Float8 | 
| 날짜 | DateDay | 
| 타임스탬프 | DateMilli | 
| 문자열 | Varchar | 
| 바이트 | Varbinary | 
| BigDecimal | 10진수 | 
| ARRAY | List | 

## 파티션 및 분할
<a name="connectors-teradata-partitions-and-splits"></a>

파티션은 `Integer` 형식의 단일 파티션 열로 표시됩니다. 열에는 Teradata 테이블에 정의된 파티션의 이름이 들어 있습니다. 파티션 이름이 없는 테이블의 경우 단일 파티션에 해당하는 \$1가 반환됩니다. 파티션은 분할과 동일합니다.


****  

| 이름 | Type | 설명 | 
| --- | --- | --- | 
| 파티션 | Integer | Teradata의 명명된 파티션. | 

## 성능
<a name="connectors-teradata-performance"></a>

Teradata는 기본 파티션을 지원합니다. Athena Teradata 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다. 열 하위 집합을 선택하면 쿼리 런타임이 크게 느려집니다. 이 커넥터는 동시성으로 인해 약간의 제한을 나타냅니다.

쿼리에서 스캔하는 데이터를 줄이기 위해 Athena Teradata 커넥터에서 조건자 푸시다운을 수행합니다. 스캔하는 데이터와 쿼리 실행 시간을 줄이도록 간단한 조건자와 복잡한 표현식을 커넥터로 푸시다운합니다.

### Predicates
<a name="connectors-teradata-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 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

### 결합된 푸시다운 예제
<a name="connectors-teradata-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
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%');
```

## 패스스루 쿼리
<a name="connectors-teradata-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-teradata-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-teradata-additional-resources"></a>

최신 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 커넥터
<a name="connectors-timestream"></a>

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에 대한 읽기 액세스 권한을 가지고 있어야 합니다.

## 사전 조건
<a name="connectors-timestream-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 파라미터
<a name="connectors-timestream-parameters"></a>

이 섹션의 파라미터를 사용하여 Timestream 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="connectors-timestream-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-timestream-legacy"></a>

**참고**  
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에서 데이터베이스 및 테이블 설정
<a name="connectors-timestream-setting-up-databases-and-tables-in-aws-glue"></a>

필요에 따라 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에 적합한 데이터 형식을 사용해야 합니다.

### 데이터 타입
<a name="connectors-timestream-data-types"></a>

현재 Timestream 커넥터는 Timestream에서 사용 가능한 데이터 형식의 하위 세트, 특히 스칼라 값 `varchar`, `double` 및 `timestamp`만 지원합니다.

`timeseries` 데이터 형식을 쿼리하려면 Timestream `CREATE_TIME_SERIES` 함수를 사용하는 AWS Glue 테이블 속성에서 보기를 구성해야 합니다. 또한 시계열 열의 유형으로 `ARRAY<STRUCT<time:timestamp,measure_value::double:double>>` 구문을 사용하는 보기에 대한 스키마를 제공해야 합니다. `double`을 테이블에 적합한 스칼라 유형으로 바꿉니다.

다음 이미지는 시계열에 대한 보기를 설정하도록 구성된 AWS Glue 테이블 속성의 예제를 보여줍니다.

![\[AWS Glue에서 테이블 속성을 구성하여 시계열에 대한 보기 설정.\]](http://docs.aws.amazon.com/ko_kr/athena/latest/ug/images/connectors-timestream-1.png)


## 필수 권한
<a name="connectors-timestream-required-permissions"></a>

이 커넥터에 필요한 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 쿼리를 실행하는 데 사용됩니다.

## 성능
<a name="connectors-timestream-performance"></a>

대화형 쿼리가 제대로 작동하려면 반환되는 데이터(스캔되는 데이터 아님)를 256MB 미만으로 제한하는 `LIMIT` 절을 사용하는 것이 좋습니다.

Athena Timestream 커넥터는 조건자 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절은 스캔하는 데이터를 줄이지만 조건자가 제공되지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. 열의 하위 집합을 선택하면 쿼리 런타임 속도를 높이고 스캔되는 데이터를 줄일 수 있습니다. Timestream 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

## 패스스루 쿼리
<a name="connectors-timestream-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-timestream-license-information"></a>

Amazon Athena Timestream 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다.

## 추가 리소스
<a name="connectors-timestream-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-timestream)를 참조하세요.

# Amazon Athena TPC Benchmark DS(TPC-DS) 커넥터
<a name="connectors-tpcds"></a>

Amazon Athena TPC-DS 커넥터를 통해 Amazon Athena는 Athena Federation의 벤치마킹 및 기능 테스트에 사용하기 위해 무작위로 생성된 TPC 벤치마크 DS 데이터 소스와 통신할 수 있습니다. Athena TPC-DS 커넥터는 네 가지 확장 요소 중 하나로 TPC-DS 호환 데이터베이스를 생성합니다. Amazon S3 기반 데이터 레이크 성능 테스트의 대안으로 이 커넥터를 사용하지 않는 것이 좋습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-tpcds-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 파라미터
<a name="connectors-tpcds-parameters"></a>

이 섹션의 파라미터를 사용하여 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 연결(권장)
<a name="connectors-tpcds-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-tpcds-legacy"></a>
+ **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)를 사용하는 경우 성능이 향상될 수 있습니다.

## 데이터베이스 및 테이블 테스트
<a name="connectors-tpcds-test-databases-and-tables"></a>

Athena TPC-DS 커넥터는 4개의 스케일 팩터 `tpcds1`, `tpcds10`, `tpcds100`, `tpcds250` 또는 `tpcds1000` 중 하나로 TPC-DS 호환 데이터베이스를 생성합니다.

### 테이블 요약
<a name="connectors-tpcds-table-summary"></a>

테스트 데이터 테이블 및 열의 전체 목록을 보려면 `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) 디렉터리를 참조하세요.

### 예제 쿼리
<a name="connectors-tpcds-example-query"></a>

다음 `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
```

## 필수 권한
<a name="connectors-tpcds-required-permissions"></a>

이 커넥터에 필요한 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 쿼리가 종료된 경우 이 권한을 사용하여 빠른 실패를 수행합니다.

## 성능
<a name="connectors-tpcds-performance"></a>

Athena TPC-DS 커넥터는 선택한 스케일 팩터를 기준으로 쿼리 병렬화를 시도합니다. 조건자 푸시다운은 Lambda 함수 내에서 수행됩니다.

## 라이선스 정보
<a name="connectors-tpcds-license-information"></a>

Amazon Athena TPC-DS 커넥터 프로젝트는 [Apache-2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0.html)에 따라 사용이 허가됩니다.

## 추가 리소스
<a name="connectors-tpcds-additional-resources"></a>

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds)를 참조하세요.

# Amazon Athena Vertica 커넥터
<a name="connectors-vertica"></a>

Vertica는 클라우드 또는 온프레미스에 배포할 수 있는 열 형식 데이터베이스 플랫폼으로서 엑사바이트 규모의 데이터 웨어하우스를 지원합니다. 연합 쿼리에 Amazon Athena Vertica 커넥터를 사용하여 Athena에서 Vertica 데이터 원본을 쿼리할 수 있습니다. 예를 들어 Vertica의 데이터 웨어하우스와 Amazon S3의 데이터 레이크에 대해 분석 쿼리를 실행할 수 있습니다.

이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화하지 않습니다. 연결 구성은 Lambda를 통해 수행됩니다.

## 사전 조건
<a name="connectors-vertica-prerequisites"></a>
+ 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) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-vertica-limitations"></a>
+ 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)을 참조하세요.

## 워크플로
<a name="connectors-vertica-workflow"></a>

다음 다이어그램은 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에서 반환된 데이터를 처리하고 결과를 반환합니다.

## 용어
<a name="connectors-vertica-terms"></a>

다음 용어는 Vertica 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - Amazon EC2에 배포된 Vertica 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.

## 파라미터
<a name="connectors-vertica-parameters"></a>

이 섹션의 파라미터를 사용하여 Vertica 커넥터를 구성합니다.

### Glue 연결(권장)
<a name="connectors-vertica-gc"></a>

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만 지원합니다.

### 레거시 연결
<a name="connectors-vertica-legacy"></a>

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입니다.

#### 연결 문자열
<a name="connectors-vertica-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
vertica://jdbc:vertica://host_name:
                        port/database?user=vertica-username&password=
                        vertica-password
```

#### 단일 연결 핸들러 사용
<a name="connectors-vertica-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 Vertica 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | VerticaCompositeHandler | 
| 메타데이터 핸들러 | VerticaMetadataHandler | 
| 레코드 핸들러 | VerticaRecordHandler | 

#### 단일 연결 핸들러 파라미터
<a name="connectors-vertica-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

#### 자격 증명 제공
<a name="connectors-vertica-providing-credentials"></a>

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 속성을 인식합니다.

#### 유출 파라미터
<a name="connectors-vertica-spill-parameters"></a>

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)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-vertica-data-type-support"></a>

다음 표에 Vertica 커넥터의 지원되는 데이터 형식이 나와 있습니다.


****  

| 부울 | 
| --- | 
| BigInt | 
| Short | 
| Integer | 
| Long | 
| Float | 
| 배정밀도 실수 | 
| 날짜 | 
| Varchar | 
| 바이트 | 
| BigDecimal | 
| TimeStamp as Varchar | 

## 성능
<a name="connectors-vertica-performance"></a>

Lambda 함수는 프로젝션 푸시다운을 수행하여 쿼리에서 스캔되는 데이터를 줄입니다. `LIMIT` 절은 스캔되는 데이터의 양을 줄이지만 조건자가 제공되지 않으면 `LIMIT` 절을 포함하는 `SELECT` 쿼리가 최소 16MB의 데이터를 스캔할 것으로 예상해야 합니다. Vertica 커넥터는 동시성으로 인한 제한에 대한 복원력이 뛰어납니다.

## 패스스루 쿼리
<a name="connectors-vertica-passthrough-queries"></a>

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'
        ))
```

## 라이선스 정보
<a name="connectors-vertica-license-information"></a>

이 커넥터를 사용하면 이 커넥터에 대한 [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) 파일에 제공된 해당 타사 라이선스의 조건에 동의하는 것으로 간주됩니다.

## 추가 리소스
<a name="connectors-vertica-additional-resources"></a>

최신 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 데이터 소스 쿼리)를 참조하세요.