先决条件术语参数在 Amazon Glue 中设置数据库和表运行 SQL 查询性能另请参阅

Amazon Athena OpenSearch 连接器

OpenSearch Service

Amazon Athena OpenSearch 连接器使 Amazon Athena 能够与您的 OpenSearch 实例进行通信，以便您可以使用 SQL 查询您的 OpenSearch 数据。

注意

由于存在已知问题，OpenSearch 连接器无法与 VPC 一起使用。

如果您在账户中启用了 Lake Formation，则您在 Amazon Serverless Application Repository 中部署的 Athena 联合身份 Lambda 连接器的 IAM 角色必须在 Lake Formation 中具有 Amazon Glue Data Catalog 的读取权限。

先决条件

可以使用 Athena 控制台或 Amazon Serverless Application Repository 将该连接器部署到您的 Amazon Web Services 账户。有关更多信息，请参阅部署数据来源连接器或使用 Amazon Serverless Application Repository 部署数据源连接器。

术语

以下术语与 OpenSearch 连接器有关。

域 - 此连接器与 OpenSearch 实例的端点关联的名称。域也用作数据库名称。对于在 Amazon OpenSearch Service 中定义的 OpenSearch 实例，域是可自动发现的。对于其他实例，您必须提供域名和端点之间的映射。
索引 - 在 OpenSearch 实例中定义的数据库表。
映射 - 如果索引是数据库表，则映射是其架构（即其字段和属性的定义）。

此连接器同时支持从 OpenSearch 实例和从 Amazon Glue Data Catalog 检索元数据。如果该连接器找到与您的 OpenSearch 域名和索引名称相匹配的 Amazon Glue 数据库和表，该连接器会尝试使用它们进行架构定义。我们建议您创建 Amazon Glue 表，这样该表就是 OpenSearch 索引中所有字段的超集。
文档 - 数据库表中的记录。
数据流 - 基于时间的数据，由多个后备索引组成。有关更多信息，请参阅 OpenSearch 文档中的数据流和《Amazon OpenSearch Service 开发人员指南》中的数据流入门。

注意
由于数据流索引在内部创建并通过开放搜索进行管理，因此连接器会从第一个可用索引中选择架构映射。因此，我们强烈建议将 Amazon Glue 表设置为补充元数据源。有关更多信息，请参阅在 Amazon 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 -（可选）默认情况下，将使用经过 AES-GCM 身份验证的加密模式和随机生成的密钥对溢出到 Amazon S3 的任何数据进行加密。要让您的 Lambda 函数使用 KMS 生成的更强的加密密钥（如 a7e63k4b-8loc-40db-a2a1-4d0en2cd8331），您可以指定 KMS 密钥 ID。
disable_spill_encryption -（可选）当设置为 True 时，将禁用溢出加密。默认值为 False，此时将使用 AES-GCM 对溢出到 S3 的数据使用进行加密 - 使用随机生成的密钥，或者使用 KMS 生成密钥。禁用溢出加密可以提高性能，尤其是当您的溢出位置使用服务器端加密时。
disable_glue -（可选）如果存在且设置为 true，则该连接器不会尝试从 Amazon Glue 检索补充元数据。
query_timeout_cluster – 生成并行扫描时使用的集群运行状况查询的超时时间（以秒为单位）。
query_timeout_search – 用于从索引检索文档的搜索查询的超时时间（以秒为单位）。
auto_discover_endpoint – 布尔型。默认为 true。当您使用 Amazon OpenSearch Service 并将此参数设置为 true 时，该连接器可以通过在 OpenSearch Service 上调用适当的描述或列出 API 操作来自动发现您的域和端点。对于任何其他类型的 OpenSearch 实例（例如，自托管型），您必须在 domain_mapping 变量中指定相关联的域端点。如果 auto_discover_endpoint=true，该连接器将使用 Amazon 凭证对 OpenSearch Service 进行身份验证。否则，该连接器将通过 domain_mapping 变量从 Amazon Secrets Manager 检索用户名和密码凭证。
domain_mapping – 仅在将 auto_discover_endpoint 设置为 false 并定义域名与其关联端点之间的映射时使用。domain_mapping 变量可以容纳以下格式的多个 OpenSearch 端点：
```
domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,...       
```
为了对 OpenSearch 端点进行身份验证，该连接器支持使用 ${SecretName}: 格式以及从 Amazon Secrets Manager 检索的用户名和密码注入的替换字符串。表达式末尾的冒号 (:) 用作与端点的其余部分的分隔符。

重要
作为安全最佳实践，请勿在您的环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 Amazon Secrets Manager 的信息，请参阅《Amazon Secrets Manager 用户指南》中的将硬编码密钥移至 Amazon 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 的分隔符。

还要注意，此连接器使用逗号 (,) 和等号 (=) 作为域-端点对的分隔符。因此，您不应在存储的密钥中的任何位置使用它们。

在 Amazon Glue 中设置数据库和表

该连接器使用 Amazon Glue 或 OpenSearch 获取元数据信息。您可以设置一个 Amazon Glue 表，作为补充元数据定义源。要启用此功能，请定义与您要补充的源的域和索引相匹配的 Amazon 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 连接器可从 Amazon Glue 或 OpenSearch 实例提取元数据定义。该连接器使用下表中的映射将这些定义转换为 Apache Arrow 数据类型，包括下节中提到的要点。

OpenSearch	Apache Arrow	Amazon Glue
text、keyword、binary	VARCHAR	字符串
long	BIGINT	bigint
scaled_float	BIGINT	SCALED_FLOAT(...)
integer	INT	int
short	SMALLINT	smallint
字节	TINYINT	tinyint
double	FLOAT8	double
float、half_float	FLOAT4	float
布尔值	BIT	布尔值
date、date_nanos	DATEMILLI	timestamp
JSON 结构	STRUCT	STRUCT
_meta（有关信息，请参阅在 OpenSearch 中为数组定义元数据一节。）	LIST	ARRAY

有关数据类型的注释

目前，该连接器仅支持上表中列出的 OpenSearch 和 Amazon Glue 数据类型。
scaled_float 是按固定双精度缩放系数缩放的浮点数，在 Apache Arrow 中以 BIGINT 形式表示。例如，在缩放系数为 100 的情况下，0.756 将四舍五入为 76。
要在 Amazon 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 中的数据的文章，请参阅 Amazon 大数据博客中的使用 Amazon Athena 的 SQL 查询 Amazon OpenSearch Service 中的数据。
有关此连接器的更多信息，请访问 GitHub.com 上的相应站点。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

Neptune

Oracle