必要條件條款參數設定資料庫和資料表 AWS Glue 執行 SQL 查詢效能直通查詢其他資源

Amazon Athena OpenSearch 連

OpenSearch 服務

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

注意

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

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

必要條件

使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶。如需詳細資訊，請參閱部署資料來源連接器或使用 AWS Serverless Application Repository 部署資料來源連接器。

條款

下列與 OpenSearch 連接器有關的術語。

網域 — 此連接器與執行個體端點關聯的名 OpenSearch 稱。該網域也用作資料庫名稱。對於 OpenSearch Amazon OpenSearch 服務中定義的執行個體，該網域是可自動探索的。對於其他執行個體，您必須提供網域名稱和端點之間的映射。
Index — 在 OpenSearch 執行個體中定義的資料庫表格。
映射 - 如果索引是資料庫資料表，則映射為其結構描述 (亦即其欄位和屬性的定義)。

此連接器支援從執行個 OpenSearch 體和從中擷取中繼資料 AWS Glue Data Catalog。如果連接器找到與您的 OpenSearch 網域和索引名稱相符的 AWS Glue 資料庫和資料表，則連接器會嘗試將它們用於結構描述定義。我們建議您建立 AWS Glue 資料表，使其成為 OpenSearch 索引中所有欄位的超集合。
文件 - 資料庫資料表中的記錄。
資料串流 – 由多個後備索引組成的以時間為基礎的資料料。如需詳細資訊，請參閱 OpenSearch 文件中的資料串流和 Amazon Ser OpenSearch vice 開發人員指南中的資料串流入門。

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

參數

使用本節中的 Lambda 環境變數來設定 OpenSearch 連接器。

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 簡單儲存服務 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 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用伺服器端加密。
disabled le_glue — (選擇性) 如果存在且設定為 true，則連接器不會嘗試從中擷取補充中繼資料。 AWS Glue
query_timeout_cluster - 產生平行掃描時使用的叢集運作狀態查詢的逾時時間 (以秒為單位)。
query_timeout_search - 從索引中擷取文件時使用的搜尋查詢的逾時時間 (以秒為單位)。
auto_discover_endpoint - 布林值。預設值為 true。當您使用 Amazon OpenSearch 服務並將此參數設定為 true 時，連接器可以透過在服 OpenSearch 務上呼叫適當的描述或列出 API 操作來自動探索您的網域和端點。對於任何其他類型的 OpenSearch 執行個體 (例如，自我託管)，您必須在domain_mapping變數中指定關聯的網域端點。如果auto_discover_endpoint=true，連接器會使用 AWS 認證向 OpenSearch 服務進行驗證。否則，連接器會 AWS Secrets Manager 透過domain_mapping變數擷取使用者名稱和密碼認證。
domain_mapping - 僅在 auto_discover_endpoint 設定為 false 並定義網域名稱與其關聯端點之間的映射時使用。此domain_mapping變數可以容納下列格式的多個 OpenSearch端點：
```
domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,...       
```
為了向 OpenSearch 端點進行驗證，連接器支援使用從中 AWS Secrets Manager擷取的使用者名稱和密碼${SecretName}:的格式插入的替代字串。運算式結尾的冒號 (:) 可做為端點其餘部分的分隔符號。

重要
作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼密碼移至的資訊 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 (縮放係數) 格式宣告欄位。

以下範例有效：
```
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)
```
A 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 連接器支援以碎片為基礎的 parallel 掃描。連接器會使用從 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 或文件中的查詢 DS L。 OpenSearch

若要將傳遞查詢與 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 服務和 Amazon S3 中的資料的文章，請參閱AWS 大數據部落格中的使用亞馬遜 Athena 的 SQL 查詢亞馬遜 OpenSearch 服務中的資料。
如需有關此連接器的其他資訊，請造訪 GitHub .com 上的對應網站。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Neptune

Oracle