本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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 資料來源連接器時，才會使用下列參數。 ### AWS Glue Data Catalog 聯合連接器 我們建議您使用 Glue 連線物件來設定 OpenSearch 連接器。為此，請將 OpenSearch 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。 **Glue 連線屬性** 使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。 ``` aws glue describe-connection-type --connection-type OPENSEARCH ``` **Lambda 環境屬性** 下列 Lambda 環境屬性僅適用於在帳戶中搭配 Lambda 函數使用連接器時。 + **glue\_connection** – 指定與聯合連接器關聯的 Glue 連線名稱。 **注意** 使用聯合連線的所有連接器都必須使用 AWS Glue Data Catalog AWS Secrets Manager 來存放登入資料。 使用 AWS Glue Data Catalog 聯合連線建立的 OpenSearch 連接器不支援使用多工處理常式。 使用 AWS Glue Data Catalog 聯合連線建立的 OpenSearch 連接器僅支援 `ConnectionSchemaVersion` 2。 ### Athena 資料目錄聯合連接器 + **spill\_bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。 + **spill\_prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 Amazon S3 [儲存生命週期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)，以刪除超過預定天數或小時數的溢出。 + **spill\_put\_request\_headers** – (選用) 用於溢出的 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\_key\_id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。 + **disable\_spill\_encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。 + **disable\_glue** – （選用） 如果存在並設為 true，連接器不會嘗試從中擷取補充中繼資料 AWS Glue。 + **query\_timeout\_cluster** - 產生平行掃描時使用的叢集運作狀態查詢的逾時時間 (以秒為單位)。 + **query\_timeout\_search** - 從索引中擷取文件時使用的搜尋查詢的逾時時間 (以秒為單位)。 + **auto\_discover\_endpoint** - 布林值。預設值為 `true`。當您使用 Amazon OpenSearch Service 並將此參數設定為 true 時，連接器可以透過在 OpenSearch 服務上呼叫適當的描述或清單 API 操作來自動探索您的網域和端點。對於任何其他類型的 OpenSearch 執行個體 (例如，自助託管)，您必須在 `domain_mapping` 變數中指定相關聯的網域端點。如果 `auto_discover_endpoint=true`，連接器會使用 AWS 憑證向 OpenSearch Service 進行身分驗證。否則，連接器 AWS Secrets Manager 會透過 `domain_mapping`變數從 擷取使用者名稱和密碼登入資料。 + **domain\_mapping** - 僅在 `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\_name}}@{{password}} 格式。雖然密碼可能包含內嵌式 `@` 符號，但第一個 `@` 用作 {{user\_name}} 的分隔符號。 還需要注意的是，此連接器使用逗號 (,) 和等號 (=) 作為網域端點對的分隔符號。因此，您不應該在儲存的秘密中的任何位置使用它們。 ## 在 中設定資料庫和資料表 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\_float | BIGINT | SCALED\_FLOAT(...) | | integer | INT | int | | short | SMALLINT | smallint | | byte | TINYINT | tinyint | | double | FLOAT8 | double | | float, half\_float | FLOAT4 | float | | boolean | BIT | boolean | | date, date\_nanos | DATEMILLI | timestamp | | JSON 結構 | STRUCT | STRUCT | | \_meta (如需詳細資訊，請參閱 [在 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\_FLOAT({{scaling\_factor}}) 格式宣告欄位。 以下範例有效： ``` 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\_name}} 對應於 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)。