先決條件條款參數在 AWS Glue 中設定資料庫和資料表執行 SQL 查詢效能另請參閱

Amazon Athena OpenSearch 連接器

OpenSearch Service

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

注意

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

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

先決條件

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

條款

下列術語與 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 中設定資料庫和資料表。

參數

使用本節中的 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 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 進行身分驗證。否則，連接器會透過 domain_mapping 變數從 AWS Secrets Manager 中擷取使用者名稱和密碼憑證。
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	字串
長整數	BIGINT	bigint
scaled_float	BIGINT	SCALED_FLOAT(...)
integer	INT	int
short	SMALLINT	smallint
byte	TINYINT	tinyint
double	FLOAT8	double
float, half_float	FLOAT4	float
布林值	BIT	布林值
date, date_nanos	DATEMILLI	timestamp
JSON 結構	STRUCT	STRUCT
_meta (如需詳細資訊，請參閱在 OpenSearch 中定義陣列的中繼資料一節)。	LIST	ARRAY

資料類型的注意事項

目前，連接器僅支援前面的表格中列出的 OpenSearch 和 AWS Glue 資料類型。
scaled_float 是由固定雙精度比例係數調整的浮點數，在 Apache Arrow 中表示為 BIGINT。例如，若比例係數為 100，則 0.756 會四捨五入為 76。
若要在 AWS Glue 中定義 scaled_float，您必須選取 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)

另請參閱

如需有關使用 Amazon Athena OpenSearch 連接器在單一查詢中查詢 Amazon OpenSearch Service 和 Amazon S3 中的資料的文章，請參閱 AWS 大數據部落格中的使用 Amazon Athena 的 SQL 查詢 Amazon OpenSearch Service 中的資料。
如需此連接器的其他資訊，請造訪 GitHub.com 上的相應網站。

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

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

文件慣用形式

Neptune

Oracle