Amazon Athena OpenSearch 連接器 - Amazon Athena
先決條件條款參數在 中設定資料庫和資料表 AWS Glue執行 SQL 查詢效能傳遞查詢其他資源

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Amazon Athena OpenSearch 連接器

OpenSearch Service

Amazon Athena OpenSearch 連接器讓 Amazon Athena 能夠與您的 OpenSearch 執行個體通訊，以便使用 SQL 來查詢您的 OpenSearch 資料。

此連接器無法向 Glue Data Catalog 註冊為聯合型目錄。此連接器不支援 Lake Formation 中在目錄、資料庫、資料表、資料欄、資料列和標籤層級定義的資料存取控制。此連接器使用 Glue Connections 來集中 Glue 中的組態屬性。

注意

由於已知問題，OpenSearch 連接器不能與 VPC 搭配使用。

如果您在帳戶中啟用 Lake Formation，則您在 中部署的 Athena 聯合 Lambda 連接器的 IAM 角色 AWS Serverless Application Repository 必須在 Lake Formation 中具有對 的讀取存取權 AWS Glue Data Catalog。

先決條件

條款

下列術語與 OpenSearch 連接器相關。

  • 網域 - 此連接器與 OpenSearch 執行個體的端點相關聯的名稱。該網域也用作資料庫名稱。對於 Amazon OpenSearch Service 中定義的 OpenSearch 執行個體，可自動探索網域。對於其他執行個體，您必須提供網域名稱和端點之間的映射。

  • 索引 - 在您的 OpenSearch 執行個體中定義的資料庫資料表。

  • 映射 - 如果索引是資料庫資料表，則映射為其結構描述 (亦即其欄位和屬性的定義)。

    此連接器支援從 OpenSearch 執行個體和 AWS Glue Data Catalog中擷取中繼資料。如果連接器找到符合您 OpenSearch 網域和索引名稱的 AWS Glue 資料庫和資料表，連接器會嘗試使用這些資料庫和資料表進行結構描述定義。我們建議您建立 AWS Glue 資料表，使其成為 OpenSearch 索引中所有欄位的超集合。

  • 文件 - 資料庫資料表中的記錄。

  • 資料串流 – 由多個後備索引組成的以時間為基礎的資料料。如需詳細資訊，請參閱 OpenSearch 文件中的資料串流和《Amazon OpenSearch Service 開發人員指南》中的資料串流入門。

    注意

    由於資料串流索引是透過開放式搜尋在內部建立和管理的，因此連接器會從第一個可用索引中選擇結構描述映射。因此，強烈建議將 AWS Glue 資料表設定為補充中繼資料來源。如需詳細資訊，請參閱在 中設定資料庫和資料表 AWS Glue。

參數

使用本節中的參數來設定 OpenSearch 連接器。

注意

Athena 資料來源連接器於 2024 年 12 月 3 日及之後建立，使用 AWS Glue 連線。

下列參數名稱和定義適用於 2024 年 12 月 3 日之前建立的 Athena 資料來源連接器。這些可能與其對應的AWS Glue 連線屬性不同。自 2024 年 12 月 3 日起，只有在您手動部署舊版 Athena 資料來源連接器時，才能使用下列參數。

  • spill_bucket - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。

  • spill_prefix - (選用) 預設為指定的 spill_bucket 中名為 athena-federation-spill 的子資料夾。我們建議您在此位置設定 Amazon S3 儲存生命週期，以刪除超過預定天數或小時數的溢出。

  • spill_put_request_headers – (選用) 用於溢出的 Amazon S3 putObject 請求的請求標頭和值的 JSON 編碼映射 (例如，{"x-amz-server-side-encryption" : "AES256"})。如需了解其他可能的標頭，請參閱《Amazon Simple Storage Service API 參考》中的 PutObject。

  • 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 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用伺服器端加密。

  • 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中擷取的使用者名稱和密碼來插入替代字串。運算式結尾的冒號 (:) 可做為端點其餘部分的分隔符號。

    重要

    作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱AWS Secrets Manager 《 使用者指南》中的將硬式編碼秘密移至 AWS Secrets Manager 。

    下列範例使用 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 中定義陣列的中繼資料 一節)。 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 執行個體擷取的叢集運作狀態資訊，為文件搜尋查詢產生多個請求。會針對每個碎片分割請求並同時執行。

連接器也會下推述詞，作為其文件搜尋查詢的一部分。下列範例查詢和述詞顯示連接器如何使用述詞下推。

查詢

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 連接器支援傳遞查詢，並使用查詢 DSL 語言。如需查詢 DSL 的詳細資訊，請參閱 Elasticsearch 文件中的查詢 DSL，或 OpenSearch 文件中的查詢 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''}}}}"
        ))

其他資源