本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 可用資料來源連接器
本節列出預先建置的 Athena 資料來源連接器，供您用來查詢 Simple Storage Service (Amazon S3) 外部的各種資料來源。若要在 Athena 查詢中使用連接器，請設定連接器並將其部署到您的帳戶。
## 考量和限制
+ 某些預先建置的連接器要求您先建立 VPC 和安全群組，然後才能使用連接器。如需建立 VPC 的相關資訊，請參閱 [為資料來源連接器或 AWS Glue 連線建立 VPC](athena-connectors-vpc-creation.md)。
+ 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，您必須為 Secrets Manager 設定 Amazon VPC 私有端點。如需詳細資訊，請參閱《AWS Secrets Manager 使用者指南》**中的[建立 Secrets Manager VPC 私有端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)。
+ 對於不支援述詞下推的連接器，包含述詞的查詢需要較長時間才能執行。對於小型資料集，只會掃描極少的資料，而查詢平均需要大約 2 分鐘。但是，對於大型資料集，許多查詢可能會逾時。
+ 有些聯合資料來源使用術語來描述與 Athena 不同的資料物件。如需詳細資訊，請參閱[了解聯合資料表名稱限定詞](tables-qualifiers.md)。
+ 我們會根據資料庫或資料來源提供者的升級情況，定期更新連接器。我們不支援已終止支援的資料來源。
+ 針對列出資料表時不支援分頁的連接器，如果您的資料庫有許多資料表和中繼資料，Web 服務可能會逾時。下列連接器提供所列資料表的分頁支援：
+ DocumentDB
+ DynamoDB
+ MySQL
+ OpenSearch
+ Oracle
+ PostgreSQL
+ Redshift
+ SQL Server
## Federation SDK 中的案例解析程式模式
Federation SDK 支援下列適用於結構描述和資料表名稱的標準化案例解析程式模式：
+ `NONE` – 請勿變更指定的結構描述和資料表名稱的大小寫。
+ `LOWER` – 將所有指定的結構描述和資料表名稱轉換為小寫。
+ `UPPER` – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ `ANNOTATION` – 此模式僅為回溯相容性而保留，且僅由現有的 Snowflake 和 SAP HANA 連接器支援。
+ `CASE_INSENSITIVE_SEARCH` – 針對結構描述和資料表名稱執行不區分大小寫搜尋。
## 連接器支援案例解析程式模式
### 基本模式支援
所有 JDBC 連接器都支援下列基本模式：
+ `NONE`
+ `LOWER`
+ `UPPER`
### 註釋模式支援
只有下列連接器支援 `ANNOTATION` 模式：
+ Snowflake
+ SAP HANA
**注意**
建議使用 CASE\$1INSENSITIVE\$1SEARCH 而不是 ANNOTATION。
### 不區分大小寫搜尋支援
下列連接器支援 `CASE_INSENSITIVE_SEARCH`：
+ DataLake Gen2
+ Snowflake
+ Oracle
+ Synapse
+ MySQL
+ PostgreSQL
+ Redshift
+ ClickHouse
+ SQL Server
+ DB2
## 案例解析程式限制
使用案例解析程式模式時，請注意下列限制：
+ 使用 `LOWER` 模式時，您的結構描述名稱和結構描述中的所有資料表必須是小寫。
+ 使用 `UPPER` 模式時，您的結構描述名稱和結構描述中的所有資料表必須是大寫。
+ 使用 `CASE_INSENSITIVE_SEARCH` 時：
+ 結構描述名稱必須是唯一的
+ 結構描述中的資料表名稱必須是唯一的 (例如，"Apple" 和 "APPLE" 不能同時存在)
+ Glue 整合限制：
+ Glue 僅支援小寫名稱
+ 使用 GlueDataCatalog/LakeFormation 註冊 Lambda 函式時，只有 `NONE` 或 `LOWER` 模式才會運作
## 其他資訊
+ 如需有關部署 Athena 資料來源連接器的資訊，請參閱[使用 Amazon Athena 聯合查詢](federated-queries.md)。
+ 如需有關使用 Athena 資料來源連接器查詢的資訊，請參閱 [執行聯合查詢](running-federated-queries.md)。
**Topics**
+ [考量和限制](#connectors-available-considerations)
+ [Federation SDK 中的案例解析程式模式](#case-resolver-modes)
+ [連接器支援案例解析程式模式](#connector-support-matrix)
+ [案例解析程式限制](#case-resolver-limitations)
+ [其他資訊](#connectors-available-additional-resources)
+ [Azure Data Lake Storage](connectors-adls-gen2.md)
+ [Azure Synapse](connectors-azure-synapse.md)
+ [Cloudera Hive](connectors-cloudera-hive.md)
+ [Cloudera Impala](connectors-cloudera-impala.md)
+ [CloudWatch](connectors-cloudwatch.md)
+ [CloudWatch 指標](connectors-cwmetrics.md)
+ [CMDB](connectors-cmdb.md)
+ [Db2](connectors-ibm-db2.md)
+ [Db2 iSeries](connectors-ibm-db2-as400.md)
+ [DocumentDB](connectors-docdb.md)
+ [DynamoDB](connectors-dynamodb.md)
+ [Google BigQuery](connectors-bigquery.md)
+ [Google Cloud Storage](connectors-gcs.md)
+ [HBase](connectors-hbase.md)
+ [Hortonworks](connectors-hortonworks.md)
+ [Kafka](connectors-kafka.md)
+ [MSK](connectors-msk.md)
+ [MySQL](connectors-mysql.md)
+ [Neptune](connectors-neptune.md)
+ [OpenSearch](connectors-opensearch.md)
+ [Oracle](connectors-oracle.md)
+ [PostgreSQL](connectors-postgresql.md)
+ [Redis OSS](connectors-redis.md)
+ [Redshift](connectors-redshift.md)
+ [SAP HANA](connectors-sap-hana.md)
+ [Snowflake](connectors-snowflake.md)
+ [SQL Server](connectors-microsoft-sql-server.md)
+ [Teradata](connectors-teradata.md)
+ [Timestream](connectors-timestream.md)
+ [TPC-DS](connectors-tpcds.md)
+ [Vertica](connectors-vertica.md)
**注意**
[AthenaJdbcConnector](https://serverlessrepo.aws.amazon.com/applications/us-east-1/292517598671/AthenaJdbcConnector) (最新版本 2022.4.1) 已棄用。相反地，請使用資料庫特定連接器，例如適用於 [MySQL](connectors-mysql.md)、[Redshift](connectors-redshift.md) 或 [PostgreSQL](connectors-postgresql.md) 的連接器。
# Amazon Athena Azure Data Lake Storage (ADLS) Gen2 連接器
適用於 [Azure Data Lake Storage (ADLS) Gen2](https://docs.microsoft.com/en-us/azure/databricks/data/data-sources/azure/adls-gen2/) 的 Amazon Athena 連接器可讓 Amazon Athena 能夠對存放在 ADLS 上的資料執行 SQL 查詢。Athena 無法直接存取資料湖中儲存的檔案。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
+ **工作流程** – 連接器實作 JDBC 介面，該介面使用 `com.microsoft.sqlserver.jdbc.SQLServerDriver` 驅動程式。連接器會將查詢傳遞至 Azure Synapse 引擎，然後其會存取資料湖。
+ **資料處理和 S3** – 一般而言，Lambda 連接器會直接查詢資料，而無需傳輸至 Amazon S3。但是，當 Lambda 函數傳回的資料超過 Lambda 限制時，資料會寫入您指定的 Amazon S3 溢出儲存貯體，以便 Athena 可以讀取多餘的資料。
+ **AAD 身分驗證** – AAD 可用作 Azure Synapse 連接器的身分驗證方法。若要使用 AAD，連接器使用的 JDBC 連線字串必須包含 URL 參數 `authentication=ActiveDirectoryServicePrincipal`、`AADSecurePrincipalId` 和 `AADSecurePrincipalSecret`。這些參數可以直接傳遞，也可以由 Secrets Manager 傳遞。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 篩選條件中的日期和時間戳記資料類型必須轉換為適當的資料類型。
## 條款
下列術語與 Azure Data Lake Storage Gen2 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Azure Data Lake Storage Gen2 連接器。為此，請將 Azure Data Lake Storage Gen2 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type DATALAKEGEN2
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Azure Data Lake Storage Gen2 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Azure Data Lake Storage Gen2 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
datalakegentwo://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | DataLakeGen2MuxCompositeHandler |
| 中繼資料處理常式 | DataLakeGen2MuxMetadataHandler |
| 記錄處理常式 | DataLakeGen2MuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mydatalakegentwocatalog，則環境變數名稱為 mydatalakegentwocatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 DataLakeGen2 MUX Lambda 函數：`datalakegentwo1` (預設) 和 `datalakegentwo2`。
****
| 屬性 | Value |
| --- | --- |
| default | datalakegentwo://jdbc:sqlserver://adlsgentwo1.hostname:port;databaseName=database\$1name;\$1\$1secret1\$1name\$1 |
| datalakegentwo\$1catalog1\$1connection\$1string | datalakegentwo://jdbc:sqlserver://adlsgentwo1.hostname:port;databaseName=database\$1name;\$1\$1secret1\$1name\$1 |
| datalakegentwo\$1catalog2\$1connection\$1string | datalakegentwo://jdbc:sqlserver://adlsgentwo2.hostname:port;databaseName=database\$1name;\$1\$1secret2\$1name\$1 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${secret1_name}`。
```
datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=database_name;${secret1_name}
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=database_name;user=user_name;password=password
```
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Azure Data Lake Storage Gen2 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | DataLakeGen2CompositeHandler |
| 中繼資料處理常式 | DataLakeGen2MetadataHandler |
| 記錄處理常式 | DataLakeGen2RecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 Azure Data Lake Storage Gen2 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 ADLS Gen2 和 Arrow 的相應資料類型。
****
| ADLS Gen2 | Arrow |
| --- | --- |
| 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 | Date(DAY) |
| time | VARCHAR |
| datetimeoffset | Date(MILLISECOND) |
| char[n] | VARCHAR |
| varchar[n/max] | VARCHAR |
## 分割區和分隔
Azure Data Lake Storage Gen2 使用與 Hadoop 相容的 Gen2 Blob 儲存體來儲存資料檔案。從 Azure Synapse 引擎中查詢這些檔案的資料。Azure Synapse 引擎會將儲存在檔案系統中的 Gen2 資料視為外部資料表。根據資料類型實作分割區。如果已在 Gen 2 儲存系統中分割和分配資料，則連接器會以單一分割方式擷取資料。
## 效能
當一次執行多個查詢時，Azure Data Lake Storage Gen2 連接器會顯示較慢的查詢效能，且會受到限流的影響。
Athena Azure Data Lake Storage Gen2 連接器會執行述詞下推，以減少查詢掃描的資料。簡單述詞和複雜表達式會下推至連接器，以減少掃描的資料量並減少查詢執行時間。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Azure Data Lake Storage Gen2 連接器可以合併這些表達式，並將其直接推送至 Azure Data Lake Storage Gen2，以增強功能並減少掃描的資料量。
下列 Athena Azure Data Lake Storage Gen2 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## 傳遞查詢
Azure Data Lake Storage Gen2 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Azure Data Lake Storage Gen2 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Azure Data Lake Storage Gen2 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Azure Data Lake Storage Gen2 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-datalakegen2)。
# Amazon Athena Azure Synapse 連接器
適用於 [Azure Synapse 分析](https://docs.microsoft.com/en-us/azure/synapse-analytics/overview-what-is)的 Amazon Athena 連接器可讓 Amazon Athena 使用 JDBC 對 Azure Synapse 資料庫執行 SQL 查詢。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 在篩選條件中，您必須將 `Date` 和 `Timestamp` 資料類型轉換為適當的資料類型。
+ 若要搜尋類型 `Real` 和 `Float` 的負值，請使用 `<=` 或者 `>=` 運算子。
+ 不支援 `binary`、`varbinary`、`image`、和 `rowversion` 資料類型。
## 條款
下列術語與 Synapse 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Synapse 連接器。為此，請將 Synapse 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type SYNAPSE
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Synapse 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Synapse 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線 (建議)
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
synapse://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | SynapseMuxCompositeHandler |
| 中繼資料處理常式 | SynapseMuxMetadataHandler |
| 記錄處理常式 | SynapseMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mysynapsecatalog，則環境變數名稱為 mysynapsecatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Synapse MUX Lambda 函數：`synapse1` (預設) 和 `synapse2`。
****
| 屬性 | Value |
| --- | --- |
| default | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 |
| synapse\$1catalog1\$1connection\$1string | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 |
| synapse\$1catalog2\$1connection\$1string | synapse://jdbc:synapse://synapse2.hostname:port;databaseName=;\$1\$1secret2\$1name\$1 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 \$1\$1secret\$1name\$1。
```
synapse://jdbc:synapse://hostname:port;databaseName=;${secret_name}
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
synapse://jdbc:synapse://hostname:port;databaseName=;user=;password=
```
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Synapse 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | SynapseCompositeHandler |
| 中繼資料處理常式 | SynapseMetadataHandler |
| 記錄處理常式 | SynapseRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 Synapse 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | synapse://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 |
#### 設定 Active Directory 身分驗證
Amazon Athena Azure Synapse 連接器支援 Microsoft Active Directory 身分驗證。開始之前，您必須在 Microsoft Azure 入口網站中設定管理使用者，然後使用 AWS Secrets Manager 建立秘密。
**若要設定 Active Directory 管理使用者**
1. 使用具有管理權限的帳戶，登入 Microsoft Azure 入口網站 [https://portal.azure.com/](https://portal.azure.com/)。
1. 在搜尋方塊中，輸入 **Azure Synapse Analytics**，然後選擇 **Azure Synapse Analytics**。
![\[選擇 Azure Synapse Analytics。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-azure-synapse-1.png)
1. 開啟左側的選單。
![\[選擇 Azure 入口網站選單。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-azure-synapse-2.png)
1. 在導覽窗格中，依序選擇 **Azure Active Directory**。
1. 在**設定管理員**索引標籤上，將 **Active Directory 管理員**設定為新的或現有的使用者。
![\[使用設定管理員索引標籤\]](http://docs.aws.amazon.com/zh_tw/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/)。
1. 在導覽窗格中，選擇 **Secrets** (祕密)。
1. 在 **Secrets** (祕密) 頁面中，選擇祕密的連結。
1. 在祕密的詳細資訊頁面上，選擇 **Retrieve secret value** (擷取祕密值)。
![\[在 中檢視秘密 AWS Secrets Manager。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-azure-synapse-4.png)
##### 修改連線字串
若要啟用連接器的 Active Directory 身分驗證，請使用下列語法修改連線字串：
```
synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryPassword;{secret_name}
```
##### 使用 ActiveDirectoryServicePrincipal
Amazon Athena Azure Synapse 連接器也支援 `ActiveDirectoryServicePrincipal`。若要啟用此功能，請依照下列方式修改連線字串。
```
synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryServicePrincipal;{secret_name}
```
對於 `secret_name`，指定應用程式或用戶端 ID 做為密碼中服務主體識別的使用者名稱和秘密。
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 Synapse 和 Apache Arrow 的相應資料類型。
****
| Synapse | Arrow |
| --- | --- |
| 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 | Date(DAY) |
| time | VARCHAR |
| datetimeoffset | Date(MILLISECOND) |
| char[n] | VARCHAR |
| varchar[n/max] | VARCHAR |
| nchar[n] | VARCHAR |
| nvarchar[n/max] | VARCHAR |
## 分割區和分隔
分割區由 `varchar` 類型的單一分割區資料欄表示。Synapse 支援範圍分割，因此透過從 Synapse 中繼資料表中擷取分割區資料欄和分割區範圍來執行分割。這些範圍值用於建立分割。
## 效能
選取資料欄子集會大幅拖慢查詢執行時間。連接器會顯示因為並行而導致的嚴重限流。
Athena Synapse 連接器執行述詞下推，以減少查詢掃描的資料。簡單述詞和複雜表達式會下推至連接器，以減少掃描的資料量並減少查詢執行時間。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Synapse 連接器可以合併這些表達式，並將其直接推送至 Synapse，以增強功能並減少掃描的資料量。
下列 Athena Synapse 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## 傳遞查詢
Synapse 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Synapse 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Synapse 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
+ 如需說明如何使用 Quick 和 Amazon Athena 聯合查詢在存放在 Microsoft Azure Synapse 資料庫的資料上建置儀表板和視覺化效果的文章，請參閱 *AWS 大數據部落格*中的[使用 Quick、Amazon Athena 聯合查詢和 Microsoft Azure Synapse 執行多雲端分析](https://aws.amazon.com/blogs/business-intelligence/perform-multi-cloud-analytics-using-amazon-quicksight-amazon-athena-federated-query-and-microsoft-azure-synapse/)。
+ 如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Synapse 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/pom.xml) 檔案。
+ 如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-synapse)。
# Amazon Athena Cloudera Hive 連接器
適用於 Cloudera Hive 的 Amazon Athena 連接器可讓 Athena 能夠對 [Cloudera Hive](https://www.cloudera.com/products/open-source/apache-hadoop/apache-hive.html) Hadoop 分發執行 SQL 查詢。連接器可將您的 Athena SQL 查詢轉換為其同等的 HiveQL 語法。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
+ 您必須先設定 VPC 和安全群組，才能使用此連接器。如需詳細資訊，請參閱[為資料來源連接器或 AWS Glue 連線建立 VPC](athena-connectors-vpc-creation.md)。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
## 條款
下列術語與 Cloudera Hive 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 Cloudera Hive 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Cloudera Hive 連接器。為此，請將 Cloudera Hive 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type CLOUDERAHIVE
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Cloudera Hive 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Cloudera Hive 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
hive://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | HiveMuxCompositeHandler |
| 中繼資料處理常式 | HiveMuxMetadataHandler |
| 記錄處理常式 | HiveMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 myhivecatalog，則環境變數名稱為 myhivecatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Hive MUX Lambda 函數：`hive1` (預設) 和 `hive2`。
****
| 屬性 | Value |
| --- | --- |
| default | hive://jdbc:hive2://hive1:10000/default;\$1\$1Test/RDS/hive1\$1 |
| hive2\$1catalog1\$1connection\$1string | hive://jdbc:hive2://hive1:10000/default;\$1\$1Test/RDS/hive1\$1 |
| hive2\$1catalog2\$1connection\$1string | hive://jdbc:hive2://hive2:10000/default;UID=sample&PWD=sample |
##### 提供憑證
若要在 JDBC 連線字串中提供資料庫的使用者名稱和密碼，Cloudera Hive 連接器需要來自 的秘密 AWS Secrets Manager。若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
在 JDBC 連線字串 AWS Secrets Manager 中放入秘密的名稱。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${Test/RDS/hive1}`。
```
hive://jdbc:hive2://hive1:10000/default;...&${Test/RDS/hive1}&...
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
hive://jdbc:hive2://hive1:10000/default;...&UID=sample2&PWD=sample2&...
```
目前，Cloudera Hive 連接器可辨識 `UID` 和 `PWD` JDBC 屬性。
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Cloudera Hive 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | HiveCompositeHandler |
| 中繼資料處理常式 | HiveMetadataHandler |
| 記錄處理常式 | HiveRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 Cloudera Hive 執行個體。
****
| 屬性 | Value |
| --- | --- |
| 預設 | hive://jdbc:hive2://hive1:10000/default;secret=\$1\$1Test/RDS/hive1\$1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC、Cloudera Hive 和 Arrow 的相應資料類型。
****
| JDBC | Cloudera Hive | Arrow |
| --- | --- | --- |
| Boolean | Boolean | 位元 |
| Integer | TINYINT | Tiny |
| Short | SMALLINT | Smallint |
| Integer | INT | Int |
| Long | BIGINT | Bigint |
| float | float4 | Float4 |
| Double | float8 | Float8 |
| Date | date | DateDay |
| 時間戳記 | timestamp | DateMilli |
| String | VARCHAR | Varchar |
| 位元組 | 位元組 | Varbinary |
| BigDecimal | Decimal (小數) | Decimal (小數) |
| ARRAY | N/A (請參閱備註) | 清單 |
**注意**
目前，Cloudera Hive 不支援彙總類型 `ARRAY`、`MAP`、`STRUCT` 或 `UNIONTYPE`。彙總類型的資料欄在 SQL 中被視為 `VARCHAR` 資料欄。
## 分割區和分隔
分割區用於決定如何產生連接器的分割。Athena 建構了類型 `varchar` 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。
## 效能
Cloudera Hive 支援靜態分割區。Athena Cloudera Hive 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大型的資料集，強烈建議使用靜態分割。Cloudera Hive 連接器對由於並行而導致的限流保有彈性。
Athena Cloudera Hive 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Cloudera Hive 連接器可以結合這些表達式，並將它們直接推送到 Cloudera Hive，以增強功能並減少掃描的資料量。
下列 Athena Cloudera Hive 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## 傳遞查詢
Cloudera Hive 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Cloudera Hive 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Cloudera Hive 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Cloudera Hive 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudera-hive)。
# Amazon Athena Cloudera Impala 連接器
Amazon Athena Cloudera Impala 連接器可讓 Athena 能夠對 [Cloudera Impala](https://docs.cloudera.com/cdw-runtime/cloud/impala-overview/topics/impala-overview.html) 分佈執行 SQL 查詢。連接器可將您的 Athena SQL 查詢轉換為同等的 Impala 語法。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
+ 您必須先設定 VPC 和安全群組，才能使用此連接器。如需詳細資訊，請參閱[為資料來源連接器或 AWS Glue 連線建立 VPC](athena-connectors-vpc-creation.md)。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
## 條款
下列術語與 Cloudera Impala 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 Cloudera Impala 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Cloudera Impala 連接器。為此，請將 Cloudera Impala 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type CLOUDERAIMPALA
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Cloudera Impala 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Cloudera Impala 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
#### 連接字串
使用下列格式的 JDBC 連接字串來連接 Impala 叢集。
```
impala://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | ImpalaMuxCompositeHandler |
| 中繼資料處理常式 | ImpalaMuxMetadataHandler |
| 記錄處理常式 | ImpalaMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. Athena 目錄的 Impala 叢集連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 myimpalacatalog，則環境變數名稱為 myimpalacatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Impala MUX Lambda 函數：`impala1` (預設) 和 `impala2`。
****
| 屬性 | Value |
| --- | --- |
| default | impala://jdbc:impala://some.impala.host.name:21050/?\$1\$1Test/impala1\$1 |
| impala\$1catalog1\$1connection\$1string | impala://jdbc:impala://someother.impala.host.name:21050/?\$1\$1Test/impala1\$1 |
| impala\$1catalog2\$1connection\$1string | impala://jdbc:impala://another.impala.host.name:21050/?UID=sample&PWD=sample |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${Test/impala1host}`。
```
impala://jdbc:impala://Impala1host:21050/?...&${Test/impala1host}&...
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
impala://jdbc:impala://Impala1host:21050/?...&UID=sample2&PWD=sample2&...
```
目前，Cloudera Impala 可辨識 `UID` 和 `PWD` JDBC 屬性。
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Cloudera Impala 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | ImpalaCompositeHandler |
| 中繼資料處理常式 | ImpalaMetadataHandler |
| 記錄處理常式 | ImpalaRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 Cloudera Impala 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | impala://jdbc:impala://Impala1host:21050/?secret=\$1\$1Test/impala1host\$1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC、Cloudera Impala 和 Arrow 的相應資料類型。
****
| JDBC | Cloudera Impala | Arrow |
| --- | --- | --- |
| Boolean | Boolean | 位元 |
| Integer | TINYINT | Tiny |
| Short | SMALLINT | Smallint |
| Integer | INT | Int |
| Long | BIGINT | Bigint |
| float | float4 | Float4 |
| Double | float8 | Float8 |
| Date | date | DateDay |
| 時間戳記 | timestamp | DateMilli |
| String | VARCHAR | Varchar |
| 位元組 | 位元組 | Varbinary |
| BigDecimal | Decimal (小數) | Decimal (小數) |
| ARRAY | N/A (請參閱備註) | 清單 |
**注意**
目前，Cloudera Impala 不支援彙總類型 `ARRAY`、`MAP`、`STRUCT` 或 `UNIONTYPE`。彙總類型的資料欄在 SQL 中被視為 `VARCHAR` 資料欄。
## 分割區和分隔
分割區用於決定如何產生連接器的分割。Athena 建構了類型 `varchar` 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。
## 效能
Cloudera Impala 支援靜態分割區。Athena Cloudera Impala 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大型的資料集，強烈建議使用靜態分割。Cloudera Impala 連接器由於並行而對限流保有彈性。
Athena Cloudera Impala 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Cloudera Impala 連接器可以結合這些表達式，並將它們直接推送到 Cloudera Impala，以增強功能並減少掃描的資料量。
下列 Athena Cloudera Impala 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## 傳遞查詢
Cloudera Impala 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Cloudera Impala 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Cloudera Impala 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Cloudera Impala 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudera-impala)。
# Amazon Athena CloudWatch 連接器
Amazon Athena CloudWatch 連接器讓 Amazon Athena 能夠與 CloudWatch 通訊，以便使用 SQL 來查詢您的日誌資料。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
此連接器將 LogGroups 映射為結構描述，將每個 LogStream 映射為資料表。此連接器也映射特殊的 `all_log_streams` 檢視，其中包含 LogGroup 中的所有 LogStream。此檢視可讓您一次查詢 LogGroup 中的所有日誌，而不是個別搜尋每個 LogStream。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## Parameters
使用本節中的參數來設定 CloudWatch 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 CloudWatch 連接器。為此，請將 CloudWatch 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type CLOUDWATCH
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 CloudWatch 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 CloudWatch 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
連接器也支援 [AIMD 擁塞控制](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)，以透過 [Amazon Athena Query Federation 軟體開發套件](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) `ThrottlingInvoker` 構造來處理來自 CloudWatch 的限流事件。您可以透過設定下列任何選用的環境變數來調整預設限流行為：
+ **throttle\$1initial\$1delay\$1ms** - 在第一個擁塞事件之後套用的初始呼叫延遲。預設值為 10 毫秒。
+ **throttle\$1max\$1delay\$1ms** - 呼叫之間的最大延遲。您可以透過將其分成 1000 毫秒來衍生 TPS。預設值為 1000 毫秒。
+ **throttle\$1decrease\$1factor** - Athena 降低呼叫速率的係數。預設值為 0.5
+ **throttle\$1increase\$1ms**— Athena 降低呼叫延遲的速率。預設值為 10 毫秒。
## 資料庫和資料表
Athena CloudWatch 連接器將 LogGroups 映射為結構描述 (即資料庫)，將每個 LogStream 映射為資料表。此連接器也映射特殊的 `all_log_streams` 檢視，其中包含 LogGroup 中的所有 LogStream。此檢視可讓您一次查詢 LogGroup 中的所有日誌，而不是個別搜尋每個 LogStream。
Athena CloudWatch 連接器映射的每個資料表都具有下列結構描述。此結構描述符合 CloudWatch Logs 提供的欄位。
+ **log\$1stream** - 一個 `VARCHAR`，它包含資料列所在之 LogStream 的名稱。
+ **time** - 一個 `INT64`，它包含產生日誌行時的 epoch 時間。
+ **message** - 包含日誌消息的 `VARCHAR`。
**範例**
下列範例會示範如何對指定的 LogStream 執行 `SELECT` 查詢。
```
SELECT *
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."log_stream_name"
LIMIT 100
```
下列範例會示範如何使用 `all_log_streams` 檢視，在指定的 LogGroup 中對所有 LogStream 執行查詢。
```
SELECT *
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."all_log_streams"
LIMIT 100
```
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-cloudwatch.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch/athena-cloudwatch.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此權限快速失敗。
+ **CloudWatch Logs Read/Write** - 連接器會使用此權限來讀取日誌資料並寫入其診斷日誌。
## 效能
Athena CloudWatch 連接器透過並行掃描査詢所需的日誌串流，嘗試依據 CloudWatch 來最佳化查詢。對於特定時段篩選條件，會在 Lambda 函數和 CloudWatch Logs 中執行述詞下推。
為了獲得最佳效能，請僅使用小寫作為日誌群組名稱和日誌串流名稱。使用混合大小寫會導致連接器執行運算密集程度較高的不區分大小寫搜尋。
**注意**
CloudWatch 連接器不支援大寫資料庫名稱。
## 傳遞查詢
CloudWatch 連接器支援使用 [CloudWatch Logs Insights 查詢語法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)的[傳遞查詢](federated-query-passthrough.md)。如需有關 CloudWatch Logs Insights 的詳細資訊，請參閱《Amazon CloudWatch Logs 使用者指南**》中的[使用 CloudWatch Logs Insights 分析日誌資料](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html)。
若要透過 CloudWatch 建立傳遞查詢，請使用下列語法：
```
SELECT * FROM TABLE(
system.query(
STARTTIME => 'start_time',
ENDTIME => 'end_time',
QUERYSTRING => 'query_string',
LOGGROUPNAMES => 'log_group-names',
LIMIT => 'max_number_of_results'
))
```
下列範例 CloudWatch 傳遞查詢會在 `duration` 欄位不等於 1000 時進行篩選。
```
SELECT * FROM TABLE(
system.query(
STARTTIME => '1710918615308',
ENDTIME => '1710918615972',
QUERYSTRING => 'fields @duration | filter @duration != 1000',
LOGGROUPNAMES => '/aws/lambda/cloudwatch-test-1',
LIMIT => '2'
))
```
## 授權資訊
Amazon Athena CloudWatch 連接器專案是依據 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) 來授權的。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch)。
# Amazon Athena CloudWatch Metrics 連接器
Amazon Athena CloudWatch Metrics 連接器讓 Amazon Athena 能夠使用 SQL 來查詢 CloudWatch Metrics 資料。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
如需將查詢指標從 Athena 本身發佈至 CloudWatch 的相關資訊，請參閱 [使用 CloudWatch 和 EventBridge 來監控查詢和控制成本](workgroups-control-limits.md)。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## Parameters
使用本節中的參數來設定 CloudWatch Metrics 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 CloudWatch Metrics 連接器。為此，請將 CloudWatch Metrics 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type CLOUDWATCHMETRICS
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 CloudWatch Metrics 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 CloudWatch Metrics 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
連接器也支援 [AIMD 擁塞控制](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)，以透過 [Amazon Athena Query Federation 軟體開發套件](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) `ThrottlingInvoker` 構造來處理來自 CloudWatch 的限流事件。您可以透過設定下列任何選用的環境變數來調整預設限流行為：
+ **throttle\$1initial\$1delay\$1ms** - 在第一個擁塞事件之後套用的初始呼叫延遲。預設值為 10 毫秒。
+ **throttle\$1max\$1delay\$1ms** - 呼叫之間的最大延遲。您可以透過將其分成 1000 毫秒來衍生 TPS。預設值為 1000 毫秒。
+ **throttle\$1decrease\$1factor** - Athena 降低呼叫速率的係數。預設值為 0.5
+ **throttle\$1increase\$1ms**— Athena 降低呼叫延遲的速率。預設值為 10 毫秒。
## 資料庫和資料表
Athena CloudWatch Metrics 連接器會將您的命名空間、維度、指標和指標值映射到名為 `default` 的單一結構描述中的兩個資料表。
### 指標資料表
`metrics` 資料表包含由命名空間、集合和名稱組合唯一定義的可用指標。`metrics` 資料表包含以下資料欄。
+ **namespace** - 包含命名空間的 `VARCHAR`。
+ **metric\$1name** - 包含指標名稱的 `VARCHAR`。
+ **dimensions** - `STRUCT` 物件的 `LIST`，由 `dim_name (VARCHAR)` 和 `dim_value (VARCHAR)` 組成。
+ **statistic** - `VARCH` 統計資料的 `LIST` (例如，`p90`、`AVERAGE` ...)，可供指標使用。
### metric\$1samples 資料表
`metric_samples` 資料表包含 `metrics` 資料表中每個指標的可用指標範例。`metric_samples` 資料表包含以下資料欄。
+ **namespace** - 包含命名空間的 `VARCHAR`。
+ **metric\$1name** - 包含指標名稱的 `VARCHAR`。
+ **dimensions** - `STRUCT` 物件的 `LIST`，由 `dim_name (VARCHAR)` 和 `dim_value (VARCHAR)` 組成。
+ **dim\$1name**— 一個 `VARCHAR` 方便欄位，可用於輕鬆篩選單個維度名稱。
+ **dim\$1value**— 一個 `VARCHAR` 方便欄位，可用於輕鬆篩選單個維度值。
+ **period** - 一個表示指標「時段」的 `INT` 欄位 (以秒為單位) (例如，60 秒指標)。
+ **timestamp** - 表示指標範例所用 epoch 時間的 `BIGINT` 欄位 (以秒為單位)。
+ **value** - 包含範例值的 `FLOAT8` 欄位。
+ **statistic** - 包含範例統計類型的 `VARCHAR` (例如，`AVERAGE` 或者 `p90`)。
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-cloudwatch-metrics.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch-metrics/athena-cloudwatch-metrics.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
+ **CloudWatch Metrics ReadOnly** - 連接器會使用此權限來查詢您的指標資料。
+ **CloudWatch Logs Write** - 連接器使用此存取權來寫入其診斷日誌。
## 效能
Athena CloudWatch Metrics 連接器透過並行掃描査詢所需的日誌串流，嘗試依據 CloudWatch Metrics 來最佳化查詢。對於特定時段、指標、命名空間和維度篩選條件，會在 Lambda 函數和 CloudWatch Logs 中執行述詞下推。
## 授權資訊
Amazon Athena CloudWatch Metrics 連接器專案是依據 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) 來授權的。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch-metrics)。
# Amazon Athena AWS CMDB 連接器
Amazon Athena AWS CMDB 連接器可讓 Athena 與各種 AWS 服務進行通訊，讓您可以使用 SQL 進行查詢。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## Parameters
使用本節中的參數來設定 AWS CMDB 連接器。
### Glue 連線 (建議)
建議您使用 AWS Glue 連線物件來設定 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 來存放登入資料。
使用 AWS Glue 連線建立的 CMDB 連接器不支援使用多工處理常式。
使用 AWS Glue 連線建立的 CMDB 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `glue_connection` 環境屬性時，才會使用下列參數。
**Lambda 環境屬性**
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **default\$1ec2\$1image\$1owner** - (選用) 設定後，控制篩選 [Amazon Machine Image (AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) 的預設 Amazon EC2 映像擁有者。如果您未設定此值，且您針對 EC2 映像資料表的查詢不包含擁有者的篩選條件，則您的結果將包含所有公有映像。
## 資料庫和資料表
Athena AWS CMDB 連接器可讓下列資料庫和資料表可用於查詢您的 AWS 資源庫存。如需有關每個資料表中可用資料欄的詳細資訊，請使用 Athena 主控台或 API 執行 `DESCRIBE database.table` 陳述式。
+ **ec2** - 此資料庫包含與 Amazon EC2 相關的資源，包括下列資源。
+ **ebs\$1volumes** - 包含您的 Amazon EBS 磁碟區的詳細資訊。
+ **ec2\$1instances** - 包含您的 EC2 執行個體的詳細資訊。
+ **ec2\$1images** - 包含您的 EC2 執行個體映像的詳細資訊。
+ **routing\$1tables** - 包含您的 VPC 路由表的詳細資訊。
+ **security\$1groups** - 包含安全性群組的詳細資訊。
+ **subnets** - 包含 VPC 子網的詳細資訊。
+ **vpcs** - 包含 VPC 的詳細資訊。
+ **emr** - 此資料庫包含與 Amazon EMR 相關的資源，包括下列資源。
+ **emr\$1clusters** - 包含 EMR 叢集的詳細資訊。
+ **rds** - 此資料庫包含與 Amazon RDS 相關的資源，包括下列資源。
+ **rds\$1instances** - 包含您的 RDS 執行個體的詳細資訊。
+ **s3** - 此資料庫包含與 RDS 相關的資源，包括下列資源。
+ **buckets** - 包含您的 Amazon S3 儲存貯體的詳細資訊。
+ **objects** - 包含 Amazon S3 物件的詳細資訊，但不包含其內容。
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-aws-cmdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-aws-cmdb/athena-aws-cmdb.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
+ **S3 List** - 連接器使用此許可列出您的 Amazon S3 儲存貯體和物件。
+ **EC2 Describe** - 連接器使用此權限來描述資源，例如您的 Amazon EC2 執行個體、安全群組、VPC 和 Amazon EBS 磁碟區。
+ **EMR Describe / List** - 連接器使用此權限來描述您的 EMR 叢集。
+ **RDS Describe** - 連接器使用此許可來描述您的 RDS 執行個體。
## 效能
目前，Athena AWS CMDB 連接器不支援平行掃描。在 Lambda 函數內執行述詞下推。如果可能，部分述詞會被推送到正在查詢的服務。例如，查詢特定 Amazon EC2 執行個體的詳細資訊會使用特定執行個體 ID 呼叫 EC2 API，以執行目標描述操作。
## 授權資訊
Amazon Athena AWS CMDB 連接器專案是根據 [Apache-2.0 授權進行授權。](https://www.apache.org/licenses/LICENSE-2.0.html)
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-aws-cmdb)。
# Amazon Athena IBM Db2 連接器
適用於 Db2 的 Amazon Athena 連接器可讓 Amazon Athena 使用 JDBC 對 IBM Db2 資料庫執行 SQL 查詢。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
+ 您必須先設定 VPC 和安全群組，才能使用此連接器。如需詳細資訊，請參閱[為資料來源連接器或 AWS Glue 連線建立 VPC](athena-connectors-vpc-creation.md)。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 篩選條件中的日期和時間戳記資料類型必須轉換為適當的資料類型。
## 條款
下列術語與 Db2 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Db2 連接器。為此，請將 Db2 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type DB2
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Db2 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Db2 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
dbtwo://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | Db2MuxCompositeHandler |
| 中繼資料處理常式 | Db2MuxMetadataHandler |
| 記錄處理常式 | Db2MuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mydbtwocatalog，則環境變數名稱為 mydbtwocatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Db2 MUX Lambda 函數：`dbtwo1` (預設) 和 `dbtwo2`。
****
| 屬性 | Value |
| --- | --- |
| default | dbtwo://jdbc:db2://dbtwo1.hostname:port/database\$1name:\$1\$1secret1\$1name\$1 |
| dbtwo\$1catalog1\$1connection\$1string | dbtwo://jdbc:db2://dbtwo1.hostname:port/database\$1name:\$1\$1secret1\$1name\$1 |
| dbtwo\$1catalog2\$1connection\$1string | dbtwo://jdbc:db2://dbtwo2.hostname:port/database\$1name:\$1\$1secret2\$1name\$1 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${secret_name}`。
```
dbtwo://jdbc:db2://hostname:port/database_name:${secret_name}
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
dbtwo://jdbc:db2://hostname:port/database_name:user=user_name;password=password;
```
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Db2 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | Db2CompositeHandler |
| 中繼資料處理常式 | Db2MetadataHandler |
| 記錄處理常式 | Db2RecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 Db2 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | dbtwo://jdbc:db2://hostname:port/database\$1name:\$1\$1secret\$1name\$1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC 和 Arrow 的相應資料類型。
****
| Db2 | Arrow |
| --- | --- |
| CHAR | VARCHAR |
| VARCHAR | VARCHAR |
| DATE | DATEDAY |
| TIME | VARCHAR |
| TIMESTAMP | DATEMILLI |
| DATETIME | DATEMILLI |
| BOOLEAN | BOOL |
| SMALLINT | SMALLINT |
| INTEGER | INT |
| BIGINT | BIGINT |
| DECIMAL | DECIMAL |
| REAL | FLOAT8 |
| DOUBLE | FLOAT8 |
| DECFLOAT | FLOAT8 |
## 分割區和分隔
分割區由 `varchar` 類型的一或多個分割區資料欄表示。Db2 連接器使用下列組織結構描述建立分割區。
+ 依雜湊分配
+ 依範圍分割
+ 依維度組織
連接器會從一或多個 Db2 中繼資料資料表擷取分割區詳細資訊，例如分割區數目和資料欄名稱。根據識別的分割區數目建立分割。
## 效能
Athena Db2 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Db2 連接器可以合併這些表達式，並將其直接推送至 Db2，以增強功能並減少掃描的資料量。
下列 Athena Db2 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## 傳遞查詢
Db2 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Db2 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Db2 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Db2 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-db2)。
# Amazon Athena IBM Db2 AS/400 (Db2 iSeries) 連接器
適用於 Db2 AS/400 的 Amazon Athena 連接器可讓 Amazon Athena 使用 JDBC 對 IBM Db2 AS/400 (Db2 iSeries) 資料庫執行 SQL 查詢。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
+ 您必須先設定 VPC 和安全群組，才能使用此連接器。如需詳細資訊，請參閱[為資料來源連接器或 AWS Glue 連線建立 VPC](athena-connectors-vpc-creation.md)。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 篩選條件中的日期和時間戳記資料類型必須轉換為適當的資料類型。
## 條款
下列術語與 Db2 AS/400 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Db2 AS/400 連接器。為此，請將 Db2 AS/400 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type DB2AS400
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Db2 AS/400 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Db2 AS/400 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
db2as400://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | Db2MuxCompositeHandler |
| 中繼資料處理常式 | Db2MuxMetadataHandler |
| 記錄處理常式 | Db2MuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mydb2as400catalog，則環境變數名稱為 mydb2as400catalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Db2 MUX Lambda 函數：`db2as4001` (預設) 和 `db2as4002`。
****
| 屬性 | Value |
| --- | --- |
| default | db2as400://jdbc:as400://;;:\$1\$1\$1; |
| db2as400\$1catalog1\$1connection\$1string | db2as400://jdbc:as400://db2as4001.hostname/:\$1\$1secret1\$1name\$1 |
| db2as400\$1catalog2\$1connection\$1string | db2as400://jdbc:as400://db2as4002.hostname/:\$1\$1secret2\$1name\$1 |
| db2as400\$1catalog3\$1connection\$1string | db2as400://jdbc:as400://;user=;password=;; |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${secret_name}`。
```
db2as400://jdbc:as400://;;:${};
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
db2as400://jdbc:as400://;user=;password=;;
```
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Db2 AS/400 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | Db2CompositeHandler |
| 中繼資料處理常式 | Db2MetadataHandler |
| 記錄處理常式 | Db2RecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函式所支援的單一 Db2 AS/400 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | db2as400://jdbc:as400://;;:\$1\$1\$1; |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC 和 Apache Arrow 的相應資料類型。
****
| Db2 AS/400 | Arrow |
| --- | --- |
| CHAR | VARCHAR |
| VARCHAR | VARCHAR |
| DATE | DATEDAY |
| TIME | VARCHAR |
| TIMESTAMP | DATEMILLI |
| DATETIME | DATEMILLI |
| BOOLEAN | BOOL |
| SMALLINT | SMALLINT |
| INTEGER | INT |
| BIGINT | BIGINT |
| DECIMAL | DECIMAL |
| REAL | FLOAT8 |
| DOUBLE | FLOAT8 |
| DECFLOAT | FLOAT8 |
## 分割區和分隔
分割區由 `varchar` 類型的一或多個分割區資料欄表示。Db2 AS/400 連接器使用下列組織結構描述建立分割區。
+ 依雜湊分配
+ 依範圍分割
+ 依維度組織
連接器會從一或多個 Db2 AS/400 中繼資料資料表擷取分割區詳細資訊，例如分割區數目和資料欄名稱。根據識別的分割區數目建立分割。
## 效能
為了提升效能，請使用述詞下推從 Athena 查詢，如下列範例所示。
```
SELECT * FROM "lambda:"."".""
WHERE integercol = 2147483647
```
```
SELECT * FROM "lambda: "."".""
WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878'
```
## 傳遞查詢
Db2 AS/400 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Db2 AS/400 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Db2 AS/400 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動器版本資訊，請參閱 GitHub.com 上 Db2 AS/400 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-db2-as400)。
# Amazon Athena DocumentDB 連接器
Amazon Athena DocumentDB 連接器讓 Athena 能夠與您的 DocumentDB 執行個體通訊，以便使用 SQL 來查詢您的 DocumentDB 資料。此連接器也適用於 MongoDB 相容的任何端點。
與傳統的關聯式資料存放區不同，Amazon DocumentDB 集合沒有集結構描述。DocumentDB 沒有中繼資料存放區。DocumentDB 集合中的每個項目可以有不同的欄位和資料類型。
DocumentDB 連接器支援兩種產生資料表結構描述資訊的機制：基本結構描述推論和 AWS Glue Data Catalog 中繼資料。
結構描述推斷是預設值。此選項會掃描集合中的少量文件，形成所有欄位的聯集，並指定具有非重疊資料類型的欄位。此選項適用於大多數具有統一條目的集合。
對於具有更多資料類型的集合，連接器支援從 AWS Glue Data Catalog中擷取中繼資料。如果連接器看到符合您 DocumentDB AWS Glue 資料庫和集合名稱的資料庫和資料表，則會從對應的 AWS Glue 資料表取得其結構描述資訊。當您建立 AWS Glue 資料表時，建議您將其設定為您可能想要從 DocumentDB 集合存取的所有欄位的超級集合。
如果您的 帳戶中已啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 DocumentDB 連接器。為此，請將 DocumentDB 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type DOCUMENTDB
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 DocumentDB 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 DocumentDB 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **disable\$1glue** – （選用） 如果存在並設為 true，連接器不會嘗試從中擷取補充中繼資料 AWS Glue。
+ **glue\$1catalog** - (選用) 使用此選項可指定[跨帳戶 AWS Glue 目錄](data-sources-glue-cross-account.md)。根據預設，連接器會嘗試從自己的 AWS Glue 帳戶取得中繼資料。
+ **default\$1docdb** - 如果存在，請指定當不存在目錄特定環境變數時要使用的 DocumentDB 連接字串。
+ **disable\$1projection\$1and\$1casing** - (選用) 停用投影和大小寫。如果想要查詢使用區分大小寫資料欄名稱的 Amazon DocumentDB 資料表，請使用此選項。`disable_projection_and_casing` 參數使用下列值來指定大小寫和資料欄映射的行為：
+ **false** – 這是預設設定。投影已啟用，連接器預期所有資料欄名稱都為小寫字母。
+ **true** – 停用投影和大小寫。使用 `disable_projection_and_casing` 參數時，請謹記以下幾點：
+ 使用該參數可能會導致更高的頻寬用量。此外，如果您的 Lambda 函數與資料來源位於不同的 AWS 區域 ，則將因為頻寬用量增加而產生較高的標準 AWS 跨區域傳輸成本。如需跨區域傳輸成本的詳細資訊，請參閱 AWS 合作夥伴網路部落格中的[AWS 伺服器和無伺服器架構的資料傳輸費用](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)。
+ 由於傳輸的位元組數目較多，而且位元組數目越多，需要越長的還原序列化時間，因此整體延遲可能會增加。
+ **enable\$1case\$1insensitive\$1match** – (選用) 當 `true` 時，針對 Amazon DocumentDB 中的結構描述和資料表名稱執行不區分大小寫搜尋。預設值為 `false`。查詢包含大寫的結構描述或資料表名稱時使用。
#### 指定連接字串
您可以提供一個或多個屬性，以定義與連接器搭配使用的 DocumentDB 執行個體的 DocumentDB 連接詳細資訊。因此，請設定您要在 Athena 使用的目錄名稱所對應的 Lambda 環境變數。例如，假設您想要使用下列查詢來查詢來自 Athena 的兩個不同 DocumentDB 執行個體：
```
SELECT * FROM "docdb_instance_1".database.table
```
```
SELECT * FROM "docdb_instance_2".database.table
```
您必須先將兩個環境變數 `docdb_instance_1` 和 `docdb_instance_2` 新增至 Lambda 函數，才能使用這兩個 SQL 陳述式。每個陳述式的值應該為以下格式的 DocumentDB 連接字串：
```
mongodb://:@:/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0
```
##### 使用秘密
您可以選擇性地將 AWS Secrets Manager 用於連線字串詳細資訊的部分或全部值。若要搭配使用 Athena 聯合查詢功能和 Secrets Manager，連接到您的 Lambda 函數的 VPC 應該具有[網際網路存取權](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接到 Secrets Manager。
如果您使用語法 `${my_secret}` 將 Secrets Manager 秘密的名稱放入連接字串中，連接器會以 Secret Manager 中的相應純文字值來取代 `${my_secret}`。秘密應儲存為具有值 `:` 的純文字秘密。儲存為 `{username:,password:}` 的秘密將不會正確地傳遞給連接字串。
秘密也可以完整地用於整個連接字串，並且可以在秘密中定義使用者名稱和密碼。
例如，假設您將 `docdb_instance_1` 的 Lambda 環境變數設定為以下值：
```
mongodb://${docdb_instance_1_creds}@myhostname.com:123/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0
```
Athena Query Federation 軟體開發套件會自動嘗試從 Secrets Manager 中擷取名為 `docdb_instance_1_creds` 的秘密，並將該值放入 `${docdb_instance_1_creds}` 位置。由 `${ }` 字元組合括住的連接字串的任何部分會被解譯為 Secrets Manager 的秘密。如果您指定連接器在 Secrets Manager 中找不到的秘密名稱，則連接器不會取代該文字。
## 擷取補充中繼資料
若要擷取補充中繼資料，請依照以下步驟，設定 Glue 資料庫和資料表。
### 設定 Glue 資料庫
1. 建立與 DocumentDB 集合同名的 Glue 資料庫。
1. 在位置 URI 欄位中，輸入 `docdb-metadata-flag`。
### 設定 Glue 資料表
將下列參數新增至您的 Glue 資料表：
+ `docdb-metadata-flag = true`
+ `columnMapping = apple=APPLE`
在此範例中，`apple` 表示 Glue 中的小寫資料欄名稱，而 `APPLE` 表示 DocumentDB 集合中實際的區分大小寫的資料欄名稱。
### 驗證中繼資料擷取
1. 執行查詢。
1. 檢查 Lambda 函式的 CloudWatch 日誌，以確認中繼資料擷取是否成功。成功擷取將顯示下列日誌項目：
```
doGetTable: Retrieved schema for table[TableName{schemaName=test, tableName=profiles}] from AWS Glue.
```
**注意**
如果您的資料表已設定 `columnMapping` 欄位，則您只需要將 `docdb-metadata-flag = true` 參數新增至資料表屬性。
## 在 中設定資料庫和資料表 AWS Glue
由於連接器的內建結構描述推論功能會掃描有限數量的文件，並僅支援一部分資料類型，因此您可能想要將 AWS Glue 用於中繼資料。
若要啟用 AWS Glue 資料表以搭配 Amazon DocumentDB 使用，您必須擁有要為其提供補充中繼資料的 DocumentDB 資料庫和集合的資料庫和 AWS Glue 資料表。
**使用 AWS Glue 資料表補充中繼資料**
1. 使用 AWS Glue 主控台建立與 Amazon DocumentDB AWS Glue 資料庫名稱同名的資料庫。
1. 將資料庫的 URI 屬性設定為包含 **docdb-metadata-flag**。
1. (選用) 新增 **sourceTable** 資料表屬性。此屬性定義 Amazon DocumentDB 中的來源資料表名稱。如果您的 AWS Glue 資料表名稱與 Amazon DocumentDB 中的資料表名稱不同，請使用此屬性。 AWS Glue 與 Amazon DocumentDB 之間命名規則的差異可能會使此成為必要。例如， AWS Glue 資料表名稱中不允許大寫字母，但 Amazon DocumentDB 資料表名稱中允許大寫字母。
1. (選用) 新增 **columnMapping** 資料表屬性。此屬性可定義資料欄名稱映射。如果 AWS Glue 資料欄命名規則阻止您建立的資料欄名稱與 Amazon DocumentDB AWS Glue 資料表中的資料欄名稱相同，請使用此屬性。這非常有用，因為 Amazon DocumentDB 資料欄名稱中允許大寫字母，但 AWS Glue 資料欄名稱中不允許。
`columnMapping` 屬性值應該是格式 `col1=Col1,col2=Col2` 中的一組映射。
**注意**
資料欄映射僅適用於頂層資料欄名稱，而不適用於巢狀欄位。
新增 AWS Glue `columnMapping`資料表屬性後，您可以移除 `disable_projection_and_casing` Lambda 環境變數。
1. 請確定您使用適用於本文件 AWS Glue 所列 的資料類型。
## 支援的資料類型
本節列出 DocumentDB 連接器用於結構描述推論的資料類型，以及使用 AWS Glue 中繼資料時的資料類型。
### 結構描述推斷資料類型
DocumentDB 連接器的結構描述推斷功能會嘗試將值推斷為以下資料類型之一。該資料表顯示 Amazon DocumentDB、Java 和 Apache Arrow 的相應資料類型。
****
| Apache Arrow | Java 或 DocDB |
| --- | --- |
| VARCHAR | String |
| INT | Integer |
| BIGINT | Long |
| BIT | Boolean |
| FLOAT4 | Float |
| FLOAT8 | Double |
| TIMESTAMPSEC | Date |
| VARCHAR | ObjectId |
| LIST | 清單 |
| STRUCT | 文件 |
### AWS Glue 資料類型
如果您使用 AWS Glue 補充中繼資料，則可以設定下列資料類型。資料表顯示 AWS Glue 和 Apache Arrow 的對應資料類型。
****
| AWS Glue | Apache Arrow |
| --- | --- |
| int | INT |
| bigint | BIGINT |
| double | FLOAT8 |
| float | FLOAT4 |
| boolean | BIT |
| binary | VARBINARY |
| string | VARCHAR |
| 清單 | LIST |
| Struct | STRUCT |
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-docdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-docdb/athena-docdb.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
+ **AWS Glue Data Catalog** – DocumentDB 連接器需要對 的唯讀存取權 AWS Glue Data Catalog ，才能取得結構描述資訊。
+ **CloudWatch Logs** - 連接器需要存取 CloudWatch Logs 以儲存日誌。
+ **AWS Secrets Manager 讀取存取** – 如果您選擇將 DocumentDB 端點詳細資訊儲存在 Secrets Manager 中，則必須授予連接器存取這些秘密的權限。
+ **VPC 存取** - 連接器需要能夠將介面連接到 VPC 並能進行分離，以便可進行連接並與 DocumentDB 執行個體通訊。
## 效能
Athena Amazon DocumentDB 連接器目前不支援平行掃描，但會嘗試下推述詞作為其 DocumentDB 查詢的一部分，而針對 DocumentDB 集合上之索引的述詞會導致掃描的資料大幅減少。
Lambda 函數執行投影下推，以減少查詢掃描的資料。不過，選取資料欄子集有時會導致較長的查詢執行時期。`LIMIT` 子句可減少掃描的資料量，但是如果您未提供述詞，則應期望具有 `LIMIT` 子句的 `SELECT` 查詢掃描至少 16 MB 的資料。
## 傳遞查詢
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` 資料庫，進而篩選出所有標題為*權利法案*的書籍。
```
SELECT * FROM TABLE(
system.query(
database => 'example',
collection => 'tpcds',
filter => '{title: "Bill of Rights"}'
))
```
## 其他資源
+ 如需使用 [Amazon Athena 聯合查詢](federated-queries.md)將 MongoDB 資料庫連線至 [Quick](https://aws.amazon.com/quicksight/) 以建置儀表板和視覺化效果的文章，請參閱 大數據部落格中的[使用 Amazon Athena 聯合查詢視覺化來自 Quick 的 MongoDB ](https://aws.amazon.com/blogs/big-data/visualize-mongodb-data-from-amazon-quicksight-using-amazon-athena-federated-query/) 資料。 *AWS *
+ 如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-docdb)。
# Amazon Athena DynamoDB 連接器
Amazon Athena DynamoDB 連接器讓 Amazon Athena 能夠與 DynamoDB 通訊，以便使用 SQL 來查詢您的資料表。不支援 [INSERT INTO](insert-into.md) 等寫入操作。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
如果您的 帳戶中已啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
如果將 DynamoDB 連線移轉至 Glue Catalog 和 Lake Formation，則僅會辨識小寫的資料表和資料欄名稱。
## Parameters
使用本節中的參數來設定 DynamoDB 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 DynamoDB 連接器。為此，請將 DynamoDB 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type DYNAMODB
```
**Lambda 環境屬性**
**glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 DynamoDB 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 DynamoDB 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `glue_connection` 環境屬性時，才會使用下列參數。
**Lambda 環境屬性**
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **disable\$1glue** – （選用） 如果存在並設為 true，連接器不會嘗試從中擷取補充中繼資料 AWS Glue。
+ **glue\$1catalog** - (選用) 使用此選項可指定[跨帳戶 AWS Glue 目錄](data-sources-glue-cross-account.md)。根據預設，連接器會嘗試從自己的 AWS Glue 帳戶取得中繼資料。
+ **disable\$1projection\$1and\$1casing** - (選用) 停用投影和大小寫。如果您想要查詢其資料欄名稱中有大小寫的 DynamoDB 資料表並且不想在 AWS Glue 中指定 `columnMapping` 屬性，請使用它。
`disable_projection_and_casing` 參數使用下列值來指定大小寫和資料欄映射的行為：
+ **auto** (自動) - 當偵測到先前不支援的類型且未在資料表中設定資料欄名稱映射時，停用投影和大小寫。這是預設設定。
+ **always** (永遠) - 無條件停用投影和大小寫。當 DynamoDB 資料欄名稱中有大小寫，但您不想指定任何資料欄名稱映射時，此功能非常有用。
使用 `disable_projection_and_casing` 參數時，請謹記以下幾點：
+ 使用該參數可能會導致更高的頻寬用量。此外，如果您的 Lambda 函數與資料來源位於不同的 AWS 區域 ，則將因為頻寬用量增加而產生較高的標準 AWS 跨區域傳輸成本。如需跨區域傳輸成本的詳細資訊，請參閱 AWS 合作夥伴網路部落格中的[AWS 伺服器和無伺服器架構的資料傳輸費用](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)。
+ 由於傳輸的位元組數目較多，而且位元組數目越多，需要越長的還原序列化時間，因此整體延遲可能會增加。
## 在 中設定資料庫和資料表 AWS Glue
由於連接器的內建結構描述推論功能有限，您可能想要將 AWS Glue 用於中繼資料。若要這樣做，您必須在其中擁有資料庫和資料表 AWS Glue。若要啟用資料庫和資料表以與 DynamoDB 搭配使用，您必須編輯其屬性。
**在 AWS Glue 主控台中編輯資料庫屬性**
1. 登入 AWS 管理主控台 ，並在 https：//[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 連接器用於補充中繼資料的資料表，而 以外的 AWS Glue 資料庫則需要此資料表`default`。`dynamo-db-flag` 屬性有助於在具有許多資料庫的帳戶中篩選資料庫。
1. 選擇 **Update Database** (更新資料庫)。
**在 AWS Glue 主控台中編輯資料表屬性**
1. 登入 AWS 管理主控台 ，並在 https：//[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** – 選用資料表屬性，指定從 `date`或 `timestamp`資料類型的資料欄剖析資料時要使用的 AWS Glue `date`或 `datetime` 格式。如果未指定此屬性，連接器會嘗試[推斷](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/time/DateFormatUtils.html) ISO-8601 格式。如果連接器無法推斷 `date` 或者 `datetime` 的格式，或無法剖析原始字串，則會從結果中省略該值。
`datetimeFormatMapping` 值的格式應為 `col1=someformat1,col2=someformat2`。以下是一些範例格式：
```
yyyyMMdd'T'HHmmss
ddMMyyyy'T'HH:mm:ss
```
如果您的資料欄具有沒有時區的 `date` 或 `datetime` 值，並且您想要在 `WHERE` 子句中使用該資料欄，請設定該資料欄的 `datetimeFormatMapping` 屬性。
1. 如果您手動定義資料欄，請務必使用適當的資料類型。如果您使用爬蟲程式，請驗證爬蟲程式發現的資料欄和類型。
1. 選擇**儲存**。
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-dynamodb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-dynamodb/athena-dynamodb.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
+ **AWS Glue Data Catalog** – DynamoDB 連接器需要對 的唯讀存取權 AWS Glue Data Catalog ，才能取得結構描述資訊。
+ **CloudWatch Logs** - 連接器需要存取 CloudWatch Logs 以儲存日誌。
+ **DynamoDB 讀取權限** - 連接器使用 `DescribeTable`、`ListSchemas`、`ListTables`、`Query` 以及 `Scan` API 操作。
## 效能
Athena DynamoDB 連接器支援平行掃描，並嘗試下推述詞作為 DynamoDB 查詢的一部分。具有 `X` 個不同值的雜湊索引鍵述詞會導致對 DynamoDB 發出 `X` 個查詢呼叫。所有其他述詞案例都會導致 `Y` 個掃描呼叫，其中 `Y` 是根據資料表大小及其佈建的輸送量啟發式決定的。不過，選取資料欄子集有時會導致查詢執行期更長。
`LIMIT` 子句和簡單述詞會下推，可以減少掃描的資料量，並會導致查詢執行時間縮短。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。為了增強功能及減少掃描的資料量，Athena DynamoDB 連接器可以合併這些表達式並將其直接推送至 DynamoDB。
下列 Athena DynamoDB 連接器運算子支援述詞下推：
+ **布林值：**AND
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10 and col_b < 10
LIMIT 10
```
如需有關使用述詞下推以改善聯合查詢中的效能 (包括 DynamoDB) 的文章，請參閱 *AWS 大數據部落格*中的[使用 Amazon Athena 中的述詞下推改善聯合查詢](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)。
## 傳遞查詢
DynamoDB 連接器支援[傳遞查詢](federated-query-passthrough.md)，並且使用 PartiQL 語法。不支援 DynamoDB [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) API 操作。如需有關使用 PartiQL 查詢 DynamoDB 的資訊，請參閱《Amazon DynamoDB 開發人員指南**》中的[適用於 DynamoDB 的 PartiQL Select 陳述式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html)。
若要透過 DynamoDB 使用傳遞查詢，請使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query_string'
))
```
下列 DynamoDB 傳遞查詢範例使用 PartiQL 傳回 `DateWatched` 屬性晚於 12/24/22 的 Fire TV Stick 裝置清單。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT Devices
FROM WatchList
WHERE Devices.FireStick.DateWatched[0] > '12/24/22''
))
```
## 疑難排解
### 排序索引鍵資料欄上的多個篩選條件
**錯誤訊息**：KeyConditionExpressions 每個索引鍵只能包含一個條件
**原因**：在 DynamoDB 排序索引鍵資料欄上同時具有下限篩選條件和上限篩選條件的查詢中，Athena 引擎第 3 版可能會發生此問題。由於 DynamoDB 不支援排序索引鍵上的多個篩選條件，因此當連接器嘗試下推套用這兩個條件的查詢時，即會擲回錯誤。
**解決方案**：將連接器更新到 2023.11.1 版本或更新版本。如需有關更新連接器的說明，請參閱 [更新資料來源連接器](connectors-updating.md)。
## 成本
連接器的使用成本取決於所使用的基礎 AWS 資源。因為使用掃描的查詢可能會消耗大量的[讀取容量單位 (RCU)](https://aws.amazon.com/dynamodb/pricing/provisioned/)，所以請仔細考慮 [Amazon DynamoDB 定價](https://aws.amazon.com/dynamodb/pricing/)資訊。
## 其他資源
+ 如需有關使用 Amazon Athena DynamoDB 連接器的說明，請參閱《*AWS 規範性指引模式*》指南中的[使用 Athena 存取、查詢和聯結 Amazon DynamoDB 資料表](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 大數據部落格*文章[使用 Amazon Athena DynamoDB 連接器在 Quick 中視覺化 Amazon DynamoDB 洞見和 Amazon Athena 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 連接器來建立簡單控管儀表板的文章，請參閱[使用 Amazon Athena 聯合查詢查詢查詢跨帳戶 Amazon DynamoDB 資料表](https://aws.amazon.com/blogs/big-data/query-cross-account-amazon-dynamodb-tables-using-amazon-athena-federated-query/)之後*AWS 的大數據部落格*。 DynamoDB
+ 如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-dynamodb)。
# Amazon Athena Google BigQuery 連接器
適用於 Google [BigQuery](https://cloud.google.com/bigquery/) 的 Amazon Athena 連接器可讓 Amazon Athena 能夠對 Google BigQuery 資料執行 SQL 查詢。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ Lambda 函數的逾時值上限為 15 分鐘。每次分割都會對 BigQuery 執行查詢，並且必須有足夠的時間來儲存結果，以便 Athena 讀取。如果 Lambda 函數逾時，查詢就會失敗。
+ Google BigQuery 區分大小寫。連接器會嘗試更正資料集名稱、資料表名稱和專案 ID 的大小寫。這是必要的，因為 Athena 會使所有中繼資料變為小寫。這些更正會對 Google BigQuery 產生許多額外呼叫。
+ 不支援二進位資料類型。
+ 由於 Google BigQuery 的並行處理和配額限制，連接器可能會遇到 Google 配額限制問題。為了避免這些問題，請盡可能多地向 Google BigQuery 推送限制條件。如需有關 BigQuery 配額的資訊，請參閱 Google BigQuery 文件中的[配額和限制](https://cloud.google.com/bigquery/quotas)。
## Parameters
使用本節中的參數來設定 Google BigQuery 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Google BigQuery 連接器。為此，請將 Google BigQuery 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type BIGQUERY
```
**Lambda 環境屬性**
**glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Google BigQuery 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Google BigQuery 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `glue_connection` 環境屬性時，才會使用下列參數。
**Lambda 環境屬性**
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 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** – 內秘密的名稱 AWS Secrets Manager ，其中包含 JSON 格式的 BigQuery 登入資料 （例如 `GoogleCloudPlatformCredentials`)。
+ **big\$1query\$1endpoint** – (選用) BigQuery 私有端點的 URL。如果想要透過私有端點存取 BigQuery，請使用此參數。
## 分割與檢視
由於 BigQuery 連接器使用 BigQuery Storage Read API 查詢資料表，並且 BigQuery Storage API 不支援檢視，因此連接器會使用具有單一分割的 BigQuery 用戶端以進行檢視。
## 效能
若要查詢資料表，BigQuery 連接器會使用 BigQuery Storage Read API，而該 API 使用了 RPC 型通訊協定，可快速存取 BigQuery 受管儲存。如需有關 BigQuery Storage Read API 的詳細資訊，請參閱 Google Cloud 文件中的[使用 BigQuery Storage Read API 讀取資料表資料](https://cloud.google.com/bigquery/docs/reference/storage)。
選取資料欄子集可大幅加速查詢執行期，並減少掃描的資料。隨著並行數目增加，連接器容易出現查詢失敗，且連接器速度通常較慢。
Athena Google BigQuery 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、`ORDER BY` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 前 N 個查詢
前 `N` 個查詢會指定結果集的順序，以及傳回的資料列數目的限制。您可以使用這種查詢類型，判斷資料集的前 `N` 個最大值或前 `N` 個最小值。透過前 `N` 個下推，連接器只會向 Athena 傳回 `N` 個排序的資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Google BigQuery 連接器可以結合這些表達式，並將它們直接推送到 Google BigQuery，以增強功能並減少掃描的資料量。
下列 Athena Google BigQuery 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
ORDER BY col_a DESC
LIMIT 10;
```
## 傳遞查詢
Google BigQuery 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Google BigQuery 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Google BigQuery 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
Amazon Athena Google BigQuery 連接器專案是依據 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) 來授權的。
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-google-bigquery)。
# Amazon Athena Google Cloud Storage 連接器
Amazon Athena Google Cloud Storage 連接器讓 Amazon Athena 能夠對存放在 Google Cloud Storage (GCS) 儲存貯體中的 Parquet 檔案和 CSV 檔案執行查詢。將一個或多個 Parquet 或 CSV 檔案分組到 GCS 儲存貯體中的未分割或分割資料夾之後，您可以在 [AWS Glue](https://aws.amazon.com/glue/) 資料庫資料表中對其進行整理。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
如果您的 帳戶中已啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。
如需示範如何使用 Athena 對 GCS 儲存貯體中的 Parquet 或 CSV 檔案執行查詢的文章，請參閱 AWS 大數據部落格文章[使用 Amazon Athena 查詢存放在 Google Cloud Platform 中的資料](https://aws.amazon.com/blogs/big-data/use-amazon-athena-to-query-data-stored-in-google-cloud-platform/)。
## 先決條件
+ 設定與 Google Cloud Storage 中的儲存貯體和資料夾對應的 AWS Glue 資料庫和資料表。如需這些步驟，請參閱本文件後面的 [在 中設定資料庫和資料表 AWS Glue](#connectors-gcs-setting-up-databases-and-tables-in-glue)。
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 目前，連接器僅支援分割區資料欄的`VARCHAR`類型 (`string` 或 AWS Glue 資料表結構描述`varchar`中的 )。當您在 Athena 中查詢其他分割區欄位類型時，會引發錯誤。
## 條款
下列術語與 GCS 連接器相關。
+ **處理常式** - 存取 GCS 儲存貯體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從 GCS 儲存貯體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從 GCS 儲存貯體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從 GCS 儲存貯體中擷取中繼資料和資料記錄的 Lambda 處理常式。
## 支援的檔案類型
GCS 連接器支援 Parquet 和 CSV 檔案類型。
**注意**
請確定不要將 CSV 和 Parquet 檔案同時放在相同的 GCS 儲存貯體或路徑中。如果嘗試將 Parquet 檔案讀取為 CSV，可能會導致執行階段錯誤，反之亦然。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 GCS 連接器。為此，請將 GCS 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type GOOGLECLOUDSTORAGE
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 GCS 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 GCS 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **secret\$1manager\$1gcp\$1creds\$1name** – 中的秘密名稱 AWS Secrets Manager ，其中包含 JSON 格式的 GCS 登入資料 （例如 `GoogleCloudPlatformCredentials`)。
## 在 中設定資料庫和資料表 AWS Glue
由於 GCS 連接器的內建結構描述推論功能有限，我們建議您將 AWS Glue 用於中繼資料。下列程序說明如何在 中建立資料庫和資料表 AWS Glue ，以便從 Athena 存取。
### 在 中建立資料庫 AWS Glue
您可以使用 AWS Glue 主控台來建立資料庫，以搭配 GCS 連接器使用。
**在 中建立資料庫 AWS Glue**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) 開啟 AWS Glue 主控台。
1. 在導覽窗格中，選擇 **Databases** (資料庫)。
1. 選擇**新增資料庫**。
1. 對於 **Name** (名稱)，輸入您要搭配 GCS 連接器使用的資料庫名稱。
1. 對於**位置**，請指定 `google-cloud-storage-flag`。此位置會告知 GCS 連接器， AWS Glue 資料庫包含要在 Athena 中查詢 GCS 資料的資料表。連接器可辨識 Athena 中具有此標記的資料庫，並忽略沒有此標記的資料庫。
1. 選擇**建立資料庫**。
### 在 中建立資料表 AWS Glue
現在，您可以為資料庫建立資料表。當您建立要與 GCS 連接器搭配使用的 AWS Glue 資料表時，您必須指定其他中繼資料。
**在 AWS Glue 主控台中建立資料表**
1. 在 AWS Glue 主控台的導覽窗格中，選擇**資料表**。
1. 在 **Tables** (資料表) 頁面中，選擇 **Add table** (新增資料表)。
1. 在 **Set table properties** (設定資料表屬性) 頁面中，輸入以下資訊。
+ **名稱** – 資料表的唯一名稱。
+ **資料庫** - 選擇您為 GCS 連接器建立的 AWS Glue 資料庫。
+ **包含路徑** – 在 **Data store** (資料存放區) 區段中，對於 **Include path** (包含路徑)，輸入字首為 `gs://` 的 GCS URI 位置 (例如，`gs://gcs_table/data/`)。如果您有一個或多個分割區資料夾，則請不要將其包含在路徑中。
**注意**
當您輸入非 `s3://` 資料表路徑時， AWS Glue 主控台會顯示錯誤。您可以忽略此錯誤。將成功建立資料表。
+ **資料格式** - 對於 **Classification** (分類)，請選取 **CSV** 或 **Parquet**。
1. 選擇**下一步**。
1. 強烈建議您在 **Choose or define schema** (選擇或定義結構描述) 頁面中定義資料表結構描述，但不是必要的。如果您未定義結構描述，則 GCS 連接器會嘗試為您推斷結構描述。
執行以下任意一項：
+ 如果要讓 GCS 連接器嘗試為您推斷結構描述，則請選擇 **Next** (下一步)，然後選擇 **Create** (建立)。
+ 若要自行定義結構描述，請遵循下一節中的步驟。
### 在 中定義資料表結構描述 AWS Glue
在 中定義資料表結構描述 AWS Glue 需要更多步驟，但可讓您更好地控制資料表建立程序。
**在 中定義資料表的結構描述 AWS Glue**
1. 在 **Choose or define schema** (選擇或定義結構描述) 頁面中，選擇 **Add** (新增)。
1. 使用 **Add schema entry** (新增結構描述項目) 對話方塊提供資料欄名稱和資料類型。
1. 若要將資料欄指定為分割區資料欄，請選取 **Set as partition key** (設定為分割區索引鍵) 選項。
1. 選擇 **Save** (儲存) 可儲存資料欄。
1. 選擇 **Add** (新增) 可新增另一個資料欄。
1. 當您完成新增資料欄時，選擇 **Next** (下一步)。
1. 在 **Review and create** (檢閱和建立) 頁面中，檢閱資料表，然後選擇 **Create** (建立)。
1. 如果您的結構描述包含分割區資訊，則請遵循下一節中的步驟，將分割區模式新增至 AWS Glue中的資料表屬性。
### 將分割區模式新增至 中的資料表屬性 AWS Glue
如果您的 GCS 儲存貯體具有分割區，則必須將分割區模式新增至 AWS Glue中的資料表屬性。
**將分割區資訊新增至資料表屬性 AWS Glue**
1. 在您建立之資料表的詳細資訊頁面上 AWS Glue，選擇**動作**、**編輯資料表**。
1. 在 **Edit table** (編輯資料表) 頁面中，向下捲動至 **Table properties** (資料表屬性) 區段。
1. 選擇 **Add** (新增) 以新增分割區索引鍵。
1. 在 **Key** (索引鍵) 欄位，輸入 **partition.pattern**。此索引鍵定義資料夾路徑模式。
1. 在 **Value** (值) 中，輸入資料夾路徑樣式，例如 **StateName=\$1\$1statename\$1/ZipCode=\$1\$1zipcode\$1/**，其中由 **\$1\$1\$1** 括起來的 **statename** 和 **zipcode** 是分割區資料欄名稱。GCS 連接器支援 Hive 和非 Hive 分割區結構描述。
1. 完成時，請選擇 **Save (儲存)**。
1. 若要檢視您剛剛建立的資料表屬性，請選擇 **Advanced properties** (進階屬性) 索引標籤。
此時，您可以導覽至 Athena 主控台。您在 中建立的資料庫和資料表 AWS Glue 可在 Athena 中查詢。
## 支援的資料類型
下表顯示 CSV 和 Parquet 支援的資料類型。
### CSV
****
| **Nature of data** (資料性質) | **Inferred Data Type** (推斷的資料類型) |
| --- | --- |
| 資料看起來像數字 | BIGINT |
| 資料看起來像字串 | VARCHAR |
| 資料看起來像浮點值 (浮點數、雙精度或十進制) | DOUBLE |
| 資料看起來像日期 | 時間戳記 |
| 包含真/假值的資料 | BOOL |
### Parquet
****
| **PARQUET** | **Athena (Arrow)** (Athena (箭頭)) |
| --- | --- |
| 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/zh_tw/athena/latest/ug/connectors-gcs.html) |
| INT64 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/connectors-gcs.html) |
| INT96 | 時間戳記 |
| MAP | MAP |
| STRUCT | STRUCT |
| LIST | LIST |
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-gcs.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/athena-gcs.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
+ **AWS Glue Data Catalog** – GCS 連接器需要對 的唯讀存取權 AWS Glue Data Catalog ，才能取得結構描述資訊。
+ **CloudWatch Logs** - 連接器需要存取 CloudWatch Logs 以儲存日誌。
## 效能
當資料表結構描述包含分割區欄位且 `partition.pattern` 資料表屬性設定正確時，您可以在查詢的 `WHERE` 子句中包含分割區欄位。對於此類查詢，GCS 連接器會使用分割區資料欄來精簡 GCS 資料夾路徑，並避免掃描 GCS 資料夾中不需要的檔案。
對於 Parquet 資料集，選取資料欄子集會導致掃描的資料較少。當套用資料欄投影時，這通常會導致較短的查詢執行階段。
對於 CSV 資料集，不支援資料欄投影，並且不會減少掃描的資料量。
`LIMIT` 子句可減少掃描的資料量，但是如果您未提供述詞，則應期望具有 `LIMIT` 子句的 `SELECT` 查詢掃描至少 16 MB 的資料。與較小資料集相比，GCS 連接器可為較大資料集掃描更多資料，無論是否套用 `LIMIT` 子句。例如，與較小的基礎資料集相比，`SELECT * LIMIT 10000` 查詢可為較大的基礎資料集掃描更多資料。
### 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
### 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-gcs)。
# Amazon Athena HBase 連接器
Amazon Athena HBase 連接器讓 Amazon Athena 能夠與您的 Apache HBase 執行個體通訊，以便使用 SQL 來查詢您的 HBase 資料。
與傳統的關聯式資料存放區不同，HBase 集合沒有集結構描述。HBase 沒有中繼資料存放區。HBase 集合中的每個條目可以有不同的欄位和資料類型。
HBase 連接器支援兩種產生資料表結構描述資訊的機制：基本結構描述推論和 AWS Glue Data Catalog 中繼資料。
結構描述推斷是預設值。此選項會掃描集合中的少量文件，形成所有欄位的聯集，以及強制具有非重疊資料類型的欄位。此選項適用於大多數具有統一條目的集合。
對於具有更多資料類型的集合，連接器支援從 AWS Glue Data Catalog中擷取中繼資料。如果連接器看到符合您 HBase 命名空間和集合名稱的 AWS Glue 資料庫和資料表，則會從對應的 AWS Glue 資料表取得其結構描述資訊。當您建立 AWS Glue 資料表時，建議您將其設定為您可能想要從 HBase 集合存取的所有欄位的超級集合。
如果您的 帳戶中已啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 HBase 連接器。為此，請將 HBase 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type HBASE
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 HBase 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 HBase 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **disable\$1glue** – （選用） 如果存在並設為 true，連接器不會嘗試從中擷取補充中繼資料 AWS Glue。
+ **glue\$1catalog** - (選用) 使用此選項可指定[跨帳戶 AWS Glue 目錄](data-sources-glue-cross-account.md)。根據預設，連接器會嘗試從自己的 AWS Glue 帳戶取得中繼資料。
+ **default\$1hbase** - 如果存在，則指定當不存在目錄特定環境變數時要使用的 HBase 連接字串。
+ **enable\$1case\$1insensitive\$1match** – (選用) 當 `true` 時，針對 HBase 中的資料表名稱執行不區分大小寫搜尋。預設值為 `false`。查詢包含大寫的資料表名稱時使用。
#### 指定連接字串
您可以提供一個或多個屬性，以定義與連接器搭配使用的 HBase 執行個體的 HBase 連接詳細資訊。因此，請設定您要在 Athena 使用的目錄名稱所對應的 Lambda 環境變數。例如，假設您想要使用下列查詢來查詢來自 Athena 的兩個不同 HBase 執行個體：
```
SELECT * FROM "hbase_instance_1".database.table
```
```
SELECT * FROM "hbase_instance_2".database.table
```
您必須先將兩個環境變數 `hbase_instance_1` 和 `hbase_instance_2` 新增至 Lambda 函數，才能使用這兩個 SQL 陳述式。每個的值應該為以下格式的 HBase 連接字串：
```
master_hostname:hbase_port:zookeeper_port
```
##### 使用秘密
您可以選擇性地將 AWS Secrets Manager 用於連線字串詳細資訊的部分或全部值。若要搭配使用 Athena 聯合查詢功能和 Secrets Manager，連接到您的 Lambda 函數的 VPC 應該具有[網際網路存取權](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接到 Secrets Manager。
如果您使用語法 `${my_secret}` 將 Secret Manager 秘密的名稱放入連接字串中，連接器會使用您在 Secret Manager 中的使用者名稱和密碼值來取代秘密名稱。
例如，假設您將 `hbase_instance_1` 的 Lambda 環境變數設定為以下值：
```
${hbase_host_1}:${hbase_master_port_1}:${hbase_zookeeper_port_1}
```
Athena Query Federation 軟體開發套件會自動嘗試從 Secrets Manager 中擷取名為 `hbase_instance_1_creds` 的秘密，並將該值放入 `${hbase_instance_1_creds}` 位置。由 `${ }` 字元組合括住的連接字串的任何部分會被解譯為 Secrets Manager 的秘密。如果您指定連接器在 Secrets Manager 中找不到的秘密名稱，則連接器不會取代該文字。
## 在 中設定資料庫和資料表 AWS Glue
連接器的內建結構描述推斷僅支援在 HBase 中序列化為字串的值 (例如，`String.valueOf(int)`)。由於連接器的內建結構描述推斷功能受到限制，因此您可能需要對中繼資料使用 AWS Glue 。若要啟用 AWS Glue 資料表以搭配 HBase 使用，您必須擁有 AWS Glue 資料庫和資料表，其名稱符合您要為其提供補充中繼資料的 HBase 命名空間和資料表。使用 HBase 資料欄系列命名慣例是可選的，但不是必需的。
**使用 AWS Glue 資料表補充中繼資料**
1. 在 AWS Glue 主控台中編輯資料表和資料庫時，請新增下列資料表屬性：
+ **hbase-metadata-flag** - 此屬性向 HBase 連接器發出指示，連接器可使用資料表作為補充中繼資料。您可以為 `hbase-metadata-flag` 提供任何值，只要 `hbase-metadata-flag` 屬性存在於資料表屬性清單中。
+ **hbase-native-storage-flag** - 使用此標記可切換連接器支援的兩個值序列化模式。根據預設，當此欄位不存在時，連接器假定所有值都作為字串儲存在 HBase 中。因此，它會嘗試將 HBase 中的 `INT`、`BIGINT` 和 `DOUBLE` 等資料類型作為字串進行剖析。如果此欄位在 中的資料表上以任何值設定 AWS Glue，連接器會切換到「原生」儲存模式，並使用下列函數嘗試將 `INT`、`BIT`、 `BIGINT`和 讀取`DOUBLE`為位元組：
```
ByteBuffer.wrap(value).getInt()
ByteBuffer.wrap(value).getLong()
ByteBuffer.wrap(value).get()
ByteBuffer.wrap(value).getDouble()
```
1. 請確定您使用適用於本文件 AWS Glue 所列 的資料類型。
### 建立資料欄系列模型
Athena HBase 連接器支援兩種方式來建立 HBase 資料欄系列模型：完全限定 (扁平化) 命名 (例如 `family:column`)，或使用 `STRUCT` 物件。
在 `STRUCT` 模型中，`STRUCT` 欄位的名稱應與資料欄系列相符，而 `STRUCT` 的子項應該與該系列的資料欄名稱相符。但是，由於諸如 `STRUCT` 等複雜類型尚不完全支援述詞下推和資料欄讀取，因此目前不建議使用 `STRUCT`。
下圖顯示在 中設定的資料表 AWS Glue ，該資料表使用兩種方法的組合。
![\[在 AWS Glue for Apache Hbase 中建立資料欄系列的模型。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-hbase-1.png)
## 支援的資料類型
連接器會擷取所有 HBase 值作為基本位元組類型。然後，根據您在 AWS Glue Data Catalog 中定義資料表的方式，它會將值映射至下表中的其中一個 Apache Arrow 資料類型。
****
| AWS Glue 資料類型 | Apache Arrow 資料類型 |
| --- | --- |
| int | INT |
| bigint | BIGINT |
| double | FLOAT8 |
| float | FLOAT4 |
| boolean | BIT |
| binary | VARBINARY |
| string | VARCHAR |
**注意**
如果您不使用 AWS Glue 補充中繼資料，連接器的結構描述推論只會使用資料類型 `BIGINT`、 `FLOAT8`和 `VARCHAR`。
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-hbase.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hbase/athena-hbase.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
+ **AWS Glue Data Catalog** – HBase 連接器需要對 的唯讀存取權 AWS Glue Data Catalog ，才能取得結構描述資訊。
+ **CloudWatch Logs** - 連接器需要存取 CloudWatch Logs 以儲存日誌。
+ **AWS Secrets Manager 讀取存取** – 如果您選擇將 HBase 端點詳細資訊存放在 Secrets Manager 中，則必須授予連接器存取這些秘密的權限。
+ **VPC 存取** - 連接器需要能夠將介面連接到 VPC 並能進行分離，以便可進行連接並與 HBase 執行個體通訊。
## 效能
Athena HBase 連接器透過平行讀取每個區域伺服器，嘗試對 HBase 執行個體平行處理查詢。Athena HBase 連接器執行述詞下推，以減少查詢掃描的資料。
Lambda 函數還執行*投影*下推，以減少查詢掃描的資料。不過，選取資料欄子集有時會導致較長的查詢執行時期。`LIMIT` 子句可減少掃描的資料量，但是如果您未提供述詞，則應期望具有 `LIMIT` 子句的 `SELECT` 查詢掃描至少 16 MB 的資料。
HBase 容易導致查詢失敗和可變的查詢執行時間。您可能必須重試查詢多次才能成功。HBase 連接器由於並行而對限流保有彈性。
## 傳遞查詢
HBase 連接器支援[傳遞查詢](federated-query-passthrough.md)，並且以 NoSQL 為基礎。如需有關使用篩選查詢 Apache HBase 的資訊，請參閱 Apache 文件中的[篩選語言](https://hbase.apache.org/book.html#thrift.filter_language)。
若要透過 HBase 使用傳遞查詢，請使用下列語法：
```
SELECT * FROM TABLE(
system.query(
database => 'database_name',
collection => 'collection_name',
filter => '{query_syntax}'
))
```
下列範例 HBase 傳遞查詢會篩選 `default` 資料庫的 `employee` 集合內年齡為 24 或 30 歲的員工。
```
SELECT * FROM TABLE(
system.query(
DATABASE => 'default',
COLLECTION => 'employee',
FILTER => 'SingleColumnValueFilter(''personaldata'', ''age'', =, ''binary:30'')' ||
' OR SingleColumnValueFilter(''personaldata'', ''age'', =, ''binary:24'')'
))
```
## 授權資訊
Amazon Athena HBase 連接器專案是依據 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) 來授權的。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hbase)。
# Amazon Athena Hortonworks 連接器
適用於 Hortonworks 的 Amazon Athena 連接器可讓 Amazon Athena 能夠在 Cloudera [Hortonworks](https://www.cloudera.com/products/hdp.html) 資料平台上執行 SQL 查詢。連接器可將您的 Athena SQL 查詢轉換為其同等的 HiveQL 語法。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
## 條款
下列術語與 Hortonworks Hive 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 Hortonworks Hive 連接器。
### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
hive://${jdbc_connection_string}
```
### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | HiveMuxCompositeHandler |
| 中繼資料處理常式 | HiveMuxMetadataHandler |
| 記錄處理常式 | HiveMuxRecordHandler |
#### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 myhivecatalog，則環境變數名稱為 myhivecatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Hive MUX Lambda 函數：`hive1` (預設) 和 `hive2`。
****
| 屬性 | Value |
| --- | --- |
| default | hive://jdbc:hive2://hive1:10000/default?\$1\$1Test/RDS/hive1\$1 |
| hive\$1catalog1\$1connection\$1string | hive://jdbc:hive2://hive1:10000/default?\$1\$1Test/RDS/hive1\$1 |
| hive\$1catalog2\$1connection\$1string | hive://jdbc:hive2://hive2:10000/default?UID=sample&PWD=sample |
#### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${Test/RDS/hive1host}`。
```
hive://jdbc:hive2://hive1host:10000/default?...&${Test/RDS/hive1host}&...
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
hive://jdbc:hive2://hive1host:10000/default?...&UID=sample2&PWD=sample2&...
```
目前，Hortonworks Hive 連接器可辨識 `UID` 和 `PWD` JDBC 屬性。
### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Hortonworks Hive 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | HiveCompositeHandler |
| 中繼資料處理常式 | HiveMetadataHandler |
| 記錄處理常式 | HiveRecordHandler |
#### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 Hortonworks Hive 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | hive://jdbc:hive2://hive1host:10000/default?secret=\$1\$1Test/RDS/hive1host\$1 |
### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC、Hortonworks Hive 和 Arrow 的相應資料類型。
****
| JDBC | Hortonworks Hive | Arrow |
| --- | --- | --- |
| Boolean | Boolean | 位元 |
| Integer | TINYINT | Tiny |
| Short | SMALLINT | Smallint |
| Integer | INT | Int |
| Long | BIGINT | Bigint |
| float | float4 | Float4 |
| Double | float8 | Float8 |
| Date | date | DateDay |
| 時間戳記 | timestamp | DateMilli |
| String | VARCHAR | Varchar |
| 位元組 | 位元組 | Varbinary |
| BigDecimal | Decimal (小數) | Decimal (小數) |
| ARRAY | N/A (請參閱備註) | 清單 |
**注意**
目前，Hortonworks Hive 不支援彙總類型 `ARRAY`、`MAP`、`STRUCT` 或 `UNIONTYPE`。彙總類型的資料欄在 SQL 中被視為 `VARCHAR` 資料欄。
## 分割區和分隔
分割區用於決定如何產生連接器的分割。Athena 建構了類型 `varchar` 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。
## 效能
Hortonworks Hive 支援靜態分割區。Athena Hortonworks Hive 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大型的資料集，強烈建議使用靜態分割。選取資料欄子集可大幅加速查詢執行期，並減少掃描的資料。Hortonworks Hive 連接器由於並行而對限流保有彈性。
Athena Hortonworks Hive 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Hortonworks Hive 連接器可以結合這些表達式，並將它們直接推送到 Hortonworks Hive，以增強功能並減少掃描的資料量。
下列 Athena Hortonworks Hive 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## 傳遞查詢
Hortonworks Hive 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Hortonworks Hive 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Hortonworks Hive 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Hortonworks Hive 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hortonworks-hive)。
# Amazon Athena Apache Kafka 連接器
適用於 Apache Kafka 的 Amazon Athena 連接器可讓 Amazon Athena 能夠對 Apache Kafka 主題執行 SQL 查詢。使用此連接器可以在 Athena 中以資料表的形式檢視 [Apache Kafka](https://kafka.apache.org/) 主題，並以資料列的形式檢視訊息。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
## 先決條件
使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 篩選條件中的日期和時間戳記資料類型必須轉換為適當的資料類型。
+ 日期和時間戳記資料類型不受 CSV 檔案類型支援，且會被視為 varchar 值。
+ 不支援映射至巢狀 JSON 欄位。連接器僅映射最上層欄位。
+ 連接器不支援複雜類型。複雜類型會轉譯為字串。
+ 若要擷取或使用複雜的 JSON 值，請使用 Athena 中提供的 JSON 相關函數。如需詳細資訊，請參閱[從字串擷取 JSON 資料](extracting-data-from-JSON.md)。
+ 連接器不支援存取 Kafka 訊息中繼資料。
## 條款
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **Kafka 端點** – 與 Kafka 執行個體建立連線的文字字串。
## 叢集相容性
Kafka 連接器可搭配下列叢集類型使用。
+ **獨立 Kafka** – 直接連接至 Kafka (已進行身分驗證或未進行身分驗證)。
+ **Confluent** – 直接連線至 Confluent Kafka。如需有關搭配 Confluent Kafka 資料使用 Athena 的資訊，請參閱*AWS 商業智慧部落格*[中的使用 Amazon Athena 在 Quick 中視覺化 Confluent 資料](https://aws.amazon.com/blogs/business-intelligence/visualize-confluent-data-in-amazon-quicksight-using-amazon-athena/)。
### 連線至 Confluent
連線到 Confluent 需要以下步驟：
1. 從 Confluent 產生一個 API 金鑰。
1. 將 Confluent API 金鑰的使用者名稱和密碼儲存到 AWS Secrets Manager。
1. 提供 Kafka 連接器中 `secrets_manager_secret` 環境變數的密碼名稱。
1. 請遵循本文件 [設定 Kafka 連接器](#connectors-kafka-setup) 一節中的步驟。
## 支援的身分驗證方法
連接器支援下列身分驗證方法。
+ [SSL](https://kafka.apache.org/documentation/#security_ssl)
+ [SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram)
+ SASL/PLAIN
+ SASL/PLAINTEXT
+ NO\$1AUTH
+ **自我管理的 Kafka 和 Confluent 平台** – SSL、SASL/SCRAM、SASL/PLAINTEXT、NO\$1AUTH
+ **自我管理的 Kafka 和 Confluent 雲端** – SASL/PLAIN
如需詳細資訊，請參閱[設定 Athena Kafka 連接器的身分驗證](#connectors-kafka-setup-configuring-authentication)。
## 支援的輸入資料格式
連接器支援以下輸入資料格式。
+ JSON
+ CSV
+ AVRO
+ PROTOBUF (PROTOCOL BUFFERS)
## Parameters
使用本節中的參數來設定 Athena Kafka 連接器。
+ **auth\$1type** – 指定叢集的身分驗證類型。連接器支援下列身分驗證類型：
+ **NO\$1AUTH** – 直接連接至 Kafka (例如，連接至透過無需使用身分驗證之 EC2 執行個體部署的 Kafka 叢集)。
+ **SASL\$1SSL\$1PLAIN** – 此方法使用 `SASL_SSL` 安全通訊協定和 `PLAIN` SASL 機制。如需詳細資訊，請參閱 Apache Kafka 文件中的 [SASL 組態](https://kafka.apache.org/documentation/#security_sasl_config)。
+ **SASL\$1PLAINTEXT\$1PLAIN** – 此方法使用 `SASL_PLAINTEXT` 安全通訊協定和 `PLAIN` SASL 機制。如需詳細資訊，請參閱 Apache Kafka 文件中的 [SASL 組態](https://kafka.apache.org/documentation/#security_sasl_config)。
+ **SASL\$1SSL\$1SCRAM\$1SHA512** – 您可以使用此身分驗證類型來控制對 Apache Kafka 叢集的存取。此方法會將使用者名稱和密碼存放在其中 AWS Secrets Manager。秘密必須與 Kafka 叢集相關聯。如需詳細資訊，請參閱 Apache Kafka 文件中的[使用 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 組態](https://kafka.apache.org/documentation/#security_sasl_config)一節。
+ **SSL** – SSL 身分驗證使用金鑰存放區和信任存放區檔案來連接 Apache Kafka 叢集。您必須產生信任存放區和金鑰存放區檔案，將其上傳至 Amazon S3 儲存貯體，並在部署連接器時提供 Amazon S3 參考。金鑰存放區、信任存放區和 SSL 金鑰會存放在其中 AWS Secrets Manager。部署連接器時，您的用戶端必須提供 AWS 私密金鑰。如需詳細資訊，請參閱 Apache Kafka 文件中的[使用 SSL 進行加密和身分驗證](https://kafka.apache.org/documentation/#security_ssl)。
如需詳細資訊，請參閱[設定 Athena Kafka 連接器的身分驗證](#connectors-kafka-setup-configuring-authentication)。
+ **certificates\$1s3\$1reference** – 包含憑證 (金鑰存放區和信任存放區檔案) 的 Amazon S3 位置。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 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/zh_tw/athena/latest/ug/connectors-kafka.html)
+ **Subnet IDs** – 一個或多個子網路 ID，其對應於 Lambda 函數可用來存取資料來源的子網路。
+ **公有 Kafka 叢集或標準 Confluent 雲端叢集** – 將連接器與具有 NAT 閘道的私有子網路建立關聯。
+ **Confluent 雲端叢集與私有連線** – 將連接器與具有對 Confluent 雲端叢集的路由的私有子網路建立關聯。
+ 對於 [AWS Transit Gateway](https://docs.confluent.io/cloud/current/networking/aws-transit-gateway.html)，子網路必須位於連接至 Confluent 雲端使用的同一傳輸閘道的 VPC 中。
+ 對於 [VPC 對等連線](https://docs.confluent.io/cloud/current/networking/peering/aws-peering.html)，子網路必須位於對等連線至 Confluent 雲端 VPC 的 VPC 中。
+ 對於 [AWS PrivateLink](https://docs.confluent.io/cloud/current/networking/private-links/aws-privatelink.html)，子網路必須位於已路由至連線至 Confluent 雲端的 VPC 端點的 VPC 中。
**注意**
如果您將連接器部署到 VPC 中以存取私有資源，並且還想要連接到可公開存取的服務 (例如 Confluent)，則必須將連接器與具有 NAT 閘道的私有子網路建立關聯。如需詳細資訊，請參閱《Amazon VPC 使用者指南》中的 [NAT 閘道](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)。
## 支援的資料類型
下表顯示 Kafka 和 Apache Arrow 支援的相應資料類型。
****
| Kafka | Arrow |
| --- | --- |
| CHAR | VARCHAR |
| VARCHAR | VARCHAR |
| TIMESTAMP | 毫秒 |
| DATE | DAY |
| BOOLEAN | BOOL |
| SMALLINT | SMALLINT |
| INTEGER | INT |
| BIGINT | BIGINT |
| DECIMAL | FLOAT8 |
| DOUBLE | FLOAT8 |
## 分割區和分隔
Kafka 主題會分為多個分割區。每個分割區都已排序。分割區中的每個訊息都有一個稱為*位移*的增量 ID。每個 Kafka 分割區可再細分為多個分隔，用於並行處理。資料在 Kafka 叢集中設定的保留期間內可供使用。
## 最佳實務
最佳實務是在您查詢 Athena 時使用述詞下推，如以下範例所示。
```
SELECT *
FROM "kafka_catalog_name"."glue_schema_registry_name"."glue_schema_name"
WHERE integercol = 2147483647
```
```
SELECT *
FROM "kafka_catalog_name"."glue_schema_registry_name"."glue_schema_name"
WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878'
```
## 設定 Kafka 連接器
您必須先設定 Apache Kafka 叢集、使用 [AWS Glue 結構描述登錄檔](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)來定義結構描述，以及為連接器設定身分驗證，才能使用連接器。
使用 AWS Glue 結構描述登錄檔時，請注意下列幾點：
+ 請確定 AWS Glue 結構描述登錄檔的 **Description** (描述) 欄位中的文字包含字串 `{AthenaFederationKafka}`。搭配 Amazon Athena Kafka 連接器使用的 AWS Glue 登錄檔需要此標記字串。
+ 為了獲得最佳效能，請僅使用小寫作為資料庫名稱和資料表名稱。使用混合大小寫會導致連接器執行運算密集程度較高的不區分大小寫搜尋。
**設定您的 Apache Kafka 環境和 AWS Glue 結構描述登錄檔**
1. 設定 Apache Kafka 環境。
1. 將 JSON 格式的 Kafka 主題描述檔案 （即其結構描述） 上傳至 AWS Glue 結構描述登錄檔。如需詳細資訊，請參閱《 AWS Glue 開發人員指南》中的[整合 AWS Glue 結構描述登錄](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html)檔。
1. 若要在 AWS Glue 結構描述登錄檔中定義結構描述時使用 `AVRO` 或 `PROTOBUF` 資料格式：
+ 對於**結構描述名稱**，請輸入與原名稱大小寫相同的 Kafka 主題名稱。
+ 對於**資料格式**，選擇 **Apache Avro** 或 **Protocol Buffers**。
如需範例結構描述，請參閱下一節。
### 結構描述登錄檔的 AWS Glue 結構描述範例
將結構描述上傳至 [AWS Glue 結構描述登錄檔](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)時，請使用本節中的範例格式。
#### JSON 類型結構描述範例
在下列範例中，要在結構描述登錄檔中建立的 AWS Glue 結構描述指定 `json`作為 的值`dataFormat`，並`datatypejson`用於 `topicName`。
**注意**
`topicName` 的值應使用與 Kafka 中的主題名稱相同的大小寫。
```
{
"topicName": "datatypejson",
"message": {
"dataFormat": "json",
"fields": [
{
"name": "intcol",
"mapping": "intcol",
"type": "INTEGER"
},
{
"name": "varcharcol",
"mapping": "varcharcol",
"type": "VARCHAR"
},
{
"name": "booleancol",
"mapping": "booleancol",
"type": "BOOLEAN"
},
{
"name": "bigintcol",
"mapping": "bigintcol",
"type": "BIGINT"
},
{
"name": "doublecol",
"mapping": "doublecol",
"type": "DOUBLE"
},
{
"name": "smallintcol",
"mapping": "smallintcol",
"type": "SMALLINT"
},
{
"name": "tinyintcol",
"mapping": "tinyintcol",
"type": "TINYINT"
},
{
"name": "datecol",
"mapping": "datecol",
"type": "DATE",
"formatHint": "yyyy-MM-dd"
},
{
"name": "timestampcol",
"mapping": "timestampcol",
"type": "TIMESTAMP",
"formatHint": "yyyy-MM-dd HH:mm:ss.SSS"
}
]
}
}
```
#### CSV 類型結構描述範例
在下列範例中，要在結構描述登錄檔中建立的 AWS Glue 結構描述會指定 `csv`作為 的值`dataFormat`，並`datatypecsvbulk`用於 `topicName`。`topicName` 的值應使用與 Kafka 中的主題名稱相同的大小寫。
```
{
"topicName": "datatypecsvbulk",
"message": {
"dataFormat": "csv",
"fields": [
{
"name": "intcol",
"type": "INTEGER",
"mapping": "0"
},
{
"name": "varcharcol",
"type": "VARCHAR",
"mapping": "1"
},
{
"name": "booleancol",
"type": "BOOLEAN",
"mapping": "2"
},
{
"name": "bigintcol",
"type": "BIGINT",
"mapping": "3"
},
{
"name": "doublecol",
"type": "DOUBLE",
"mapping": "4"
},
{
"name": "smallintcol",
"type": "SMALLINT",
"mapping": "5"
},
{
"name": "tinyintcol",
"type": "TINYINT",
"mapping": "6"
},
{
"name": "floatcol",
"type": "DOUBLE",
"mapping": "7"
}
]
}
}
```
#### AVRO 類型結構描述範例
下列範例用於在 AWS Glue 結構描述登錄檔中建立以 AVRO 為基礎的結構描述。當您在結構描述登錄檔中定義 AWS Glue 結構描述時，對於**結構描述名稱**，您可以在與原始 相同的大小寫中輸入 Kafka 主題名稱，對於**資料格式**，您可以選擇 **Apache Avro**。由於您直接在登錄檔中指定此資訊，因此不需要 `dataformat` 和 `topicName` 欄位。
```
{
"type": "record",
"name": "avrotest",
"namespace": "example.com",
"fields": [{
"name": "id",
"type": "int"
},
{
"name": "name",
"type": "string"
}
]
}
```
#### PROTOBUF 類型結構描述範例
下列範例用於在 AWS Glue 結構描述登錄檔中建立以 PROTOBUF 為基礎的結構描述。當您在結構描述登錄檔中定義 AWS Glue 結構描述時，對於**結構描述名稱**，您可以在與原始 相同的大小寫中輸入 Kafka 主題名稱，對於**資料格式**，您可以選擇**通訊協定緩衝區**。由於您直接在登錄檔中指定此資訊，因此不需要 `dataformat` 和 `topicName` 欄位。第一行將結構描述定義為 PROTOBUF。
```
syntax = "proto3";
message protobuftest {
string name = 1;
int64 calories = 2;
string colour = 3;
}
```
如需在結構描述登錄檔中 AWS Glue 新增登錄檔和結構描述的詳細資訊，請參閱 AWS Glue 文件中的[結構描述登錄檔入門](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-gs.html)。
### 設定 Athena Kafka 連接器的身分驗證
您可以使用各種方法對 Apache Kafka 叢集進行身分驗證，包括 SSL、SASL/SCRAM、SASL/PLAIN 和 SASL/PLAINTEXT。
下表顯示了連接器的身分驗證類型，以及每種連接器的安全通訊協定和 SASL 機制。如需有關詳細資訊，請參閱 Apache Kafka 文件的[安全性](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/zh_tw/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/zh_tw/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/zh_tw/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/zh_tw/athena/latest/ug/connectors-kafka.html) |
| SSL | SSL | N/A | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/connectors-kafka.html) |
#### SSL
如果叢集經過 SSL 身分驗證，您必須產生信任存放區和金鑰存放區檔案，並將其上傳到 Amazon S3 儲存貯體。部署連接器時，您必須提供此 Amazon S3 參考。金鑰存放區、信任存放區和 SSL 金鑰會儲存在 AWS Secrets Manager中。您可以在部署連接器時提供 AWS 私密金鑰。
如需有關在 Secrets Manager 中建立祕密的詳細資訊，請參閱[建立 AWS Secrets Manager 祕密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
若要使用此身分驗證類型，請設定環境變數，如下表所示。
****
| 參數 | Value |
| --- | --- |
| 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/)。
1. 在導覽窗格中，選擇 **Secrets** (祕密)。
1. 在 **Secrets** (祕密) 頁面中，選擇祕密的連結。
1. 在祕密的詳細資訊頁面上，選擇 **Retrieve secret value** (擷取祕密值)。
下圖顯示了具有三個金鑰/值對的祕密範例：`keystore_password`、`truststore_password` 和 `ssl_key_password`。
![\[在 Secrets Manager 中擷取 SSL 祕密。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-kafka-setup-1.png)
如需有關使用 SSL with Kafka 的詳細資訊，請參閱 Apache Kafka 文件中的[使用 SSL 進行加密和身分驗證](https://kafka.apache.org/documentation/#security_ssl)。
#### SASL/SCRAM
如果您的叢集使用 SCRAM 身分驗證，則請在部署連接器時提供與叢集相關聯的 Secrets Manager 金鑰。使用者的 AWS 憑證 (祕密金鑰和存取金鑰) 可用於向叢集進行身分驗證。
設定環境變數，如下表所示。
****
| 參數 | Value |
| --- | --- |
| auth\$1type | SASL\$1SSL\$1SCRAM\$1SHA512 |
| secrets\$1manager\$1secret | AWS 私密金鑰的名稱。 |
下圖顯示了 Secrets Manager 主控台中含有兩個金鑰/值對的祕密範例：一個用於 `username`，另一個用於 `password`。
![\[在 Secrets Manager 中擷取 SCRAM 祕密。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-kafka-setup-2.png)
如需有關使用 SASL/SCRAM with Kafka 的詳細資訊，請參閱 Apache Kafka 文件中的[使用 SASL/SCRAM 進行身分驗證](https://kafka.apache.org/documentation/#security_sasl_scram)。
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-kafka/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-kafka/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-kafka)。
# Amazon Athena MSK 連接器
適用於 [Amazon MSK](https://aws.amazon.com/msk/) 的 Amazon Athena 連接器可讓 Amazon Athena 能夠對 Apache Kafka 主題執行 SQL 查詢。使用此連接器可以在 Athena 中以資料表的形式檢視 [Apache Kafka](https://kafka.apache.org/) 主題，並以資料列的形式檢視訊息。如需詳細資訊，請參閱 AWS 大[數據部落格中的使用 Amazon Athena 分析 Amazon MSK 中的即時串流](https://aws.amazon.com/blogs/big-data/analyze-real-time-streaming-data-in-amazon-msk-with-amazon-athena/)資料。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
## 先決條件
使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 篩選條件中的日期和時間戳記資料類型必須轉換為適當的資料類型。
+ 日期和時間戳記資料類型不受 CSV 檔案類型支援，且會被視為 varchar 值。
+ 不支援映射至巢狀 JSON 欄位。連接器僅映射最上層欄位。
+ 連接器不支援複雜類型。複雜類型會轉譯為字串。
+ 若要擷取或使用複雜的 JSON 值，請使用 Athena 中提供的 JSON 相關函數。如需詳細資訊，請參閱[從字串擷取 JSON 資料](extracting-data-from-JSON.md)。
+ 連接器不支援存取 Kafka 訊息中繼資料。
## 條款
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **Kafka 端點** – 與 Kafka 執行個體建立連線的文字字串。
## 叢集相容性
MSK 連接器可搭配下列叢集類型使用。
+ **MSK 佈建的叢集** – 您可以手動指定、監控和調整叢集容量。
+ **MSK 無伺服器叢集** – 提供隨需容量，可隨應用程式 I/O 擴展而自動擴展。
+ **獨立 Kafka** – 直接連接至 Kafka (已進行身分驗證或未進行身分驗證)。
## 支援的身分驗證方法
連接器支援下列身分驗證方法。
+ [SASL/IAM](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html)
+ [SSL](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html)
+ [SASL/SCRAM](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html)
+ SASL/PLAIN
+ SASL/PLAINTEXT
+ NO\$1AUTH
如需詳細資訊，請參閱[設定 Athena MSK 連接器的身分驗證](#connectors-msk-setup-configuring-authentication)。
## 支援的輸入資料格式
連接器支援以下輸入資料格式。
+ JSON
+ CSV
## Parameters
使用本節中的參數來設定 Athena MSK 連接器。
+ **auth\$1type** – 指定叢集的身分驗證類型。連接器支援下列身分驗證類型：
+ **NO\$1AUTH** – 直接連接至 Kafka，而不需要身分驗證 (例如，連接至透過無需使用身分驗證之 EC2 執行個體部署的 Kafka 叢集)。
+ **SASL\$1SSL\$1PLAIN** – 此方法使用 `SASL_SSL` 安全通訊協定和 `PLAIN` SASL 機制。
+ **SASL\$1PLAINTEXT\$1PLAIN** – 此方法使用 `SASL_PLAINTEXT` 安全通訊協定和 `PLAIN` SASL 機制。
**注意**
Apache Kafka 支援 `SASL_SSL_PLAIN` 和 `SASL_PLAINTEXT_PLAIN` 身分驗證類型，但 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` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 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/zh_tw/athena/latest/ug/connectors-msk.html)
## 支援的資料類型
下表顯示 Kafka 和 Apache Arrow 支援的相應資料類型。
****
| Kafka | Arrow |
| --- | --- |
| CHAR | VARCHAR |
| VARCHAR | VARCHAR |
| TIMESTAMP | 毫秒 |
| DATE | DAY |
| BOOLEAN | BOOL |
| SMALLINT | SMALLINT |
| INTEGER | INT |
| BIGINT | BIGINT |
| DECIMAL | FLOAT8 |
| DOUBLE | FLOAT8 |
## 分割區和分隔
Kafka 主題會分為多個分割區。每個分割區都已排序。分割區中的每個訊息都有一個稱為*位移*的增量 ID。每個 Kafka 分割區可再細分為多個分隔，用於並行處理。資料在 Kafka 叢集中設定的保留期間內可供使用。
## 最佳實務
最佳實務是在您查詢 Athena 時使用述詞下推，如以下範例所示。
```
SELECT *
FROM "msk_catalog_name"."glue_schema_registry_name"."glue_schema_name"
WHERE integercol = 2147483647
```
```
SELECT *
FROM "msk_catalog_name"."glue_schema_registry_name"."glue_schema_name"
WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878'
```
## 設定 MSK 連接器
您必須先設定 Amazon MSK 叢集、使用 [AWS Glue 結構描述登錄檔](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)來定義結構描述，以及為連接器設定身分驗證，才能使用連接器。
**注意**
如果您將連接器部署到 VPC 中以存取私有資源，並且還想要連接到可公開存取的服務 (例如 Confluent)，則必須將連接器與具有 NAT 閘道的私有子網路建立關聯。如需詳細資訊，請參閱《Amazon VPC 使用者指南》中的 [NAT 閘道](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)。
使用 AWS Glue 結構描述登錄檔時，請注意下列幾點：
+ 請確定 AWS Glue 結構描述登錄檔的 **Description** (描述) 欄位中的文字包含字串 `{AthenaFederationMSK}`。搭配 Amazon Athena MSK 連接器使用的 AWS Glue 註冊機構需要此標記字串。
+ 為了獲得最佳效能，請僅使用小寫作為資料庫名稱和資料表名稱。使用混合大小寫會導致連接器執行運算密集程度較高的不區分大小寫搜尋。
**設定 Amazon MSK 環境和 AWS Glue 結構描述登錄檔**
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 結構描述登錄檔。如需詳細資訊，請參閱《 AWS Glue 開發人員指南》中的[整合 AWS Glue 結構描述登錄](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html)檔。如需範例結構描述，請參閱下一節。
### 結構描述登錄檔的 AWS Glue 結構描述範例
將結構描述上傳至 [AWS Glue 結構描述登錄檔](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)時，請使用本節中的範例格式。
#### JSON 類型結構描述範例
在下列範例中，要在結構描述登錄檔中建立的 AWS Glue 結構描述指定 `json`作為 的值`dataFormat`，並`datatypejson`用於 `topicName`。
**注意**
`topicName` 的值應使用與 Kafka 中的主題名稱相同的大小寫。
```
{
"topicName": "datatypejson",
"message": {
"dataFormat": "json",
"fields": [
{
"name": "intcol",
"mapping": "intcol",
"type": "INTEGER"
},
{
"name": "varcharcol",
"mapping": "varcharcol",
"type": "VARCHAR"
},
{
"name": "booleancol",
"mapping": "booleancol",
"type": "BOOLEAN"
},
{
"name": "bigintcol",
"mapping": "bigintcol",
"type": "BIGINT"
},
{
"name": "doublecol",
"mapping": "doublecol",
"type": "DOUBLE"
},
{
"name": "smallintcol",
"mapping": "smallintcol",
"type": "SMALLINT"
},
{
"name": "tinyintcol",
"mapping": "tinyintcol",
"type": "TINYINT"
},
{
"name": "datecol",
"mapping": "datecol",
"type": "DATE",
"formatHint": "yyyy-MM-dd"
},
{
"name": "timestampcol",
"mapping": "timestampcol",
"type": "TIMESTAMP",
"formatHint": "yyyy-MM-dd HH:mm:ss.SSS"
}
]
}
}
```
#### CSV 類型結構描述範例
在下列範例中，要在結構描述登錄檔中建立的 AWS Glue 結構描述會指定 `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 連接器的身分驗證
您可以使用各種方法對 Amazon MSK 叢集進行身分驗證，包括 IAM、SSL、SCRAM 和獨立 Kafka。
下表顯示了連接器的身分驗證類型，以及每種連接器的安全通訊協定和 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 | N/A |
**注意**
Apache Kafka 支援 `SASL_SSL_PLAIN` 和 `SASL_PLAINTEXT_PLAIN` 身分驗證類型，但 Amazon MSK 不支援。
#### SASL/IAM
如果叢集使用 IAM 身分驗證，則必須在設定叢集時為使用者設定 IAM 政策。如需詳細資訊，請參閱《Amazon Managed Streaming for Apache Kafka 開發人員指南》中的 [IAM 存取控制](https://docs.aws.amazon.com/msk/latest/developerguide/IAM-access-control.html)。
若要使用此身分驗證類型，請將連接器的 `auth_type` Lambda 環境變數設定為 `SASL_SSL_AWS_MSK_IAM`。
#### SSL
如果叢集經過 SSL 身分驗證，您必須產生信任存放區和金鑰存放區檔案，並將其上傳到 Amazon S3 儲存貯體。部署連接器時，您必須提供此 Amazon S3 參考。金鑰存放區、信任存放區和 SSL 金鑰會儲存在 AWS Secrets Manager中。您可以在部署連接器時提供 AWS 私密金鑰。
如需有關在 Secrets Manager 中建立祕密的詳細資訊，請參閱[建立 AWS Secrets Manager 祕密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
若要使用此身分驗證類型，請設定環境變數，如下表所示。
****
| 參數 | Value |
| --- | --- |
| 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/)。
1. 在導覽窗格中，選擇 **Secrets** (祕密)。
1. 在 **Secrets** (祕密) 頁面中，選擇祕密的連結。
1. 在祕密的詳細資訊頁面上，選擇 **Retrieve secret value** (擷取祕密值)。
下圖顯示了具有三個金鑰/值對的祕密範例：`keystore_password`、`truststore_password` 和 `ssl_key_password`。
![\[在 Secrets Manager 中擷取 SSL 祕密。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-msk-setup-1.png)
#### SASL/SCRAM
如果您的叢集使用 SCRAM 身分驗證，則請在部署連接器時提供與叢集相關聯的 Secrets Manager 金鑰。使用者的 AWS 憑證 (祕密金鑰和存取金鑰) 可用於向叢集進行身分驗證。
設定環境變數，如下表所示。
****
| 參數 | Value |
| --- | --- |
| auth\$1type | SASL\$1SSL\$1SCRAM\$1SHA512 |
| secrets\$1manager\$1secret | AWS 私密金鑰的名稱。 |
下圖顯示了 Secrets Manager 主控台中含有兩個金鑰/值對的祕密範例：一個用於 `username`，另一個用於 `password`。
![\[在 Secrets Manager 中擷取 SCRAM 祕密。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-msk-setup-2.png)
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-msk/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-msk/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-msk)。
# Amazon Athena MySQL 連接器
Amazon Athena Lambda MySQL 連接器讓 Amazon Athena 能夠存取 MySQL 資料庫。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
+ 您必須先設定 VPC 和安全群組，才能使用此連接器。如需詳細資訊，請參閱[為資料來源連接器或 AWS Glue 連線建立 VPC](athena-connectors-vpc-creation.md)。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 由於 Athena 將查詢轉換為小寫，因此 MySQL 資料表名稱必須為小寫。例如，Athena 針對名為 `myTable` 的資料表進行查詢會失敗。
+ 如果將 MySQL 連線移轉至 Glue Catalog 和 Lake Formation，則僅會辨識小寫的資料表和資料欄名稱。
## 條款
下列術語與 MySQL 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 MySQL 連接器。
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 MySQL 連接器。
為此，請將 MySQL 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type MYSQL
```
**Lambda 環境屬性**
**glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 MySQL 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 MySQL 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `glue_connection` 環境屬性時，才會使用下列參數。
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
mysql://${jdbc_connection_string}
```
**注意**
如果在對 MySQL 資料表進行 `SELECT` 查詢時，收到錯誤 java.sql.SQLException: Zero date value prohibited (java.sql.SQLException：禁止零日期值)，請將以下參數新增到您的連接字串中：
```
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 資料表中選擇時出現錯誤「禁止零日期值」)。
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | MySqlMuxCompositeHandler |
| 中繼資料處理常式 | MySqlMuxMetadataHandler |
| 記錄處理常式 | MySqlMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mymysqlcatalog，則環境變數名稱為 mymysqlcatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 MySql MUX Lambda 函數：`mysql1` (預設) 和 `mysql2`。
****
| 屬性 | Value |
| --- | --- |
| default | mysql://jdbc:mysql://mysql2.host:3333/default?user=sample2&password=sample2 |
| mysql\$1catalog1\$1connection\$1string | mysql://jdbc:mysql://mysql1.host:3306/default?\$1\$1Test/RDS/MySql1\$1 |
| mysql\$1catalog2\$1connection\$1string | mysql://jdbc:mysql://mysql2.host:3333/default?user=sample2&password=sample2 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${Test/RDS/MySql1}`。
```
mysql://jdbc:mysql://mysql1.host:3306/default?...&${Test/RDS/MySql1}&...
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
mysql://jdbc:mysql://mysql1host:3306/default?...&user=sample2&password=sample2&...
```
目前，MySQL 連接器可辨識 `user` 和 `password` JDBC 屬性。
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 MySQL 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | MySqlCompositeHandler |
| 中繼資料處理常式 | MySqlMetadataHandler |
| 記錄處理常式 | MySqlRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 MySQL 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | mysql://mysql1.host:3306/default?secret=Test/RDS/MySql1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC 和 Arrow 的相應資料類型。
****
| JDBC | Arrow |
| --- | --- |
| Boolean | 位元 |
| Integer | Tiny |
| Short | Smallint |
| Integer | Int |
| Long | Bigint |
| float | Float4 |
| Double | Float8 |
| Date | DateDay |
| 時間戳記 | DateMilli |
| String | Varchar |
| 位元組 | Varbinary |
| BigDecimal | Decimal (小數) |
| ARRAY | 清單 |
## 分割區和分隔
分割區用於決定如何產生連接器的分割。Athena 建構了類型 `varchar` 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。
## 效能
MySQL 支援原生分割區。Athena MySQL 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大的資料集，強烈建議使用原生分割。
Athena MySQL 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena MySQL 連接器可以合併這些表達式，並將其直接推送至 MySQL，以增強功能並減少掃描的資料量。
下列 Athena MySQL 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
如需有關使用述詞下推以改善聯合查詢中的效能 (包括 MySQL) 的文章，請參閱 *AWS 大數據部落格*中的[使用 Amazon Athena 中的述詞下推改善聯合查詢](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)。
## 傳遞查詢
MySQL 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 MySQL 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 MySQL 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 MySQL 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-mysql)。
# Amazon Athena Neptune 連接器
Amazon Neptune 是快速、可靠、全受管的圖形資料庫服務，可讓您輕鬆建置和執行搭配高度連線資料集使用的應用程式。專門打造的 Neptune 高效能圖形資料庫引擎可將數十億筆關係以最佳化方式存放，且查詢圖形時只會產生數毫秒的延遲。如需詳細資訊，請參閱《[Neptune 使用者指南](https://docs.aws.amazon.com/neptune/latest/userguide/intro.html)》。
Amazon Athena Neptune 連接器讓 Athena 能夠與您的 Neptune 圖形資料庫執行個體通訊，以便使用 SQL 查詢來存取您的 Neptune 圖形資料。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
如果您的 帳戶中已啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。
## 先決條件
使用 Neptune 連接器需要以下三個步驟。
+ 設定 Neptune 叢集
+ 設定 AWS Glue Data Catalog
+ 將連接器部署到您的 AWS 帳戶。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。如需特定於部署 Neptune 連接器的其他詳細資訊，請參閱 GitHub.com 上的[部署 Amazon Athena Neptune 連接器](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/neptune-connector-setup)。
## 限制
目前，Neptune 連接器會有下列限制。
+ 不支援投影資料欄，包括主索引鍵 (ID)。
## 設定 Neptune 叢集
如果您沒有想要使用的現有 Amazon Neptune 叢集和屬性圖資料集，則必須設定一個。
確保在託管 Neptune 叢集的 VPC 中具有網際網路閘道和 NAT 閘道。Neptune 連接器 Lambda 函數使用的私有子網應具有透過此 NAT 閘道連線至網際網路的路由。Neptune 連接器 Lambda 函數使用 NAT Gateway 進行通訊 AWS Glue。
如需有關設定新 Neptune 叢集並使用範例資料集載入它的說明，請參閱 GitHub.com 上的 [Sample Neptune Cluster Setup](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/neptune-cluster-setup) (Neptune 叢集設定範例)。
## 設定 AWS Glue Data Catalog
與傳統的關聯式資料存放區不同，Neptune 圖形資料庫節點和邊緣不使用集結構描述。每個條目可以有不同的欄位和資料類型。不過，由於 Neptune 連接器會從 擷取中繼資料 AWS Glue Data Catalog，因此您必須建立資料庫 AWS Glue ，其中包含具有所需結構描述的資料表。建立 AWS Glue 資料庫和資料表之後，連接器會填充可從 Athena 查詢的資料表清單。
### 啟用不區分大小寫的資料欄比對
若要使用正確的大小寫解析 Neptune 資料表中的資料欄名稱，即使資料欄名稱都是小寫的 AWS Glue，您可以將 Neptune 連接器設定為不區分大小寫的比對。
若要啟用此功能，請將 Neptune 連接器 Lambda 函數環境變數 `enable_caseinsensitivematch` 設定為 `true`。
### 指定大小寫資料表名稱的 AWS Glue glabel 資料表參數
由於 僅 AWS Glue 支援小寫資料表名稱，因此當您為 Neptune 建立`glabel` AWS Glue 資料表且 Neptune AWS Glue 資料表名稱包含大小寫時，請務必指定資料表參數。
在 AWS Glue 資料表定義中，包含 `glabel` 參數，並使用其原始大小寫將其值設定為資料表名稱。這可確保在 與您的 Neptune 資料表 AWS Glue 互動時保留正確的大小寫。下列範例會將 `glabel` 的值設定為資料表名稱 `Airport`。
```
glabel = Airport
```
![\[設定glabel AWS Glue 資料表屬性以保留 Neptune 資料表的資料表名稱大小寫\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-neptune-1.png)
如需設定 AWS Glue Data Catalog 以使用 Neptune 的詳細資訊，請參閱在 GitHub.com 上[設定 AWS Glue 目錄](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/aws-glue-sample-scripts)。 GitHub.com.
## 效能
Athena Neptune 連接器執行述詞下推，以減少查詢掃描的資料。不過，使用主索引鍵的述詞會導致查詢失敗。`LIMIT` 子句可減少掃描的資料量，但是如果您未提供述詞，則應期望具有 `LIMIT` 子句的 `SELECT` 查詢掃描至少 16 MB 的資料。Neptune 連接器由於並行而對限流保有彈性。
## 傳遞查詢
Neptune 連接器支援[傳遞查詢](federated-query-passthrough.md)。您可以使用此功能對屬性圖執行 Gremlin 查詢，以及對 RDF 資料執行 SPARQL 查詢。
若要透過 Neptune 建立傳遞查詢，請使用下列語法：
```
SELECT * FROM TABLE(
system.query(
DATABASE => 'database_name',
COLLECTION => 'collection_name',
QUERY => 'query_string'
))
```
下列範例 Neptune 傳遞查詢會篩選代碼為 `ATL` 的機場。雙引號用於逸出。
```
SELECT * FROM TABLE(
system.query(
DATABASE => 'graph-database',
COLLECTION => 'airport',
QUERY => 'g.V().has(''airport'', ''code'', ''ATL'').valueMap()'
))
```
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune)。
# Amazon Athena OpenSearch 連接器
OpenSearch Service
Amazon Athena OpenSearch 連接器讓 Amazon Athena 能夠與您的 OpenSearch 執行個體通訊，以便使用 SQL 來查詢您的 OpenSearch 資料。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
**注意**
由於已知問題，OpenSearch 連接器不能與 VPC 搭配使用。
如果您的 帳戶中已啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 條款
下列術語與 OpenSearch 連接器相關。
+ **網域** - 此連接器與 OpenSearch 執行個體的端點相關聯的名稱。該網域也用作資料庫名稱。對於 Amazon OpenSearch Service 中定義的 OpenSearch 執行個體，可自動探索網域。對於其他執行個體，您必須提供網域名稱和端點之間的映射。
+ **索引** - 在您的 OpenSearch 執行個體中定義的資料庫資料表。
+ **映射** - 如果索引是資料庫資料表，則映射為其結構描述 (亦即其欄位和屬性的定義)。
此連接器支援從 OpenSearch 執行個體和 AWS Glue Data Catalog中擷取中繼資料。如果連接器找到符合您 OpenSearch 網域和索引名稱的 AWS Glue 資料庫和資料表，連接器會嘗試使用這些資料庫和資料表進行結構描述定義。我們建議您建立 AWS Glue 資料表，使其成為 OpenSearch 索引中所有欄位的超級集合。
+ **文件** - 資料庫資料表中的記錄。
+ **資料串流** – 由多個後備索引組成的以時間為基礎的資料料。如需詳細資訊，請參閱 OpenSearch 文件中的[資料串流](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)。
**注意**
由於資料串流索引是透過開放式搜尋在內部建立和管理的，因此連接器會從第一個可用索引中選擇結構描述映射。因此，強烈建議將 AWS Glue 資料表設定為補充中繼資料來源。如需詳細資訊，請參閱[在 中設定資料庫和資料表 AWS Glue](#connectors-opensearch-setting-up-databases-and-tables-in-aws-glue)。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 OpenSearch 連接器。為此，請將 OpenSearch 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type OPENSEARCH
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 OpenSearch 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 OpenSearch 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 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 服務上呼叫適當的描述或清單 API 操作來自動探索您的網域和端點。對於任何其他類型的 OpenSearch 執行個體 (例如，自助託管)，您必須在 `domain_mapping` 變數中指定相關聯的網域端點。如果 `auto_discover_endpoint=true`，連接器會使用 AWS 憑證向 OpenSearch Service 進行身分驗證。否則，連接器 AWS Secrets Manager 會透過 `domain_mapping`變數從 擷取使用者名稱和密碼登入資料。
+ **domain\$1mapping** - 僅在 `auto_discover_endpoint` 設定為 false 並定義網域名稱與其關聯端點之間的映射時使用。`domain_mapping` 變數可以下列格式容納多個 OpenSearch 端點：
```
domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,...
```
為了對 OpenSearch 端點進行身分驗證，連接器支援使用格式 `${SecretName}` 搭配從 AWS Secrets Manager中擷取的使用者名稱和密碼來插入替代字串。該秘密應採用下列 JSON 格式進行存放：
```
{ "username": "your_username", "password": "your_password" }
```
連接器會自動剖析此 JSON 結構，以擷取憑證。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
下列範例使用 `opensearch-creds` 秘密。
```
movies=https://${opensearch-creds}:search-movies-ne...qu---us-east-1---es.amazonaws.com
```
在執行時，`${opensearch-creds}` 呈現為使用者名稱和密碼，如以下範例所示。
```
movies=https://myusername@mypassword:search-movies-ne...qu---us-east-1---es.amazonaws.com
```
在 `domain_mapping` 參數中，每個網域端點對可以使用不同的秘密。秘密本身必須指定為 *user\$1name*@*password* 格式。雖然密碼可能包含內嵌式 `@` 符號，但第一個 `@` 用作 *user\$1name* 的分隔符號。
還需要注意的是，此連接器使用逗號 (,) 和等號 (=) 作為網域端點對的分隔符號。因此，您不應該在儲存的秘密中的任何位置使用它們。
## 在 中設定資料庫和資料表 AWS Glue
連接器使用 AWS Glue 或 OpenSearch 取得中繼資料資訊。您可以將 AWS Glue 資料表設定為補充中繼資料定義來源。若要啟用此功能，請定義符合您正在補充之來源網域和索引的 AWS Glue 資料庫和資料表。連接器也可以透過擷取指定索引的映射，來利用 OpenSearch 執行個體中儲存的中繼資料定義。
### 在 OpenSearch 中定義陣列的中繼資料
OpenSearch 沒有專用的陣列資料類型。任何欄位都可以包含零個或多個值，只要它們是相同的資料類型。如果您要使用 OpenSearch 作為中繼資料定義來源，對於被視為串列或陣列的欄位，您必須為 Athena 搭配使用的所有索引定義 `_meta` 屬性。如果您無法完成此步驟，查詢只會傳回串列欄位中的第一個元素。當您指定 `_meta` 屬性時，欄位名稱應完全符合巢狀 JSON 結構 (例如，`address.street`，其中 `street` 是 `address` 結構內的巢狀欄位）。
以下範例定義 `movies` 資料表中的 `actor` 和 `genre` 清單。
```
PUT movies/_mapping
{
"_meta": {
"actor": "list",
"genre": "list"
}
}
```
### 資料類型
OpenSearch 連接器可以從 AWS Glue 或 OpenSearch 執行個體擷取中繼資料定義。連接器使用下表中的映射，將定義轉換為 Apache Arrow 資料類型，包括下一節中所述的幾點。
****
| OpenSearch | Apache Arrow | AWS Glue |
| --- | --- | --- |
| 文字、關鍵字、二進位 | VARCHAR | string |
| 長整數 | BIGINT | bigint |
| scaled\$1float | BIGINT | SCALED\$1FLOAT(...) |
| integer | INT | int |
| short | SMALLINT | smallint |
| byte | TINYINT | tinyint |
| double | FLOAT8 | double |
| float, half\$1float | FLOAT4 | float |
| boolean | BIT | boolean |
| date, date\$1nanos | DATEMILLI | timestamp |
| JSON 結構 | STRUCT | STRUCT |
| \$1meta (如需詳細資訊，請參閱 [在 OpenSearch 中定義陣列的中繼資料](#connectors-opensearch-defining-metadata-for-arrays-in-opensearch) 一節)。 | LIST | ARRAY |
#### 資料類型的注意事項
+ 目前，連接器僅支援前面的表格中列出的 OpenSearch 和 AWS Glue 資料類型。
+ `scaled_float` 是由固定雙精度比例係數調整的浮點數，在 Apache Arrow 中表示為 `BIGINT`。例如，若比例係數為 100，則 0.756 會四捨五入為 76。
+ 若要在 `scaled_float`中定義 AWS Glue，您必須選取`array`資料欄類型，並使用 SCALED\$1FLOAT(*scaling\$1factor*) 格式宣告欄位。
以下範例有效：
```
SCALED_FLOAT(10.51)
SCALED_FLOAT(100)
SCALED_FLOAT(100.0)
```
以下範例無效：
```
SCALED_FLOAT(10.)
SCALED_FLOAT(.5)
```
+ 從 `date_nanos` 轉換為 `DATEMILLI` 時，奈秒四捨五入為最接近的毫秒。`date` 和 `date_nanos` 的有效值包括但不限於下列格式：
```
"2020-05-18T10:15:30.123456789"
"2020-05-15T06:50:01.123Z"
"2020-05-15T06:49:30.123-05:00"
1589525370001 (epoch milliseconds)
```
+ OpenSearch `binary` 是使用 `Base64` 編碼的二進位值的字串表示並轉換為 `VARCHAR`。
## 執行 SQL 查詢
以下是您可以搭配此連接器使用的 DDL 查詢範例。在這些範例中，*function\$1name* 對應於 Lambda 函數的名稱，*domain* 是您要查詢的網域名稱，*index* 是索引的名稱。
```
SHOW DATABASES in `lambda:function_name`
```
```
SHOW TABLES in `lambda:function_name`.domain
```
```
DESCRIBE `lambda:function_name`.domain.index
```
## 效能
Athena OpenSearch 連接器支援碎片式平行掃描。連接器會使用從 OpenSearch 執行個體擷取的叢集運作狀態資訊，為文件搜尋查詢產生多個請求。會針對每個碎片分割請求並同時執行。
連接器也會下推述詞，作為其文件搜尋查詢的一部分。下列範例查詢和述詞顯示連接器如何使用述詞下推。
**Query**
```
SELECT * FROM "lambda:elasticsearch".movies.movies
WHERE year >= 1955 AND year <= 1962 OR year = 1996
```
** 述詞**
```
(_exists_:year) AND year:([1955 TO 1962] OR 1996)
```
## 傳遞查詢
OpenSearch 連接器支援[傳遞查詢](federated-query-passthrough.md)，並且使用 Query DSL 語言。如需有關使用 Query DSL 進行查詢的詳細資訊，請參閱 Elasticsearch 文件中的 [Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) 或 OpenSearch 文件中的[Query DSL](https://opensearch.org/docs/latest/query-dsl/)。
若要透過 OpenSearch 連接器使用傳遞查詢，請使用下列語法：
```
SELECT * FROM TABLE(
system.query(
schema => 'schema_name',
index => 'index_name',
query => "{query_string}"
))
```
下列 OpenSearch 範例傳遞查詢會篩選出 `default` 結構描述的 `employee` 索引中雇用狀態為作用中的員工。
```
SELECT * FROM TABLE(
system.query(
schema => 'default',
index => 'employee',
query => "{ ''bool'':{''filter'':{''term'':{''status'': ''active''}}}}"
))
```
## 其他資源
+ 如需有關使用 Amazon Athena OpenSearch 連接器在單一查詢中查詢 Amazon OpenSearch Service 和 Amazon S3 中的資料的文章，請參閱 *AWS 大數據部落格*中的[使用 Amazon Athena 的 SQL 查詢 Amazon OpenSearch Service 中的資料](https://aws.amazon.com/blogs/big-data/query-data-in-amazon-opensearch-service-using-sql-from-amazon-athena/)。
+ 如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-elasticsearch)。
# Amazon Athena Oracle 連接器
適用於 Oracle 的 Amazon Athena 連接器可讓 Amazon Athena 能夠對內部部署或在 Amazon EC2 或 Amazon RDS 上執行的 Oracle 中存放的資料執行 SQL 查詢。您也可以使用連接器來查詢 [Oracle exadata](https://www.oracle.com/engineered-systems/exadata/) 上的資料。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 僅支援 12.1.0.2 版 Oracle 資料庫。
+ 如果 Oracle 連接器沒有使用 Glue 連線，則連接器會將資料庫、資料表和資料欄名稱轉換為大寫。
如果 Oracle 連接器使用了 Glue 連線，則連接器不會將資料庫、資料表和資料欄名稱預設為大寫。若要變更此大小寫行為，請視需要將 Lambda 的環境變數 `casing_mode` 變更為 `upper` 或 `lower` 。
使用 Glue 連線的 Oracle 連接器不支援使用多工處理常式。
+ 當使用 Oracle `NUMBER` 而未定義精確度與小數位數，Athena 會將此視為 `BIGINT`。若要在 Athena 中取得所需的小數位數，請在 Lambda 環境變數中指定 `default_scale=`。
## 條款
下列術語與 Oracle 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 Oracle 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Oracle 連接器。為此，請將 Oracle 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type ORACLE
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **is\$1fips\$1enabled** – (選用) 啟用 FIPS 模式時，設定為 true。預設值為 false。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。這是沒有關聯 Glue 連線的連接器的預設值。
+ **case\$1insensitive\$1search** – 針對 Oracle 中的結構描述和資料表名稱執行不區分大小寫搜尋。如果查詢包含不符合連接器預設大小寫的結構描述或資料表名稱，請使用此值。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Oracle 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Oracle 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `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** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **is\$1fips\$1enabled** – (選用) 啟用 FIPS 模式時，設定為 true。預設值為 false。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。這是沒有關聯 Glue 連線的連接器的預設值。
+ **case\$1insensitive\$1search** – 針對 Oracle 中的結構描述和資料表名稱執行不區分大小寫搜尋。如果查詢包含不符合連接器預設大小寫的結構描述或資料表名稱，請使用此值。
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
oracle://${jdbc_connection_string}
```
**注意**
如果您的密碼包含特殊字元 (例如，`some.password`)，當您將密碼傳遞給連線字串時，請以雙引號括住密碼 (例如，`"some.password"`)。如果沒有這樣做，會導致指定的 Oracle URL 無效錯誤。
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Oracle 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | OracleCompositeHandler |
| 中繼資料處理常式 | OracleMetadataHandler |
| 記錄處理常式 | OracleRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
| IsFIPSEnabled | 選用。啟用 FIPS 模式時，設定為 true。預設值為 false。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
該連接器支援基於 SSL 的 Amazon RDS 執行個體連接。支援範圍僅限於 Transport Layer Security (TLS) 通訊協定，以及用戶端對伺服器執行的身分驗證作業。Amazon RDS 中不支援相互身分驗證。下表中的第二列顯示使用 SSL 的語法。
下列範例屬性適用於 Lambda 函數所支援的單一 Oracle 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@//hostname:port/servicename |
| | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS) (HOST=)(PORT=))(CONNECT\$1DATA=(SID=))(SECURITY=(SSL\$1SERVER\$1CERT\$1DN=))) |
#### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 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"`)。如果沒有這樣做，會導致指定的 Oracle URL 無效錯誤。
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${Test/RDS/Oracle}`。
```
oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
oracle://jdbc:oracle:thin:username/password@//hostname:port/servicename
```
目前，Oracle 連接器可辨識 `UID` 和 `PWD` JDBC 屬性。
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | OracleMuxCompositeHandler |
| 中繼資料處理常式 | OracleMuxMetadataHandler |
| 記錄處理常式 | OracleMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 myoraclecatalog，則環境變數名稱為 myoraclecatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Oracle MUX Lambda 函數：`oracle1` (預設) 和 `oracle2`。
****
| 屬性 | Value |
| --- | --- |
| default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename |
| oracle\$1catalog1\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename |
| oracle\$1catalog2\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle2\$1@//oracle2.hostname:port/servicename |
## 支援的資料類型
下表顯示 JDBC、Oracle 和 Arrow 的相應資料類型。
****
| JDBC | Oracle | Arrow |
| --- | --- | --- |
| Boolean | boolean | 位元 |
| Integer | N/A | Tiny |
| Short | smallint | Smallint |
| Integer | integer | Int |
| Long | bigint | Bigint |
| float | float4 | Float4 |
| Double | float8 | Float8 |
| Date | date | DateDay |
| 時間戳記 | timestamp | DateMilli |
| String | text | Varchar |
| 位元組 | 位元組 | Varbinary |
| BigDecimal | numeric(p,s) | Decimal (小數) |
| ARRAY | N/A (請參閱備註) | 清單 |
## 分割區和分隔
分割區用於決定如何產生連接器的分割。Athena 建構了類型 `varchar` 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。
## 效能
Oracle 支援原生分割區。Athena Oracle 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大的資料集，強烈建議使用原生分割。選取資料欄子集可大幅加速查詢執行期，並減少掃描的資料。Oracle 連接器由於並行而對限流保有彈性。但是，查詢執行時間往往會很長。
Athena Oracle 連接器執行述詞下推，以減少查詢掃描的資料。簡單述詞和複雜表達式會下推至連接器，以減少掃描的資料量並減少查詢執行時間。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Oracle 連接器可以合併這些表達式，並將其直接推送至 Oracle，以增強功能並減少掃描的資料量。
下列 Athena Oracle 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## 傳遞查詢
Oracle 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Oracle 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Oracle 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Oracle 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-oracle)。
# Amazon Athena PostgreSQL 連接器
Amazon Athena PostgreSQL 連接器讓 Athena 能夠存取您的 PostgreSQL 資料庫。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 與 PostgreSQL 類似，Athena 會將 PostgreSQL `CHAR` 類型中的尾隨空格視為在長度和比較方面於語義上是無關緊要。請注意，這僅適用於 `CHAR`，但不適用於 `VARCHAR` 類型。Athena 會忽略 `CHAR` 類型的尾隨空格，但會將其視為對 `VARCHAR` 類型具有重要意義。
+ 當您使用 [citext](https://www.postgresql.org/docs/current/citext.html) 不區分大小寫字元字串資料類型時，PostgreSQL 會使用與 Athena 不同的不區分大小寫資料比較。此差異會在 SQL `JOIN` 操作期間產生資料差異。若要解決此問題，請使用 PostgreSQL 連接器傳遞查詢功能。如需詳細資訊，請參閱本文件後面的[傳遞查詢](#connectors-postgres-passthrough-queries)一節。
## 條款
下列術語與 PostgreSQL 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 PostgreSQL 連接器。
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 PostgreSQL 連接器。
為此，請將 PostgreSQL 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type POSTGRESQL
```
**Lambda 環境屬性**
**glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 PostgreSQL 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 PostgreSQL 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `glue_connection` 環境屬性時，才會使用下列參數。
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
postgres://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | PostGreSqlMuxCompositeHandler |
| 中繼資料處理常式 | PostGreSqlMuxMetadataHandler |
| 記錄處理常式 | PostGreSqlMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mypostgrescatalog，則環境變數名稱為 mypostgrescatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 PostGreSql MUX Lambda 函數：`postgres1` (預設) 和 `postgres2`。
****
| 屬性 | Value |
| --- | --- |
| default | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 |
| postgres\$1catalog1\$1connection\$1string | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 |
| postgres\$1catalog2\$1connection\$1string | postgres://jdbc:postgresql://postgres2.host:5432/default?user=sample&password=sample |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${Test/RDS/PostGres1}`。
```
postgres://jdbc:postgresql://postgres1.host:5432/default?...&${Test/RDS/PostGres1}&...
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
postgres://jdbc:postgresql://postgres1.host:5432/default?...&user=sample2&password=sample2&...
```
目前，PostgreSQL 連接器可辨識 `user` 和 `password` JDBC 屬性。
##### 正在啟用 SSL
若要在 PostgreSQL 連線中支援 SSL，請將下列內容附加到您的連線字串中：
```
&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory
```
**範例**
下列範例連線字串並未使用 SSL。
```
postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword
```
若要啟用 SSL，請依照下列方式修改字串。
```
postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory
```
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 PostgreSQL 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | PostGreSqlCompositeHandler |
| 中繼資料處理常式 | PostGreSqlMetadataHandler |
| 記錄處理常式 | PostGreSqlRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 PostgreSQL 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | postgres://jdbc:postgresql://postgres1.host:5432/default?secret=\$1\$1Test/RDS/PostgreSQL1\$1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC、PostGreSQL 和 Arrow 的相應資料類型。
****
| JDBC | PostGreSQL | Arrow |
| --- | --- | --- |
| Boolean | Boolean | 位元 |
| Integer | N/A | Tiny |
| Short | smallint | Smallint |
| Integer | integer | Int |
| Long | bigint | Bigint |
| float | float4 | Float4 |
| Double | float8 | Float8 |
| Date | date | DateDay |
| 時間戳記 | timestamp | DateMilli |
| String | text | Varchar |
| 位元組 | 位元組 | Varbinary |
| BigDecimal | numeric(p,s) | Decimal (小數) |
| ARRAY | N/A (請參閱備註) | 清單 |
**注意**
PostgreSQL 連接器支援 `ARRAY` 類型，但有以下限制：不支援多維陣列 (`[][]` 或巢狀陣列)。具有不受支援之 `ARRAY` 資料類型的資料欄被轉換為字串元素陣列 (`array`)。
## 分割區和分隔
分割區用於決定如何產生連接器的分割。Athena 建構了類型 `varchar` 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。
## 效能
PostgreSQL 支援原生分割區。Athena PostgreSQL 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大的資料集，強烈建議使用原生分割。
Athena PostgreSQL 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。不過，選取資料欄子集有時會導致查詢執行期更長。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena PostgreSQL 連接器可以合併這些表達式，並將其直接推送至 PostgreSQL，以增強功能並減少掃描的資料量。
下列 Athena PostgreSQL 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## 傳遞查詢
PostgreSQL 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 PostgreSQL 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 PostgreSQL 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 PostgreSQL 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-postgresql/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-postgresql)。
# Amazon Athena Redis OSS 連接器
Amazon Athena 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 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
如果您的 帳戶中已啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。
Amazon Athena Redis OSS 連接器支援 Amazon MemoryDB 和 Amazon ElastiCache (Redis OSS)。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
+ 您必須先設定 VPC 和安全群組，才能使用此連接器。如需詳細資訊，請參閱[為資料來源連接器或 AWS Glue 連線建立 VPC](athena-connectors-vpc-creation.md)。
## Parameters
使用本節中的參數來設定 Redis 連接器。
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **glue\$1catalog** - (選用) 使用此選項可指定[跨帳戶 AWS Glue 目錄](data-sources-glue-cross-account.md)。根據預設，連接器會嘗試從自己的 AWS Glue 帳戶取得中繼資料。
## 在 中設定資料庫和資料表 AWS Glue
若要啟用 AWS Glue 資料表以搭配 Redis OSS 使用，您可以在 資料表上設定下列資料表屬性：`redis-value-type`、 `redis-endpoint`和 `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`) 或者，您可以使用 AWS Secrets Manager \$1\$1*Secret\$1Name*\$1 作為資料表屬性值，在 中存放端點或部分端點。
**注意**
若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
+ **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** - (選用) 僅適用於獨立的非叢集執行個體。設定此數字 (例如 1、2 或 3) 以便從非預設 Redis 資料庫中讀取。預設值為 Redis 邏輯資料庫 0。此數字不是指 Athena 中的資料庫 AWS Glue，也不是指 Redis 邏輯資料庫。如需詳細資訊，請參閱 Redis 文件中的 [SELECT 索引](https://redis.io/commands/select)。
## 資料類型
Redis OSS 連接器支援下列資料類型。不支援 Redis OSS 串流。
+ [：字串](https://redis.com/ebook/part-1-getting-started/chapter-1-getting-to-know-redis/1-2-what-redis-data-structures-look-like/1-2-1-strings-in-redis/)
+ [雜湊](https://redis.com/ebook/part-1-getting-started/chapter-1-getting-to-know-redis/1-2-what-redis-data-structures-look-like/1-2-4-hashes-in-redis/)
+ 排序集 ([ZSet](https://redis.com/ebook/part-2-core-concepts/chapter-3-commands-in-redis/3-5-sorted-sets/))
所有 Redis OSS 值被擷取為 `string` 資料類型。然後根據在 AWS Glue Data Catalog中定義資料表的方式，將它們轉換為以下 Apache Arrow 資料類型之一。
****
| AWS Glue 資料類型 | Apache Arrow 資料類型 |
| --- | --- |
| int | INT |
| string | VARCHAR |
| bigint | BIGINT |
| double | FLOAT8 |
| float | FLOAT4 |
| smallint | SMALLINT |
| tinyint | TINYINT |
| boolean | BIT |
| binary | VARBINARY |
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-redis.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-redis/athena-redis.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
+ **AWS Glue Data Catalog** – Redis 連接器需要對 的唯讀存取權 AWS Glue Data Catalog ，才能取得結構描述資訊。
+ **CloudWatch Logs** - 連接器需要存取 CloudWatch Logs 以儲存日誌。
+ **AWS Secrets Manager 讀取存取** – 如果您選擇將 Redis 端點詳細資訊存放在 Secrets Manager 中，則必須授予連接器存取這些秘密的權限。
+ **VPC 存取** - 連接器需要能夠將介面連接到 VPC 並能進行分離，以便可進行連接並與 Redis 執行個體通訊。
## 效能
Athena Redis OSS 連接器會嘗試根據您定義的資料表類型 (例如，zset 索引鍵或字首索引鍵)，對 Redis OSS 執行個體進行並行查詢。
Athena Redis 連接器執行述詞下推，以減少查詢掃描的資料。不過，包含針對主索引鍵的述詞的查詢因逾時而失敗。`LIMIT` 子句可減少掃描的資料量，但是如果您未提供述詞，則應期望具有 `LIMIT` 子句的 `SELECT` 查詢掃描至少 16 MB 的資料。Redis 連接器由於並行而對限流保有彈性。
## 傳遞查詢
Redis 連接器支援[傳遞查詢](federated-query-passthrough.md)。您可以使用此功能，以在 Redis 資料庫上執行使用 Lua 指令碼的查詢。
若要透過 Redis 建立傳遞查詢，請使用下列語法：
```
SELECT * FROM TABLE(
system.script(
script => 'return redis.[call|pcall](query_script)',
keys => '[key_pattern]',
argv => '[script_arguments]'
))
```
下列範例會執行 Lua 指令碼，以取得索引鍵 `l:a` 的值。
```
SELECT * FROM TABLE(
system.script(
script => 'return redis.call("GET", KEYS[1])',
keys => '[l:a]',
argv => '[]'
))
```
## 授權資訊
Amazon Athena Redis 連接器專案是依據 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) 來授權的。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redis)。
# Amazon Athena Redshift 連接器
Amazon Athena Redshift 連接器讓 Amazon Athena 能夠存取 Amazon Redshift 和 Amazon Redshift Serverless 資料庫，包括 Redshift Serverless 檢視。您可以使用此頁面所述的 JDBC 連線字串組態設定來連線至任一服務。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 由於 Redshift 不支援外部分割區，因此每次都會擷取由查詢指定的所有資料。
+ 與 Redshift 類似，Athena 會將 Redshift `CHAR` 類型中的尾隨空格視為在長度和比較方面於語義上是無關緊要。請注意，這僅適用於 `CHAR`，但不適用於 `VARCHAR` 類型。Athena 會忽略 `CHAR` 類型的尾隨空格，但會將其視為對 `VARCHAR` 類型具有重要意義。
## 條款
下列術語與 Redshift 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 Redshift 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Redshift 連接器。為此，請將 Amazon Redshift 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type REDSHIFT
```
**Lambda 環境屬性**
**glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Redshift 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Redshift 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `glue_connection` 環境屬性時，才會使用下列參數。
**Lambda 環境屬性**
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **disable\$1glue** – （選用） 如果存在並設為 true，連接器不會嘗試從中擷取補充中繼資料 AWS Glue。
+ **glue\$1catalog** - (選用) 使用此選項可指定[跨帳戶 AWS Glue 目錄](data-sources-glue-cross-account.md)。根據預設，連接器會嘗試從自己的 AWS Glue 帳戶取得中繼資料。
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
redshift://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | RedshiftMuxCompositeHandler |
| 中繼資料處理常式 | RedshiftMuxMetadataHandler |
| 記錄處理常式 | RedshiftMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 myredshiftcatalog，則環境變數名稱為 myredshiftcatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Redshift MUX Lambda 函數：`redshift1` (預設) 和 `redshift2`。
****
| 屬性 | Value |
| --- | --- |
| default | redshift://jdbc:redshift://redshift1.host:5439/dev?user=sample2&password=sample2 |
| redshift\$1catalog1\$1connection\$1string | redshift://jdbc:redshift://redshift1.host:3306/default?\$1\$1Test/RDS/Redshift1\$1 |
| redshift\$1catalog2\$1connection\$1string | redshift://jdbc:redshift://redshift2.host:3333/default?user=sample2&password=sample2 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 \$1\$1Test/RDS/ `Redshift1`\$1。
```
redshift://jdbc:redshift://redshift1.host:3306/default?...&${Test/RDS/Redshift1}&...
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
redshift://jdbc:redshift://redshift1.host:3306/default?...&user=sample2&password=sample2&...
```
目前，Redshift 連接器可辨識 `user` 和 `password` JDBC 屬性。
## 支援的資料類型
下表顯示 JDBC 和 Apache Arrow 的相應資料類型。
****
| JDBC | Arrow |
| --- | --- |
| Boolean | 位元 |
| Integer | Tiny |
| Short | Smallint |
| Integer | Int |
| Long | Bigint |
| float | Float4 |
| Double | Float8 |
| Date | DateDay |
| 時間戳記 | DateMilli |
| String | Varchar |
| 位元組 | Varbinary |
| BigDecimal | Decimal (小數) |
| ARRAY | 清單 |
## 分割區和分隔
Redshift 不支援外部分割區。如需效能相關問題的資訊，請參閱 [效能](#connectors-redshift-performance)。
## 效能
Athena Redshift 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、`ORDER BY` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。不過，選取資料欄子集有時會導致查詢執行期更長。同時執行多個查詢時，Amazon Redshift 特別容易受到查詢執行速度減慢的影響。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 前 N 個查詢
前 `N` 個查詢會指定結果集的順序，以及傳回的資料列數目的限制。您可以使用這種查詢類型，判斷資料集的前 `N` 個最大值或前 `N` 個最小值。透過前 `N` 個下推，連接器只會向 Athena 傳回 `N` 個排序的資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Redshift 連接器可以合併這些表達式，並將其直接推送至 Redshift，以增強功能並減少掃描的資料量。
下列 Athena Redshift 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
ORDER BY col_a DESC
LIMIT 10;
```
如需有關使用述詞下推以改善聯合查詢中的效能 (包括 Amazon Redshift) 的文章，請參閱 *AWS 大數據部落格*中的[使用 Amazon Athena 中的述詞下推改善聯合查詢](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)。
## 傳遞查詢
Redshift 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Redshift 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Redshift 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Redshift 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-redshift/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redshift)。
# Amazon Athena SAP HANA 連接器
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 在 SAP HANA 中，當物件名稱儲存在 SAP HANA 資料庫中時會轉換為大寫。但是，由於引號中的名稱區分大小寫，因此兩個資料表的名稱可能會相同，分別為小寫和大寫 (例如，`EMPLOYEE` 和 `employee`)。
在 Athena 聯合查詢中，結構描述資料表名稱會以小寫形式提供給 Lambda 函數。若要解決此問題，您可以提供 `@schemaCase` 查詢提示以便從名稱區分大小寫的資料表中擷取資料。以下是具有查詢提示的兩個查詢範例。
```
SELECT *
FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=upper"
```
```
SELECT *
FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=lower"
```
## 條款
下列術語與 SAP HANA 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 SAP HANA 連接器。為此，請將 SAP HANA 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type SAPHANA
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 SAP HANA 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 SAP HANA 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
saphana://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | SaphanaMuxCompositeHandler |
| 中繼資料處理常式 | SaphanaMuxMetadataHandler |
| 記錄處理常式 | SaphanaMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mysaphanacatalog，則環境變數名稱為 mysaphanacatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Saphana MUX Lambda 函數：`saphana1` (預設) 和 `saphana2`。
****
| 屬性 | Value |
| --- | --- |
| default | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 |
| saphana\$1catalog1\$1connection\$1string | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 |
| saphana\$1catalog2\$1connection\$1string | saphana://jdbc:sap://saphana2.host:port/?user=sample2&password=sample2 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${Test/RDS/Saphana1}`。
```
saphana://jdbc:sap://saphana1.host:port/?${Test/RDS/Saphana1}&...
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
saphana://jdbc:sap://saphana1.host:port/?user=sample2&password=sample2&...
```
目前，SAP HANA 連接器可辨識 `user` 和 `password` JDBC 屬性。
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 SAP HANA 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | SaphanaCompositeHandler |
| 中繼資料處理常式 | SaphanaMetadataHandler |
| 記錄處理常式 | SaphanaRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 SAP HANA 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | saphana://jdbc:sap://saphana1.host:port/?secret=Test/RDS/Saphana1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC 和 Apache Arrow 的相應資料類型。
****
| JDBC | Arrow |
| --- | --- |
| Boolean | 位元 |
| Integer | Tiny |
| Short | Smallint |
| Integer | Int |
| Long | Bigint |
| float | Float4 |
| Double | Float8 |
| Date | DateDay |
| 時間戳記 | DateMilli |
| String | Varchar |
| 位元組 | Varbinary |
| BigDecimal | Decimal (小數) |
| ARRAY | 清單 |
## 資料類型轉換
除了 JDBC 到 Arrow 轉換之外，連接器還會執行一些其他轉換，以使 SAP HANA 來源和 Athena 資料類型相容。這些轉換有助於確保成功執行查詢。下表顯示了這些轉換。
****
| 來源資料類型 (SAP HANA) | 轉換後的資料類型 (Athena) |
| --- | --- |
| DECIMAL | BIGINT |
| INTEGER | INT |
| DATE | DATEDAY |
| TIMESTAMP | DATEMILLI |
所有其他不受支援的資料類型都會轉換為 `VARCHAR`。
## 分割區和分隔
分割區由 `Integer` 類型的單一分割區資料欄表示。此資料欄包含 SAP HANA 資料表中所定義之分割區的分割區名稱。對於沒有分割區名稱的資料表，會傳回 \$1，這相當於一個單一的分割區。分割區等同於分隔。
****
| 名稱 | 類型 | 說明 |
| --- | --- | --- |
| PART\$1ID | Integer | SAP HANA 中的已命名分割區。 |
## 效能
SAP HANA 支援原生分割區。Athena SAP HANA 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大的資料集，強烈建議使用原生分割。選取資料欄子集可大幅加速查詢執行期，並減少掃描的資料。由於並行，連接器會顯示嚴重限流，且有時會顯示查詢失敗。
Athena SAP HANA 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行時間。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena SAP HANA 連接器可以合併這些表達式，並將其直接推送至 SAP HANA，以增強功能並減少掃描的資料量。
下列 Athena SAP HANA 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## 傳遞查詢
SAP HANA 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 SAP HANA 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 SAP HANA 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 SAP HANA 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-saphana)。
# Amazon Athena Snowflake 連接器
適用於 [Snowflake](https://www.snowflake.com/) 的 Amazon Athena 連接器可讓 Amazon Athena 使用 JDBC 對存放在 Snowflake SQL 資料庫或 RDS 執行個體中的資料執行 SQL 查詢。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
使用 Athena 主控台或 `CreateDataCatalog` API 操作，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱[建立資料來源連線](connect-to-a-data-source.md)。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 只有舊版連線支援多工器設定。
+ 目前支援採用單一分割方式的 Snowflake 檢視。
+ 在 Snowflake 中，物件名稱區分大小寫。Athena 在 DDL 和 DML 查詢中接受混合大小寫，但在預設情況下，會在執行查詢時[接受](https://docs.aws.amazon.com/athena/latest/ug/tables-databases-columns-names.html#table-names-and-table-column-names-in-ate-must-be-lowercase)物件名稱。使用 Glue Catalog/Lake Formation 時，Snowflake 連接器僅支援小寫。使用 Athena Catalog 時，客戶可以使用 `casing_mode` Lambda 環境變數控制大小寫行為，其可能的值列於 [Parameters](#connectors-snowflake-parameters)區段 （例如 `key=casing_mode, value = CASE_INSENSITIVE_SEARCH`)。
## 條款
下列術語與 Snowflake 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 Snowflake 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Snowflake 連接器。為此，請將 Snowflake 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type SNOWFLAKE
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **NONE** – 請勿變更指定結構描述和資料表名稱的大小寫 （對 Snowflake 執行查詢）。這是未指定 **casing\$1mode** 時的預設值。
+ **UPPER** – 在針對 Snowflake 執行之前，查詢中所有指定結構描述和資料表名稱的大寫。
+ **LOWER** – 在針對 Snowflake 執行之前，查詢中所有指定結構描述和資料表名稱的較小大小寫。
+ **CASE\$1INSENSITIVE\$1SEARCH** – 針對 Snowflake 中的結構描述和資料表名稱執行不區分大小寫的搜尋。例如，當您有類似 的查詢，`SELECT * FROM EMPLOYEE`且 Snowflake 包含名為 的資料表時，您可以使用此模式`Employee`。不過，在出現名稱衝突的情況下，例如在 Snowflake `Employee`中有一個名為 的資料表`EMPLOYEE`和另一個名為 的資料表，查詢將會失敗。
**注意**
使用 Glue 連線建立的 Snowflake 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Snowflake 連接器僅支援 `ConnectionSchemaVersion` 2。
**儲存登入資料**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。如需詳細資訊，請參閱[使用 Snowflake 進行身分驗證](connectors-snowflake-authentication.md)。
### 舊版連線
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `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** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
snowflake://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | SnowflakeMuxCompositeHandler |
| 中繼資料處理常式 | SnowflakeMuxMetadataHandler |
| 記錄處理常式 | SnowflakeMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mysnowflakecatalog，則環境變數名稱為 mysnowflakecatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Snowflake MUX Lambda 函數：`snowflake1` (預設) 和 `snowflake2`。
****
| 屬性 | Value |
| --- | --- |
| default | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1&\$1\$1Test/RDS/Snowflake1\$1 |
| snowflake\$1catalog1\$1connection\$1string | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1\$1\$1Test/RDS/Snowflake1\$1 |
| snowflake\$1catalog2\$1connection\$1string | snowflake://jdbc:snowflake://snowflake2.host:port/?warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 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 屬性。它也接受格式為 *username*`/`*password* 的使用者名稱和密碼，而不使用金鑰 `user` 或 `password`。
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Snowflake 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | SnowflakeCompositeHandler |
| 中繼資料處理常式 | SnowflakeMetadataHandler |
| 記錄處理常式 | SnowflakeRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 Snowflake 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | snowflake://jdbc:snowflake://snowflake1.host:port/?secret=Test/RDS/Snowflake1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC 和 Apache Arrow 的相應資料類型。
****
| JDBC | Arrow |
| --- | --- |
| Boolean | 位元 |
| Integer | Tiny |
| Short | Smallint |
| Integer | Int |
| Long | Bigint |
| float | Float4 |
| Double | Float8 |
| Date | DateDay |
| 時間戳記 | DateMilli |
| String | Varchar |
| 位元組 | Varbinary |
| BigDecimal | Decimal (小數) |
| ARRAY | 清單 |
## 資料類型轉換
除了 JDBC 到 Arrow 轉換之外，連接器還會執行一些其他轉換，以使 Snowflake 來源和 Athena 資料類型相容。這些轉換有助於確保成功執行查詢。下表顯示了這些轉換。
****
| 來源資料類型 (Snowflake) | 轉換後的資料類型 (Athena) |
| --- | --- |
| TIMESTAMP | TIMESTAMPMILLI |
| DATE | TIMESTAMPMILLI |
| INTEGER | INT |
| DECIMAL | BIGINT |
| TIMESTAMP\$1NTZ | TIMESTAMPMILLI |
所有其他不受支援的資料類型都會轉換為 `VARCHAR`。
## 分割區和分隔
分割區用於決定如何產生連接器的分割。Athena 建構了類型 `varchar` 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。
若要建立此合成資料欄和分割區，Athena 需要定義主索引鍵。不過，由於 Snowflake 不會強制執行主索引鍵限制，您必須自行強制執行唯一性。否則，Athena 會預設為單一分割。
## 效能
為了獲得最佳效能，請盡可能在查詢中使用篩選條件。此外，我們強烈建議使用原生分割來擷取具有統一分割區分佈的龐大資料集。選取資料欄子集可大幅加速查詢執行期，並減少掃描的資料。Snowflake 連接器由於並行而對限流保有彈性。
Athena Snowflake 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行期。
### LIMIT 子句
`LIMIT N` 陳述句可減少查詢掃描的資料。透過 `LIMIT N` 下推，連接器只會向 Athena 傳回 `N` 個資料列。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Snowflake 連接器可以合併這些表達式，並將其直接推送至 Snowflake，以增強功能並減少掃描的資料量。
下列 Athena Snowflake 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
# 使用 Snowflake 進行身分驗證
您可以設定 Amazon Athena Snowflake 連接器，讓其使用金鑰對身分驗證或 OAuth 身分驗證方法來連線至 Snowflake 資料倉儲。這兩種方法都能安全存取 Snowflake，而無需在連線字串中存放密碼。
+ **金鑰對身分驗證** – 此方法使用 RSA 公有或私有金鑰對，以進行 Snowflake 的身分驗證。當對應的公有金鑰在 Snowflake 中註冊以進行驗證時，私有金鑰會以數位方式簽署身分驗證請求。此方法無需密碼儲存。
+ **OAuth 身分驗證** –此方法使用授權權杖和重新整理權杖，以進行 Snowflake 的身分驗證。此方法支援自動權杖重新整理，因此適用於長時間執行的應用程式。
如需詳細資訊，請參閱《Snowflake 使用者指南》中的[金鑰對身分驗證](https://docs.snowflake.com/en/user-guide/key-pair-auth)和 [OAuth 身分驗證](https://docs.snowflake.com/en/user-guide/oauth-custom)。
## 先決條件
開始之前，請先完成以下先決條件：
+ 擁有管理權限的 Snowflake 帳戶存取。
+ 專屬於 Athena 連接器的 Snowflake 使用者帳戶。
+ OpenSSL 或同等金鑰產生工具，以進行金鑰對身份驗證。
+ AWS Secrets Manager 建立和管理秘密的存取權。
+ Web 瀏覽器，以完成進行 OAuth 身分驗證的 OAuth 流程。
## 設定金鑰對身分驗證
此程序包括產生 RSA 金鑰對、使用公有金鑰設定 Snowflake 帳戶，以及將私有金鑰安全地存放在 AWS Secrets Manager中。下列步驟將引導您建立密碼編譯金鑰、設定必要的 Snowflake 許可，以及設定 AWS 登入資料以進行無縫身分驗證。
1. **產生 RSA 金鑰對**
使用 OpenSSL 產生私有和公有金鑰對。
+ 若要產生未加密版本，請在本機命令列應用程式中使用下列命令。
```
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```
+ 若要產生加密版本，請使用下列命令，而這會省略 `-nocrypt`。
```
openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
```
+ 從私有金鑰產生公有金鑰。
```
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
# Set appropriate permissions (Unix/Linux)
chmod 600 rsa_key.p8
chmod 644 rsa_key.pub
```
**注意**
請勿共用您的私有金鑰。只有需要進行 Snowflake 身分驗證的應用程式才能存取私有金鑰。
1. **擷取 Snowflake 的公有金鑰內容 (不含分隔符號)**
```
# Extract public key content (remove BEGIN/END lines and newlines)
cat rsa_key.pub | grep -v "BEGIN\|END" | tr -d '\n'
```
儲存此輸出，因為您在後續步驟中需要此輸出。
1. **設定 Snowflake 使用者**
依照以下步驟，設定 Snowflake 使用者。
1. 如果 Athena 連接器尚未存在，請為其建立專用使用者。
```
-- Create user for Athena connector
CREATE USER athena_connector_user;
-- Grant necessary privileges
GRANT USAGE ON WAREHOUSE your_warehouse TO ROLE athena_connector_role;
GRANT USAGE ON DATABASE your_database TO ROLE athena_connector_role;
GRANT SELECT ON ALL TABLES IN DATABASE your_database TO ROLE athena_connector_role;
```
1. 授予身分驗證權限。若要將公有金鑰指派給使用者，您必須擁有下列其中一個角色或權限。
+ 使用者的 `MODIFY PROGRAMMATIC AUTHENTICATION METHODS` 或 `OWNERSHIP` 權限。
+ `SECURITYADMIN` 角色或更高權限。
授予必要權限，以使用下列命令指派公有金鑰。
```
GRANT MODIFY PROGRAMMATIC AUTHENTICATION METHODS ON USER athena_connector_user TO ROLE your_admin_role;
```
1. 使用下列命令，將公有金鑰指派給 Snowflake 使用者。
```
ALTER USER athena_connector_user SET RSA_PUBLIC_KEY='RSAkey';
```
使用以下命令，驗證公有金鑰是否已成功指派給使用者。
```
DESC USER athena_connector_user;
```
1. **在 中存放私有金鑰 AWS Secrets Manager**
1. 將您的私有金鑰轉換為連接器所需的格式。
```
# Read private key content
cat rsa_key.p8
```
1. AWS Secrets Manager 使用下列結構在 中建立秘密。
```
{
"sfUser": "your_snowflake_user",
"pem_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
"pem_private_key_passphrase": "passphrase_in_case_of_encrypted_private_key(optional)"
}
```
**注意**
標頭和頁尾為選用項。
私有金鑰必須以 `\n` 分隔。
## 設定 OAuth 身分驗證
此身分驗證方法可利用自動憑證重新整理功能，啟用對 Snowflake 的安全權杖型存取。組態程序包括在 Snowflake 中建立安全整合、擷取 OAuth 用戶端憑證、完成授權流程以取得存取碼，以及將 OAuth 憑證存放在 AWS Secrets Manager 中以供連接器使用。
1. **在 Snowflake 中建立安全整合**
在 Snowflake 中執行下列 SQL 命令，以建立 Snowflake OAuth 安全整合。
```
CREATE SECURITY INTEGRATION my_snowflake_oauth_integration_a
TYPE = OAUTH
ENABLED = TRUE
OAUTH_CLIENT = CUSTOM
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://localhost:8080/oauth/callback'
OAUTH_ISSUE_REFRESH_TOKENS = TRUE
OAUTH_REFRESH_TOKEN_VALIDITY = 7776000;
```
**組態參數**
+ `TYPE = OAUTH` – 指定 OAuth 身分驗證類型。
+ `ENABLED = TRUE` – 啟用安全整合。
+ `OAUTH_CLIENT = CUSTOM` – 使用自訂 OAuth 用戶端組態。
+ `OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'` – 設定安全應用程式的用戶端類型。
+ `OAUTH_REDIRECT_URI` – OAuth 流程的回呼 URL。其可設為 localhost 以用於測試。
+ `OAUTH_ISSUE_REFRESH_TOKENS = TRUE` – 啟用重新整理權杖產生。
+ `OAUTH_REFRESH_TOKEN_VALIDITY = 7776000` – 設定重新整理權杖有效性 (90 天，以秒為單位)。
1. **擷取 OAuth 用戶端秘密**
1. 請執行下列 SQL 命令，以取得用戶端憑證。
```
DESC SECURITY INTEGRATION 'MY_SNOWFLAKE_OAUTH_INTEGRATION_A';
```
1. 擷取 OAuth 用戶端秘密。
```
SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('MY_SNOWFLAKE_OAUTH_INTEGRATION_A');
```
**回應範例**
```
{
"OAUTH_CLIENT_SECRET_2": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"OAUTH_CLIENT_SECRET": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY,
"OAUTH_CLIENT_ID": "AIDACKCEVSQ6C2EXAMPLE"
}
```
**注意**
保護這些憑證的安全，切勿共用。這些將用於設定 OAuth 用戶端。
1. **授權使用者並擷取授權碼**
1. 在瀏覽器中開啟下列 URL。
```
https://.snowflakecomputing.com/oauth/authorize?client_id=&response_type=code&redirect_uri=https://localhost:8080/oauth/callback
```
1. 完成授權流程。
1. 使用您的 Snowflake 憑證登入。
1. 授予所需的許可。您會被重新導向至具有授權碼的回呼 URI。
1. 從重新導向 URL 複製程式碼參數，擷取授權碼。
```
https://localhost:8080/oauth/callback?code=
```
**注意**
授權碼有效期限有限，且只能使用一次。
1. **在 中存放 OAuth 登入資料 AWS Secrets Manager**
AWS Secrets Manager 使用下列結構在 中建立秘密。
```
{
"redirect_uri": "https://localhost:8080/oauth/callback",
"client_secret": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY",
"token_url": "https://.snowflakecomputing.com/oauth/token-request",
"client_id": "AIDACKCEVSQ6C2EXAMPLE,
"username": "your_snowflake_username",
"auth_code": "authorizationcode"
}
```
**必要欄位**
+ `redirect_uri` – 您從步驟 1 取得的 OAuth 重新導向 URI。
+ `client_secret` – 您從步驟 2 取得的 OAuth 用戶端秘密。
+ `token_url` – Snowflake OAuth 權杖端點。
+ `client_id` – 從步驟 2 取得的 OAuth 用戶端 ID。
+ `username` – 連接器的 Snowflake 使用者名稱。
+ `auth_code` – 您從步驟 3 取得的授權碼。
建立秘密後，您即會取得秘密 ARN，並且您可以在[建立資料來源連線](connect-to-a-data-source.md)時，於 Glue 連線中使用該 ARN。
## 傳遞查詢
Snowflake 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Snowflake 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Snowflake 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Snowflake 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-snowflake)。
# Amazon Athena Microsoft SQL Server 連接器
適用於 [Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/?view=sql-server-ver15) 的 Amazon Athena 連接器可讓 Amazon Athena 使用 JDBC 對存放在 Microsoft SQL Server 中的資料執行 SQL 查詢。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 在篩選條件中，您必須將 `Date` 和 `Timestamp` 資料類型轉換為適當的資料類型。
+ 若要搜尋類型 `Real` 和 `Float` 的負值，請使用 `<=` 或者 `>=` 運算子。
+ 不支援 `binary`、`varbinary`、`image`、和 `rowversion` 資料類型。
## 條款
下列術語與 SQL Server 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 SQL Server 連接器。為此，請將 SQL Server 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type SQLSERVER
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 SQL Server 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 SQL Server 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
sqlserver://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | SqlServerMuxCompositeHandler |
| 中繼資料處理常式 | SqlServerMuxMetadataHandler |
| 記錄處理常式 | SqlServerMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mysqlservercatalog，則環境變數名稱為 mysqlservercatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 SqlServer MUX Lambda 函數：`sqlserver1` (預設) 和 `sqlserver2`。
****
| 屬性 | Value |
| --- | --- |
| default | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 |
| sqlserver\$1catalog1\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 |
| sqlserver\$1catalog2\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver2.hostname:port;databaseName=;\$1\$1secret2\$1name\$1 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 `${secret_name}`。
```
sqlserver://jdbc:sqlserver://hostname:port;databaseName=;${secret_name}
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
sqlserver://jdbc:sqlserver://hostname:port;databaseName=;user=;password=
```
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 SQL Server 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | SqlServerCompositeHandler |
| 中繼資料處理常式 | SqlServerMetadataHandler |
| 記錄處理常式 | SqlServerRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數所支援的單一 SQL Server 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | sqlserver://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 SQL Server 和 Apache Arrow 的相應資料類型。
****
| SQL Server | Arrow |
| --- | --- |
| 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 | Date(DAY) |
| time | VARCHAR |
| datetimeoffset | Date(MILLISECOND) |
| char[n] | VARCHAR |
| varchar[n/max] | VARCHAR |
| nchar[n] | VARCHAR |
| nvarchar[n/max] | VARCHAR |
| text | VARCHAR |
| ntext | VARCHAR |
## 分割區和分隔
分割區由 `varchar` 類型的單一分割區資料欄表示。如果是 SQL Server 連接器，分割區函數會決定在資料表上套用分割區的方式。從 SQL Server 中繼資料表中擷取分割區函數和資料欄名稱資訊。然後，自訂查詢可獲取分割區。根據收到的不同分割區數目建立分割。
## 效能
選取資料欄子集可大幅加速查詢執行期，並減少掃描的資料。SQL Server 連接器由於並行而對限流保有彈性。
Athena SQL Server 連接器執行述詞下推，以減少查詢掃描的資料。簡單述詞和複雜表達式會下推至連接器，以減少掃描的資料量並減少查詢執行時間。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。 Athena SQL Server 連接器可以合併這些表達式，並將其直接推送至 SQL Server，以增強功能並減少掃描的資料量。
下列 Athena SQL Server 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## 傳遞查詢
SQL Server 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 SQL Server 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 SQL Server 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 SQL Server 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-sqlserver)。
# Amazon Athena Teradata 連接器
適用於 Teradata 的 Amazon Athena 連接器可讓 Athena 對存放在 Teradata 資料庫中的資料執行 SQL 查詢。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## 限制
+ 不支援寫入 DDL 操作。
+ 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
## 條款
下列術語與 Teradata 連接器相關。
+ **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
+ **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。
## Parameters
使用本節中的參數來設定 Teradata 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Teradata 連接器。為此，請將 Teradata 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type TERADATA
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Teradata 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Teradata 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
teradata://${jdbc_connection_string}
```
#### 使用多工處理常式
您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。
****
| 處理常式 | 類別 |
| --- | --- |
| 複合處理常式 | TeradataMuxCompositeHandler |
| 中繼資料處理常式 | TeradataMuxMetadataHandler |
| 記錄處理常式 | TeradataMuxRecordHandler |
##### 多工處理常式參數
****
| 參數 | Description |
| --- | --- |
| \$1catalog\$1connection\$1string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 myteradatacatalog，則環境變數名稱為 myteradatacatalog\$1connection\$1string。 |
| default | 必要. 預設的連接字串。目錄為 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 時，使用此字串。 |
下列範例屬性適用於支援兩個資料庫執行個體的 Teradata MUX Lambda 函數：`teradata1` (預設) 和 `teradata2`。
****
| 屬性 | Value |
| --- | --- |
| default | teradata://jdbc:teradata://teradata2.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,user=sample2&password=sample2 |
| teradata\$1catalog1\$1connection\$1string | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,\$1\$1Test/RDS/Teradata1\$1 |
| teradata\$1catalog2\$1connection\$1string | teradata://jdbc:teradata://teradata2.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,user=sample2&password=sample2 |
##### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 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 屬性。它也接受格式為 *username*`/`*password* 的使用者名稱和密碼，而不使用金鑰 `user` 或 `password`。
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Teradata 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | TeradataCompositeHandler |
| 中繼資料處理常式 | TeradataMetadataHandler |
| 記錄處理常式 | TeradataRecordHandler |
##### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
下列範例屬性適用於 Lambda 函數支援的單一 Teradata 執行個體。
****
| 屬性 | Value |
| --- | --- |
| default | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,secret=Test/RDS/Teradata1 |
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 JDBC 和 Apache Arrow 的相應資料類型。
****
| JDBC | Arrow |
| --- | --- |
| Boolean | 位元 |
| Integer | Tiny |
| Short | Smallint |
| Integer | Int |
| Long | Bigint |
| float | Float4 |
| Double | Float8 |
| Date | DateDay |
| 時間戳記 | DateMilli |
| String | Varchar |
| 位元組 | Varbinary |
| BigDecimal | Decimal (小數) |
| ARRAY | 清單 |
## 分割區和分隔
分割區由 `Integer` 類型的單一分割區資料欄表示。此資料欄包含 Teradata 資料表中所定義之分割區的分割區名稱。對於沒有分割區名稱的資料表，會傳回 \$1，這相當於一個單一的分割區。分割區等同於分隔。
****
| 名稱 | 類型 | 說明 |
| --- | --- | --- |
| 分割區 | Integer | Teradata 中的已命名分割區。 |
## 效能
Teradata 支援原生分割區。Athena Teradata 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大的資料集，強烈建議使用原生分割。選取資料欄子集會大幅拖慢查詢執行時間。連接器會顯示因為並行而導致的部分限流。
Athena Teradata 連接器執行述詞下推，以減少查詢掃描的資料。簡單述詞和複雜表達式會下推至連接器，以減少掃描的資料量並減少查詢執行時間。
### 述詞
述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Teradata 連接器可以合併這些表達式，並將其直接推送至 Teradata，以增強功能並減少掃描的資料量。
下列 Athena Teradata 連接器運算子支援述詞下推：
+ **布林值：**AND、OR、NOT
+ **等式：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL
+ **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN
### 合併下推範例
如需增強的查詢功能，請合併下推類型，如以下範例所示：
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## 傳遞查詢
Teradata 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Teradata 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Teradata 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Teradata 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/pom.xml) 檔案。
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-teradata)。
# Amazon Athena Timestream 連接器
Amazon Athena Timestream 連接器讓 Amazon Athena 能夠與 [Amazon Timestream](https://aws.amazon.com/timestream/) 進行通訊，從而可透過 Amazon Athena 存取您的時間序列資料。您可以選擇使用 AWS Glue Data Catalog 作為補充中繼資料的來源。
Amazon Timestream 是快速、可擴展、全受管、專門打造的時間序列資料庫，可讓您每天輕鬆存放和分析數兆個時間序列資料點。Timestream 會將最近的資料保存在記憶體中，並根據使用者定義的政策將歷史資料移到成本最佳化的儲存層，藉此節省您管理時間序列資料生命週期的時間和成本。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
如果您的 帳戶中已啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## Parameters
使用本節中的參數來設定 Timestream 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Timestream 連接器。為此，請將 Timestream 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type TIMESTREAM
```
**Lambda 環境屬性**
**glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Timestream 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Timestream 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
**注意**
2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。
下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `glue_connection` 環境屬性時，才會使用下列參數。
**Lambda 環境屬性**
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **glue\$1catalog** - (選用) 使用此選項可指定[跨帳戶 AWS Glue 目錄](data-sources-glue-cross-account.md)。根據預設，連接器會嘗試從自己的 AWS Glue 帳戶取得中繼資料。
## 在 中設定資料庫和資料表 AWS Glue
您可以選擇使用 AWS Glue Data Catalog 作為補充中繼資料的來源。若要啟用 AWS Glue 資料表以與 Timestream 搭配使用，您必須擁有 AWS Glue 資料庫和資料表，其名稱符合您要為其提供補充中繼資料的 Timestream 資料庫和資料表。
**注意**
為了獲得最佳效能，請僅使用小寫作為資料庫名稱和資料表名稱。使用混合大小寫會導致連接器執行運算密集程度較高的不區分大小寫搜尋。
若要設定 AWS Glue 資料表以搭配 Timestream 使用，您必須在 中設定其資料表屬性 AWS Glue。
**使用 AWS Glue 資料表補充中繼資料**
1. 在 AWS Glue 主控台中編輯資料表，以新增下列資料表屬性：
+ **timestream-metadata-flag** - 此屬性向 Timestream 連接器發出指示，連接器可使用資料表作為補充中繼資料。您可以為 `timestream-metadata-flag` 提供任何值，只要 `timestream-metadata-flag` 屬性存在於資料表屬性清單中。
+ **\$1view\$1template** - 當您使用 AWS Glue 作為補充中繼資料時，可以使用此資料表屬性，並指定任何 Timestream SQL 作為檢視。Athena Timestream 連接器會使用檢視中的 SQL 以及 Athena 中的 SQL 來執行查詢。如果您想要使用 Athena 中沒有的 Timestream SQL 功能，這會非常有用。
1. 請確定您使用適用於本文件 AWS Glue 所列 的資料類型。
### 資料類型
目前，Timestream 連接器僅支援 Timestream 中部份的可用資料類型，尤其是：純量值 `varchar`、`double` 和 `timestamp`。
若要查詢 `timeseries` 資料類型，您必須在 AWS Glue 資料表屬性中設定一個使用 Timestream `CREATE_TIME_SERIES` 函數的檢視。您還需要為檢視提供結構描述，它使用語法 `ARRAY>` 作為任何時間序列欄的類型。請務必將 `double` 取代為適合您的資料表的純量類型。
下圖顯示設定為在時間序列中設定檢視的 AWS Glue 資料表屬性範例。
![\[在 中設定資料表屬性 AWS Glue ，以設定時間序列的檢視。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connectors-timestream-1.png)
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-timestream.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-timestream/athena-timestream.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
+ **AWS Glue Data Catalog** – Timestream 連接器需要對 的唯讀存取權 AWS Glue Data Catalog ，才能取得結構描述資訊。
+ **CloudWatch Logs** - 連接器需要存取 CloudWatch Logs 以儲存日誌。
+ **Timestream Access** - 用於執行 Timestream 查詢。
## 效能
建議您使用 `LIMIT` 子句將傳回的資料 (非掃描的資料) 限制在 256 MB 以下，以確保互動式查詢效能良好。
Athena Timestream 連接器執行述詞下推，以減少查詢掃描的資料。`LIMIT` 子句可減少掃描的資料量，但是如果未提供述詞，則應預期含有 `LIMIT` 子句的 `SELECT` 查詢可掃描至少 16 MB 的資料。選取資料欄子集可大幅加速查詢執行時間，並減少掃描的資料。Timestream 連接器由於並行而對限流保有彈性。
## 傳遞查詢
Timestream 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Timestream 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Timestream 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
Amazon Athena Timestream 連接器專案是依據 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) 來授權的。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-timestream)。
# Amazon Athena TPC benchmark DS (TPC-DS) 連接器
Amazon Athena TPC-DS 連接器讓 Amazon Athena 能夠與隨機產生的 TPC Benchmark DS 資料來源通訊，以用於 Athena Federation 的基準化分析和功能測試。Athena TPC-DS 連接器會以四種縮放比例之一產生符合 TPC-DS 規範的資料庫。我們不建議使用此連接器作為 Amazon S3 資料湖效能測試的替代方案。
此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
## Parameters
使用本節中的參數來設定 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 日開始，只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器時，才會使用下列參數。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 TPC-DS 連接器。為此，請將 TPC-DS 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type TPCDS
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 TPC-DS 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 TPC-DS 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
+ **spill\$1bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。
+ **spill\$1prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
## 測試資料庫和資料表
Athena TPC-DS 連接器會以四種縮放比例 (`tpcds1`、`tpcds10`、`tpcds100`、`tpcds250` 或 `tpcds1000`) 之一產生符合 TPC-DS 規範的資料庫。
### 資料表摘要
如需測試資料表和資料欄的完整清單，請執行 `SHOW TABLES` 或者 `DESCRIBE TABLE` 查詢。為了方便起見，提供以下資料表摘要。
1. call\$1center
1. catalog\$1page
1. catalog\$1returns
1. catalog\$1sales
1. customer
1. customer\$1address
1. customer\$1demographics
1. date\$1dim
1. dbgen\$1version
1. household\$1demographics
1. income\$1band
1. 庫存
1. item
1. promotion
1. reason
1. ship\$1mode
1. 存放
1. store\$1returns
1. store\$1sales
1. time\$1dim
1. warehouse
1. web\$1page
1. web\$1returns
1. web\$1sales
1. web\$1site
如需與此產生的結構描述和資料相容的 TPC-DS 查詢，請參閱 GitHub 上的 [athena-tpcds/src/main/resources/queries/](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds/src/main/resources/queries) 目錄。
### 查詢範例
下列 `SELECT` 查詢範例會查詢特定郡的客戶人口統計的 `tpcds` 目錄。
```
SELECT
cd_gender,
cd_marital_status,
cd_education_status,
count(*) cnt1,
cd_purchase_estimate,
count(*) cnt2,
cd_credit_rating,
count(*) cnt3,
cd_dep_count,
count(*) cnt4,
cd_dep_employed_count,
count(*) cnt5,
cd_dep_college_count,
count(*) cnt6
FROM
"lambda:tpcds".tpcds1.customer c, "lambda:tpcds".tpcds1.customer_address ca, "lambda:tpcds".tpcds1.customer_demographics
WHERE
c.c_current_addr_sk = ca.ca_address_sk AND
ca_county IN ('Rush County', 'Toole County', 'Jefferson County',
'Dona Ana County', 'La Porte County') AND
cd_demo_sk = c.c_current_cdemo_sk AND
exists(SELECT *
FROM "lambda:tpcds".tpcds1.store_sales, "lambda:tpcds".tpcds1.date_dim
WHERE c.c_customer_sk = ss_customer_sk AND
ss_sold_date_sk = d_date_sk AND
d_year = 2002 AND
d_moy BETWEEN 1 AND 1 + 3) AND
(exists(SELECT *
FROM "lambda:tpcds".tpcds1.web_sales, "lambda:tpcds".tpcds1.date_dim
WHERE c.c_customer_sk = ws_bill_customer_sk AND
ws_sold_date_sk = d_date_sk AND
d_year = 2002 AND
d_moy BETWEEN 1 AND 1 + 3) OR
exists(SELECT *
FROM "lambda:tpcds".tpcds1.catalog_sales, "lambda:tpcds".tpcds1.date_dim
WHERE c.c_customer_sk = cs_ship_customer_sk AND
cs_sold_date_sk = d_date_sk AND
d_year = 2002 AND
d_moy BETWEEN 1 AND 1 + 3))
GROUP BY cd_gender,
cd_marital_status,
cd_education_status,
cd_purchase_estimate,
cd_credit_rating,
cd_dep_count,
cd_dep_employed_count,
cd_dep_college_count
ORDER BY cd_gender,
cd_marital_status,
cd_education_status,
cd_purchase_estimate,
cd_credit_rating,
cd_dep_count,
cd_dep_employed_count,
cd_dep_college_count
LIMIT 100
```
## 所需的許可
如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-tpcds.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-tpcds/athena-tpcds.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此許可快速失敗。
## 效能
Athena TPC-DS 連接器會嘗試根據您選擇的比例因數平行處理查詢。在 Lambda 函數內執行述詞下推。
## 授權資訊
Amazon Athena TPC-DS 連接器專案是依據 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) 來授權的。
## 其他資源
如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds)。
# Amazon Athena Vertica 連接器
Vertica 是一種單欄式資料庫平台，可部署在雲端或進行內部部署，以支援 Exabyte 艾位元組規模的資料倉儲。您可以在聯合查詢中使用 Amazon Athena Vertica 連接器，查詢來自 Athena 的 Vertica 資料來源。例如，您可以在 Vertica 上的資料倉儲和 Simple Storage Service (Amazon S3) 中的資料湖上執行分析查詢。
此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。
## 先決條件
+ 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。
+ 您必須先設定 VPC 和安全群組，才能使用此連接器。如需詳細資訊，請參閱[為資料來源連接器或 AWS Glue 連線建立 VPC](athena-connectors-vpc-creation.md)。
## 限制
+ 因為 Athena Vertica 連接器會從 Amazon S3 中讀取已匯出的 Parquet 檔案，所以連接器的效能可能會很慢。查詢大型資料表時，建議您使用 [CREATE TABLE AS (SELECT ...) ](ctas.md)查詢和 SQL 述詞。
+ 目前，由於 Athena Federated Query 中存在已知問題，連接器會讓 Vertica 將已查詢資料表的所有資料欄匯出至 Amazon S3，但在 Athena 主控台的結果中只能看到已查詢的資料欄。
+ 不支援寫入 DDL 操作。
+ 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
## 工作流程
下圖顯示使用 Vertica 連接器的查詢工作流程。
![\[來自 Amazon Athena 的 Vertica 查詢工作流程\]](http://docs.aws.amazon.com/zh_tw/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 函式發出多個呼叫並使用 Apache `ArrowReader` 從結果資料集中讀取 Parquet 檔案。多個呼叫可讓 Athena 平行讀取 Amazon S3 檔案，並達到每秒高達 100GB 的輸送量。
1. Athena 會使用從資料湖掃描的資料來處理從 Vertica 傳回的資料，並傳回結果。
## 條款
下列術語與 Vertica 連接器相關。
+ **資料庫執行個體** - 部署在 Amazon EC2 上的 Vertica 資料庫的任何執行個體。
+ **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。
+ **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。
+ **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。
+ **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。
+ **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。
+ **連接字串** - 用來建立資料庫執行個體連線的文字字串。
+ **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。
## Parameters
使用本節中的參數來設定 Vertica 連接器。
### Glue 連線 (建議)
我們建議您使用 Glue 連線物件來設定 Vertica 連接器。為此，請將 Vertica 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。
**Glue 連線屬性**
使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。
```
aws glue describe-connection-type --connection-type VERTICA
```
**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。
+ **casing\$1mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為：
+ **none** – 請勿變更指定的結構描述和資料表名稱的大小寫。這是具有關聯 Glue 連線的連接器的預設值。
+ **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。
+ **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。
**注意**
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 Vertica 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 Vertica 連接器僅支援 `ConnectionSchemaVersion` 2。
### 舊版連線
Amazon Athena Vertica 連接器透過 Lambda 環境變數公開組態選項。您可以使用下列 Lambda 環境變數來設定連接器。
+ **AthenaCatalogName** - Lambda 函數名稱
+ **ExportBucket** - 匯出 Vertica 查詢結果的 Amazon S3 儲存貯體。
+ **SpillBucket** - 此函數可在其中溢出資料的 Amazon S3 儲存貯體的名稱。
+ **SpillPrefix** - 此函數可在其中溢出資料的 `SpillBucket` 位置的字首。
+ **SecurityGroupIds** - 一個或多個 ID，其對應於應套用至 Lambda 函數的安全群組 (例如，`sg1`、`sg2` 或 `sg3`)。
+ **SubnetIds** - 一個或多個子網 ID，其對應於 Lambda 函數可用來存取資料來源的子網 (例如，`subnet1` 或 `subnet2`)。
+ **SecretNameOrPrefix** - 此函數可以存取的 Secrets Manager 中的一組名稱的名稱或字首 (例如，`vertica-*`)
+ **VerticaConnectionString** - 如果未定義目錄特定連接，預設會使用 Vertica 連接詳細資訊。字串可以選擇性地使用語法 AWS Secrets Manager （例如 `${secret_name}`)。
+ **VPC ID** - 連接至 Lambda 函數的 VPC ID。
#### 連接字串
使用下列格式的 JDBC 連接字串來連接資料庫執行個體。
```
vertica://jdbc:vertica://host_name:
port/database?user=vertica-username&password=
vertica-password
```
#### 使用單一連接處理常式
您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Vertica 執行個體。
****
| 處理常式類型 | 類別 |
| --- | --- |
| 複合處理常式 | VerticaCompositeHandler |
| 中繼資料處理常式 | VerticaMetadataHandler |
| 記錄處理常式 | VerticaRecordHandler |
#### 單一連接處理常式參數
****
| 參數 | Description |
| --- | --- |
| default | 必要. 預設的連接字串。 |
單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。
#### 提供憑證
要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。
+ **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。
**重要**
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。
+ **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。
您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。
對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：
```
{"username": "${username}", "password": "${password}"}
```
**帶有秘密名稱的連接字串範例**
以下字串具有秘密名稱 \$1\$1`vertica-username`\$1 和 `${vertica-password}`。
```
vertica://jdbc:vertica://
host_name:port/database?user=${vertica-username}&password=${vertica-password}
```
連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。
```
vertica://jdbc:vertica://
host_name:port/database?user=sample-user&password=sample-password
```
目前，Vertica 連接器可辨識 `vertica-username` 和 `vertica-password` JDBC 屬性。
#### 溢出參數
Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。
****
| 參數 | Description |
| --- | --- |
| 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 參考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 |
## 支援的資料類型
下表顯示 Vertica 連接器支援的資料類型。
****
| Boolean |
| --- |
| BigInt |
| Short |
| Integer |
| Long |
| Float |
| Double |
| Date |
| Varchar |
| 位元組 |
| BigDecimal |
| TimeStamp as Varchar |
## 效能
Lambda 函式執行投影下推，以減少查詢掃描的資料。`LIMIT` 子句可減少掃描的資料量，但是如果未提供述詞，則應預期含有 `LIMIT` 子句的 `SELECT` 查詢可掃描至少 16 MB 的資料。Vertica 連接器由於並行而對限流保有彈性。
## 傳遞查詢
Vertica 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。
若要透過 Vertica 使用傳遞查詢，您可以使用下列語法：
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
下列範例查詢會將查詢下推到 Vertica 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄，並將結果限制為 10。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## 授權資訊
使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。
## 其他資源
如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Vertica 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) 檔案。
如需有關此連接器的其他資訊，請參閱 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-vertica)，以及 *AWS 大數據部落格*中的[使用 Athena 聯合查詢 SDK 在 Amazon Athena 中查詢 Vertica 資料來源](https://aws.amazon.com/blogs/big-data/querying-a-vertica-data-source-in-amazon-athena-using-the-athena-federated-query-sdk/)。