# Amazon Athena OpenSearch 连接器 OpenSearch Service Amazon Athena OpenSearch 连接器使 Amazon Athena 能够与您的 OpenSearch 实例进行通信，以便您可以使用 SQL 查询您的 OpenSearch 数据。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 **注意** 由于存在已知问题，OpenSearch 连接器无法与 VPC 一起使用。 如果您在账户中启用了 Lake Formation，则您在 AWS Serverless Application Repository 中部署的 Athena 联合身份 Lambda 连接器的 IAM 角色必须在 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)。 ## 参数 使用本节中的参数来配置 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 数据来源连接器时才使用以下参数。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 OpenSearch 连接器。要执行此操作，请将 OpenSearch 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type OPENSEARCH ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 OpenSearch 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 OpenSearch 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 + **spill\$1bucket** - 为超出 Lambda 函数限制的数据指定 Amazon S3 存储桶。 + **spill\$1prefix** -（可选）默认为指定 `spill_bucket`（称为 `athena-federation-spill`）中的子文件夹。我们建议您在此位置配置 Amazon S3 [存储生命周期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)，以删除早于预定天数或小时数的溢出内容。 + **spill\$1put\$1request\$1headers** —（可选）用于溢出的 Amazon S3 `putObject` 请求的请求标头和值的 JSON 编码映射（例如 `{"x-amz-server-side-encryption" : "AES256"}`)。有关其他可能的标头，请参阅《[Amazon Simple Storage Service API 参考](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)》中的 *PutObject*。 + **kms\$1key\$1id** -（可选）默认情况下，将使用经过 AES-GCM 身份验证的加密模式和随机生成的密钥对溢出到 Amazon S3 的任何数据进行加密。要让您的 Lambda 函数使用 KMS 生成的更强的加密密钥（如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`），您可以指定 KMS 密钥 ID。 + **disable\$1spill\$1encryption** -（可选）当设置为 `True` 时，将禁用溢出加密。默认值为 `False`，此时将使用 AES-GCM 对溢出到 S3 的数据使用进行加密 - 使用随机生成的密钥，或者使用 KMS 生成密钥。禁用溢出加密可以提高性能，尤其是当您的溢出位置使用[服务器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)时。 + **disable\$1glue** -（可选）如果存在且设置为 true，则该连接器不会尝试从 AWS Glue 检索补充元数据。 + **query\$1timeout\$1cluster** – 生成并行扫描时使用的集群运行状况查询的超时时间（以秒为单位）。 + **query\$1timeout\$1search** – 用于从索引检索文档的搜索查询的超时时间（以秒为单位）。 + **auto\$1discover\$1endpoint** – 布尔型。默认值为 `true`。当您使用 Amazon OpenSearch Service 并将此参数设置为 true 时，该连接器可以通过在 OpenSearch Service 上调用适当的描述或列出 API 操作来自动发现您的域和端点。对于任何其他类型的 OpenSearch 实例（例如，自托管型），您必须在 `domain_mapping` 变量中指定相关联的域端点。如果 `auto_discover_endpoint=true`，该连接器将使用 AWS 凭证对 OpenSearch Service 进行身份验证。否则，该连接器将通过 `domain_mapping` 变量从 AWS Secrets Manager 检索用户名和密码凭证。 + **domain\$1mapping** – 仅在将 `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\$1name*@*password* 格式指定。虽然密码可能包含嵌入式 `@` 标志，但第一个 `@` 将用作来自 *user\$1name* 的分隔符。 还要注意，此连接器使用逗号 (,) 和等号 (=) 作为域-端点对的分隔符。因此，您不应在存储的密钥中的任何位置使用它们。 ## 在 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 | | --- | --- | --- | | text、keyword、binary | VARCHAR | 字符串 | | 长整数 | BIGINT | bigint | | scaled\$1float | BIGINT | SCALED\$1FLOAT(...) | | 整数 | INT | int | | short | SMALLINT | smallint | | 字节 | TINYINT | tinyint | | double | FLOAT8 | double | | float、half\$1float | FLOAT4 | float | | 布尔值 | BIT | 布尔值 | | date、date\$1nanos | DATEMILLI | timestamp | | JSON 结构 | STRUCT | STRUCT | | \$1meta（有关信息，请参阅 [在 OpenSearch 中为数组定义元数据](#connectors-opensearch-defining-metadata-for-arrays-in-opensearch) 一节。） | LIST | ARRAY | #### 有关数据类型的注释 + 目前，该连接器仅支持上表中列出的 OpenSearch 和 AWS Glue 数据类型。 + `scaled_float` 是按固定双精度缩放系数缩放的浮点数，在 Apache Arrow 中以 `BIGINT` 形式表示。例如，在缩放系数为 100 的情况下，0.756 将四舍五入为 76。 + 要在 AWS Glue 中定义 `scaled_float`，您必须选择 `array` 列类型，并使用 SCALED\$1FLOAT(*scaling\$1factor*) 格式声明字段。 以下示例有效： ``` 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\$1name* 对应于您的 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 示例传递查询，对 `employee` 架构 `default` 索引中处于活跃就业状态的员工进行了筛选。 ``` 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)。