# 连接到数据来源 您可以使用 Amazon Athena 查询*数据集*中的不同位置和以不同格式存储的数据。此数据集可能采用 CSV、JSON、Avro、Parquet 或其他格式。 您在 Athena 中用于运行查询的表格和数据库基于*元数据*。元数据是与数据集中的底层数据有关的数据。元数据描述数据集的方式称为*架构*。例如，表名称、表中的列名称以及每列的数据类型都是架构，保存为元数据，用于描述底层数据集。在 Athena 中，我们将用于整理元数据的系统称*为数据目录*或*元数据仓*。数据集和用于描述它的数据目录的组合称为*数据源*。 元数据与底层数据集的关系取决于您所用的数据源类型。MySQL、PostgreSQL 和 SQL Server 等关系数据源将元数据与数据集紧密集成。在这些系统中，在写入数据时通常会写入元数据。其他数据源（如使用 [Hive](https://hive.apache.org) 构建的数据源）允许您在读取数据集时即时定义元数据。数据集可以采用多种格式，例如 CSV、JSON、Parquet 或 Avro。 Athena 原生支持 AWS Glue Data Catalog。AWS Glue Data Catalog 是在其他数据集和数据源（如 Amazon S3、Amazon Redshift 和 Amazon DynamoDB）之上构建的数据目录。您还可以使用各种连接器将 Athena 连接到其他数据源。 **Topics** + [使用 AWS Glue Data Catalog 连接数据](data-sources-glue.md) + [使用 Amazon Athena 联合查询](federated-queries.md) + [在 Athena 中使用 Amazon DataZone](datazone-using.md) + [使用外部 Hive 元存储](connect-to-data-source-hive.md) + [管理您的数据来源](data-sources-managing.md) # 使用 AWS Glue Data Catalog 连接数据 Athena 使用 AWS Glue Data Catalog 存储元数据，如存储在 Amazon S3 中的数据的表名和列名。此元数据信息将成为您在 Athena 查询编辑器中看到的数据库、表和视图。 在将 Athena 与 AWS Glue Data Catalog 配合使用时，可使用 AWS Glue 创建要在 Athena 中查询的数据库和表（架构），也可以使用 Athena 创建架构，然后将其用于 AWS Glue 和相关服务。 要为 AWS Glue 定义架构信息，可以使用 Athena 控制台中的表单、使用 Athena 中的查询编辑器或在 AWS Glue 控制台中创建 AWS Glue 爬网程序。AWS Glue 爬网程序会自动从 Amazon S3 中的数据推断数据库和表架构。使用表单可提供更多自定义。编写自己的 `CREATE TABLE` 语句需要更多努力，但提供了最大控制权。有关更多信息，请参阅 [CREATE TABLE](create-table.md)。 ## 其他资源 + 有关 AWS Glue Data Catalog 的更多信息，请参阅《AWS Glue 开发人员指南**》中的 [AWS Glue 中的数据目录和爬网程序](https://docs.aws.amazon.com/glue/latest/dg/catalog-and-crawler.html)。 + 有关展示如何使用 AWS Glue 和 Athena 处理 XML 数据的说明性文章，请参阅 AWS 大数据博客中的 [Process and analyze highly nested and large XML files using AWS Glue and Amazon Athena](https://aws.amazon.com/blogs/big-data/process-and-analyze-highly-nested-and-large-xml-files-using-aws-glue-and-amazon-athena/)。 + 需单独支付 AWS Glue 的费用。有关更多信息，请参阅 [AWS Glue 定价](https://aws.amazon.com/glue/pricing)。 **Topics** + [其他资源](#glue-additional-resources) + [在 Athena 中注册和使用数据目录](gdc-register.md) + [从其他账户注册数据目录](data-sources-glue-cross-account.md) + [使用 IAM 策略控制对数据目录的访问权限](datacatalogs-iam-policy.md) + [在 Athena 控制台中使用表单添加 AWS Glue 表](data-sources-glue-manual-table.md) + [使用爬网程序添加表](schema-crawlers.md) + [使用 AWS Glue 分区索引和筛选来优化查询](glue-best-practices-partition-index.md) + [使用 AWS CLI 重新创建 AWS Glue 数据库及其表](glue-recreate-db-and-tables-cli.md) + [为 ETL 作业创建表](schema-classifier.md) + [使用 AWS Glue 中的 CSV 数据](schema-csv.md) + [使用 AWS Glue 中的地理空间数据](schema-geospatial.md) # 在 Athena 中注册和使用数据目录 Athena 支持挂载和连接多个数据目录。 + 您可以从 Athena 将 Amazon Redshift 数据挂载到 AWS Glue Data Catalog 中并进行查询，而无需复制或移动数据。有关更多信息，请参阅 [Bringing Amazon Redshift data into the AWS Glue Data Catalog](https://docs.aws.amazon.com/lake-formation/latest/dg/managing-namespaces-datacatalog.html)。 + 使用 AWS Glue 连接将 AWS Glue Data Catalog 连接到外部数据来源，并创建联合目录来集中管理使用 Lake Formation 进行精细访问控制的数据。有关更多信息，请参阅 [将连接注册为 Glue Data Catalog](register-connection-as-gdc.md)。 + 从 Amazon S3 表存储桶创建目录，然后使用 Lake Formation 集中管理访问权限并限制用户对表存储桶中对象的访问。有关更多信息，请参阅《Amazon S3 开发人员指南》中的 [Working with Amazon S3 Tables and table buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables.html)。 **注意** 对于任何 Glue 目录，您只能注册类似于 `123412341234:my_catalog/my_child` 的多级目录，不能注册类似于 `123412341234:linkcontainer` 或 `my_catalog` 的单级目录。单级目录只能在 Athena 查询中直接使用 Glue 数据目录来查询。有关更多信息，请参阅 [在 Athena 中查询 AWS Glue 数据目录](gdc-register-query-the-data-source.md)。 **Topics** + [在 Athena 中注册 Redshift 数据目录](gdc-register-rs.md) + [在 Athena 中注册联合目录](gdc-register-federated.md) + [通过 Athena 注册 S3 表存储桶目录和查询表](gdc-register-s3-table-bucket-cat.md) + [在 Athena 中查询 AWS Glue 数据目录](gdc-register-query-the-data-source.md) # 在 Athena 中注册 Redshift 数据目录 Athena 可以从 AWS Glue Data Catalog 中注册的 Redshift 集群或无服务器命名空间中读取存储的数据以及将数据写入其中。这是与 AWS Lake Formation 配合使用来实现的，后者提供集中式安全和治理，确保不同查询引擎之间的数据访问得到一致的管理，并保持对共享 Redshift 数据的精细访问控制。 ## 注意事项和限制 + **实体化视图**：可以从 Athena 查询 Amazon Redshift 实体化视图，但不支持使用 Athena 或 Spark 创建实体化视图。 + 不支持 DDL 操作，包括在 Amazon Redshift 托管式存储表上设置 AWS Glue Data Catalog 配置和操作。 ## 先决条件 从 Athena 查询 AWS Glue 数据目录之前，请完成以下任务： 1. 创建 Amazon Redshift 集群或无服务器命名空间并将其注册到 AWS Glue Data Catalog。有关更多信息，请参阅《Amazon Redshift 管理指南》中的 [Registering a cluster to the AWS Glue Data Catalog](https://docs.aws.amazon.com/redshift/latest/mgmt/register-cluster.html) 或 [Registering namespaces to the AWS Glue Data Catalog](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless_datasharing-register-namespace.html)。 1. 从注册的命名空间在 AWS Lake Formation 中创建数据目录。有关更多信息，请参阅《AWS Lake Formation 开发人员指南》中的 [Creating Amazon Redshift federated catalogs](https://docs.aws.amazon.com/lake-formation/latest/dg/create-ns-catalog.html)。 1. （可选）使用 Lake Formation 设置对目录的精细访问控制。有关更多信息，请参阅《AWS Lake Formation 开发人员指南》中的 [Bringing your data into the AWS Glue Data Catalog](https://docs.aws.amazon.com/lake-formation/latest/dg/bring-your-data-overview.html)。 ## 通过 Athena 控制台注册 Redshift 数据目录 要通过 Athena 控制台注册 Redshift 数据目录，请执行以下步骤。 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) 打开 Athena 控制台。 1. 在导航窗格中，选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择**创建数据来源**。 1. 在**选择数据来源**中，选择 **Amazon S3 - AWS Glue Data Catalog**。 1. 在 **AWS Glue Data Catalog** 部分中，对于**数据来源账户**，选择**此账户中的 AWS Glue Data Catalog**。 1. 对于**创建表或注册目录**，请选择**注册新 AWS Glue 目录**。 1. 在**数据来源详细信息**部分中，对于**数据来源名称**，请输入用于在 SQL 查询中指定数据来源的名称，或者使用生成的默认名称。 1. 对于**目录**，选择**浏览**来搜索同一账户中的 AWS Glue 目录列表。如果看不到任何现有目录，请通过 [AWS Glue 控制台](https://console.aws.amazon.com/glue/)创建一个。 1. 在**浏览 AWS Glue 目录**对话框中，选择要使用的目录，然后选中**选择**。 1. （可选）对于**标签**，输入要与该数据来源关联的键值对。 1. 选择**下一步**。 1. 在**检查并创建**页面上，验证输入的信息是否正确，然后选择**创建数据来源**。 # 在 Athena 中注册联合目录 创建到联合数据来源的连接后，您可以将其注册为联合数据目录以简化数据发现，并借助 Lake Formation 的精细权限来管理数据访问权限。有关更多信息，请参阅 [将连接注册为 Glue Data Catalog](register-connection-as-gdc.md)。 ## 注意事项和限制 + 联合目录不支持 DDL 操作。 + 您可以注册以下连接器以便与 AWS Glue 集成，从而实现精细访问控制： + [Azure Data Lake 存储](connectors-adls-gen2.md) + [Azure Synapse](connectors-azure-synapse.md) + [BigQuery](connectors-bigquery.md) + [CMDB](connectors-cmdb.md) + [Db2](connectors-ibm-db2.md) + [Db2 iSeries](connectors-ibm-db2-as400.md) + [DocumentDB](connectors-docdb.md) + [DynamoDB](connectors-dynamodb.md) + [Google Cloud Storage](connectors-gcs.md) + [HBase](connectors-hbase.md) + [MySQL](connectors-mysql.md) + [OpenSearch](connectors-opensearch.md) + [Oracle](connectors-oracle.md) + [PostgreSQL](connectors-postgresql.md) + [Redshift](connectors-redshift.md) + [SAP HANA](connectors-sap-hana.md) + [Snowflake](connectors-snowflake.md) + [SQL Server](connectors-microsoft-sql-server.md) + [Timestream](connectors-timestream.md) + [TPC-DS](connectors-tpcds.md) + 在为 Glue 连接联合身份验证创建资源链接时，[资源链接](https://docs.aws.amazon.com/lake-formation/latest/dg/create-resource-link-database.html)的名称必须与创建者的数据库名称相同。 + 当前，即使数据来源不区分大小写，也只能识别小写的表名和列名。 # 通过 Athena 注册 S3 表存储桶目录和查询表 Amazon S3 表存储桶是 Amazon S3 中的一种存储桶类型，专门用于存储 Apache Iceberg 表中的表格数据。表存储桶可自动执行压缩、快照管理和垃圾回收等表管理任务，从而持续优化查询性能并尽可能降低成本。无论您是刚开始使用，还是已经在 Iceberg 环境中拥有数千个表，表存储桶都能简化任意规模的数据湖。有关更多信息，请参阅 [Table Buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets.html)。 ## 注意事项和限制 + Iceberg 表支持的所有 DDL 操作都支持 S3 表，但以下情况除外： + 不支持 `ALTER TABLE RENAME`、`CREATE VIEW` 和 `ALTER DATABASE`。 + `OPTIMIZE` 和 `VACUUM` – 您可以在 S3 中管理压缩和快照管理。有关更多信息，请参阅 [S3 表维护文档](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-maintenance.html)。 + 不支持对注册为 Athena 数据来源的 S3 表进行 DDL 查询。 + 不支持重复使用查询结果。 + 在启用了 SSE-KMS、CSE-KMS 加密的工作组中，您无法在 S3 表上运行 `INSERT`、`UPDATE`、`DELETE` 或 `MERGE` 之类的写入操作。 + 在启用了“S3 申请方付款”选项的工作组中，您无法在 S3 表上运行 DML 操作。 ## 从 Athena 中查询 S3 表 **在 Athena 中查询 S3 表之前，请完成以下前提步骤** 1. 创建一个 S3 表存储桶。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的 [Creating a table bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets-create.html)。 1. 确保已成功将表存储桶与 AWS Glue Data Catalog 集成。有关所需权限和设置步骤，请参阅《AWS Glue 开发人员指南》中的 [S3 表类数据存储服务集成的先决条件](https://docs.aws.amazon.com/glue/latest/dg/s3tables-catalog-prerequisites.html)和[启用 S3 表类数据存储服务与 Glue Data Catalog 的集成](https://docs.aws.amazon.com/glue/latest/dg/enable-s3-tables-catalog-integration.html)。 1. 对于用于通过 Athena 运行查询的主体，请使用以下方法之一授予其对 S3 表类数据存储服务目录的权限： **选项 1：使用 IAM 权限** 使用 IAM 访问控制时，您的主体需要同时拥有对 AWS Glue Data Catalog 资源和 Amazon S3 表类数据存储服务资源的权限。 以下列表包含对 Athena 中的 S3 表类数据存储服务执行任何受支持的 DDL 或 DML 操作所需的所有 `s3tables` 权限： + `s3tables:GetTableBucket` + `s3tables:GetNamespace` + `s3tables:GetTable` + `s3tables:GetTableData` + `s3tables:PutTableData` + `s3tables:ListNamespaces` + `s3tables:ListTables` + `s3tables:DeleteNamespace` + `s3tables:DeleteTable` + `s3tables:CreateNamespace` + `s3tables:CreateTable` + `s3tables:UpdateTableMetadataLocation` 将这些权限应用于特定 S3 表存储桶和 S3 表资源，或者使用 `*` 作为资源来授予对您账户中所有表存储桶和表的访问权限。这些权限可以与 [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html) 托管式策略结合使用，以实现完整的功能。 **选项 2：使用 Lake Formation 权限** 或者，要实现精细的访问控制，您可以通过 Lake Formation 控制台或 AWS CLI 授予 Lake Formation 对 S3 表目录的权限。这需要将您的 S3 表存储桶注册为 Lake Formation 数据位置。有关更多信息，请参阅《Lake Formation 开发人员指南》中的[在 AWS Glue Data Catalog 中创建 Amazon S3 表类数据存储服务目录](https://docs.aws.amazon.com/lake-formation/latest/dg/create-s3-tables-catalog.html)。 ------ #### [ AWS 管理控制台 ] 1. 以数据湖管理员身份登录 AWS Lake Formation 控制台（地址为 [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/)）。有关如何创建数据湖管理员的更多信息，请参阅 [Create a data lake administrator](https://docs.aws.amazon.com/lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)。 1. 在导航窗格中，选择**数据权限**，然后选择**授予**。 1. 在**授予权限**页面的**主体**下，选择要用于从 Athena 提交查询的主体。 1. 在 **LF 标签或目录资源**下，选择**命名 Data Catalog 资源**。 1. 对于**目录**，请选择您通过集成表存储桶创建的 Glue 数据目录。例如，**:s3tablescatalog/*amzn-s3-demo-bucket*。 1. 对于**目录权限**，请选择**超级**。 1. 选择**授权**。 ------ #### [ AWS CLI ] 使用 Lake Formation 数据湖管理员角色运行以下命令，以授予对您用于从 Athena 提交查询的主体的访问权限。 ``` aws lakeformation grant-permissions \ --region \ --cli-input-json \ '{ "Principal": { "DataLakePrincipalIdentifier": ":role/ExampleRole>" }, "Resource": { "Catalog": { "Id":":s3tablescatalog/amzn-s3-demo-bucket" } }, "Permissions": ["ALL"] }' ``` ------ **提交对 S3 表的查询** 1. 使用上述获得授权的用户/角色从 Athena 提交 `CREATE DATABASE` 查询。在此示例中，`s3tablescatalog` 是通过集成创建的父级 Glue 数据目录，` s3tablescatalog/amzn-s3-demo-bucket` 是为每个 S3 表存储桶创建的子 Glue 数据目录。查询的方法有两种。 ------ #### [ Option 1 ] 直接从控制台或 AWS CLI 指定子 Glue 数据目录（`s3tablescatalog/amzn-s3-demo-bucket`）。 **使用 AWS 管理控制台** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) 打开 Athena 控制台。 1. 在左侧导航栏中，对于**数据来源名称**，选择 **AwsDataCatalog**。 1. 对于**目录**，选择 **s3tablescatalog/*amzn-s3-demo-bucket***。 1. 在查询编辑器中，输入类似于 `CREATE DATABASE test_namespace` 的查询。 **使用 AWS CLI** 运行如下命令。 ``` aws athena start-query-execution \ --query-string 'CREATE DATABASE `test_namespace`' \ --query-execution-context '{"Catalog": "s3tablescatalog/amzn-s3-demo-bucket"}' \ --work-group "primary" ``` ------ #### [ Option 2 ] 通过 Athena 控制台从子 Glue 数据目录创建 Athena 数据目录，并在查询中将其指定为目录。有关更多信息，请参阅 [将 S3 表存储桶目录注册为 Athena 数据来源](#gdc-register-s3-table-console-steps)。 ------ 1. 通过您在上一步中创建的数据库，使用 `CREATE TABLE` 创建表。以下示例将在您先前于 `s3tablescatalog/amzn-s3-demo-bucket` Glue 目录中创建的 *`test_namespace`* 数据库中创建一个表。 ------ #### [ AWS 管理控制台 ] 1. 在左侧导航栏中，对于**数据来源名称**，选择 **AwsDataCatalog**。 1. 对于**目录**，选择 **s3tablescatalog/*amzn-s3-demo-bucket***。 1. 对于**数据库**，请选择 **test\$1namespace**。 1. 在查询编辑器中，运行以下查询。 ``` CREATE TABLE daily_sales ( sale_date date, product_category string, sales_amount double) PARTITIONED BY (month(sale_date)) TBLPROPERTIES ('table_type' = 'iceberg') ``` ------ #### [ AWS CLI ] 运行如下命令。 ``` aws athena start-query-execution \ --query-string "CREATE TABLE daily_sales ( sale_date date, product_category string, sales_amount double) PARTITIONED BY (month(sale_date)) TBLPROPERTIES ('table_type' = 'iceberg')" \ --query-execution-context '{"Catalog": "s3tablescatalog/amzn-s3-demo-bucket", "Database":"test_namespace"}' \ --work-group "primary" ``` ------ 1. 将数据插入您在之前的步骤中创建的表。 ------ #### [ AWS 管理控制台 ] 1. 在左侧导航栏中，对于**数据来源名称**，选择 **AwsDataCatalog**。 1. 对于**目录**，选择 **s3tablescatalog/*amzn-s3-demo-bucket***。 1. 对于**数据库**，请选择 **test\$1namespace**。 1. 在查询编辑器中，运行以下查询。 ``` INSERT INTO daily_sales VALUES (DATE '2024-01-15', 'Laptop', 900.00), (DATE '2024-01-15', 'Monitor', 250.00), (DATE '2024-01-16', 'Laptop', 1350.00), (DATE '2024-02-01', 'Monitor', 300.00); ``` ------ #### [ AWS CLI ] 运行如下命令。 ``` aws athena start-query-execution \ --query-string "INSERT INTO \"s3tablescatalog/amzn-s3-demo-bucket\".test_namespace.daily_sales VALUES (DATE '2024-01-15', 'Laptop', 900.00), (DATE '2024-01-15', 'Monitor', 250.00), (DATE '2024-01-16', 'Laptop', 1350.00), (DATE '2024-02-01', 'Monitor', 300.00)"\ --work-group "primary" ``` ------ 1. 向表中插入数据后，您可以对其进行查询。 ------ #### [ AWS 管理控制台 ] 1. 在左侧导航栏中，对于**数据来源名称**，选择 **AwsDataCatalog**。 1. 对于**目录**，选择 **s3tablescatalog/*amzn-s3-demo-bucket***。 1. 对于**数据库**，请选择 **test\$1namespace**。 1. 在查询编辑器中，运行以下查询。 ``` SELECT product_category, COUNT(*) AS units_sold, SUM(sales_amount) AS total_revenue, AVG(sales_amount) AS average_price FROM daily_sales WHERE sale_date BETWEEN DATE '2024-02-01' AND DATE '2024-02-29' GROUP BY product_category ORDER BY total_revenue DESC ``` ------ #### [ AWS CLI ] 运行如下命令。 ``` aws athena start-query-execution \ --query-string "SELECT product_category, COUNT(*) AS units_sold, SUM(sales_amount) AS total_revenue, AVG(sales_amount) AS average_price FROM \"s3tablescatalog/amzn-s3-demo-bucket\".test_namespace.daily_sales WHERE sale_date BETWEEN DATE '2024-02-01' AND DATE '2024-02-29' GROUP BY product_category ORDER BY total_revenue DESC"\ --work-group "primary" ``` ------ ## 在 Athena 中创建 S3 表 Athena 支持在现有的 S3 表命名空间或使用 `CREATE DATABASE` 语句在 Athena 中创建的命名空间中创建表。要从 Athena 创建 S3 表，语法要与[创建常规 Iceberg 表](querying-iceberg-creating-tables.md)时的语法相同，只是无需指定 `LOCATION`，如以下示例所示。 ``` CREATE TABLE [db_name.]table_name (col_name data_type [COMMENT col_comment] [, ...] ) [PARTITIONED BY (col_name | transform, ... )] [TBLPROPERTIES ([, property_name=property_value] )] ``` 您也可以使用 CREATE TABLE AS SELECT（CTAS）语句创建 S3 表。有关更多信息，请参阅 [适用于 S3 表的 CTAS](#ctas-s3-tables)。 ## 将 S3 表存储桶目录注册为 Athena 数据来源 要通过 Athena 控制台注册 S3 表存储桶目录，请执行以下步骤。 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) 打开 Athena 控制台。 1. 在导航窗格中，选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择**创建数据来源**。 1. 在**选择数据来源**中，选择 **Amazon S3 - AWS Glue Data Catalog**。 1. 在 **AWS Glue Data Catalog** 部分中，对于**数据来源账户**，选择**此账户中的 AWS Glue Data Catalog**。 1. 对于**创建表或注册目录**，请选择**注册新 AWS Glue 目录**。 1. 在**数据来源详细信息**部分中，对于**数据来源名称**，请输入用于在 SQL 查询中指定数据来源的名称，或者使用生成的默认名称。 1. 对于**目录**，选择**浏览**来搜索同一账户中的 AWS Glue 目录列表。如果看不到任何现有目录，请通过 [AWS Glue 控制台](https://console.aws.amazon.com/glue/)创建一个。 1. 在**浏览 AWS Glue 目录**对话框中，选择要使用的目录，然后选中**选择**。 1. （可选）对于**标签**，输入要与该数据来源关联的键值对。 1. 选择**下一步**。 1. 在**检查并创建**页面上，验证输入的信息是否正确，然后选择**创建数据来源**。 ## 适用于 S3 表的 CTAS Amazon Athena 现在支持对 S3 表执行 CREATE TABLE AS SELECT（CTAS）操作。此功能允许您根据 SELECT 查询的结果创建新的 S3 表。 在为 S3 表创建 CTAS 查询时，与标准 Athena 表相比，有一些重要的区别： + 您必须省略位置属性，因为 S3 表会自动管理自己的存储位置。 + `table_type` 属性的默认值为 `ICEBERG`，因此您无需在查询中显式指定该属性。 + 如果您不指定格式，系统将自动使用 `PARQUET` 作为数据的默认格式。 + 所有其他属性都遵循与常规 Iceberg 表相同的语法。 在使用 CTAS 创建 S3 表类数据存储服务之前，请确保您已在 IAM 或 AWS Lake Formation 中配置必要的权限。具体而言，您需要在 S3 表目录中创建表的权限。如果没有这些权限，您的 CTAS 操作将失败。 **注意** 如果您的 CTAS 查询失败，您可能需要先使用 [S3 表 API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-delete.html) 删除表，然后再尝试重新运行查询。您无法使用 Athena `DROP TABLE` 语句删除由该查询部分创建的表。 **示例** ``` CREATE TABLE "s3tablescatalog/amzn-s3-demo-bucket"."namespace"."s3-table-name" WITH ( format = 'PARQUET' ) AS SELECT * FROM source_table; ``` # 在 Athena 中查询 AWS Glue 数据目录 要从 Athena 查询数据目录，请执行以下操作之一。 + 在 Athena 中将该目录注册为数据来源，然后使用数据来源名称查询该目录。使用这种方法时，以下查询是等效的。 ``` SELECT * FROM my_data_source.my_database.my_table ``` + 如果要查询的目录尚未注册为 Athena 数据来源，则可以在 `SELECT` 查询中提供该目录的完整路径，如下例所示。 ``` SELECT * FROM "my_catalog/my_subcatalog".my_database.my_table ``` + 也可以通过 AWS 管理控制台执行此操作。 1. 打开 Athena 控制台，网址为 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/)。 1. 在查询编辑器中，对于**数据来源**，选择 **AwsDataCatalog**。 1. 对于**目录**，选择要使用的目录的名称。 1. 对于**数据库**，选择包含要查询的表的数据库。 1. 输入类似于 `SELECT * FROM my_table` 的查询，然后选择**运行**。 # 从其他账户注册数据目录 您可以使用 Athena 的跨账户 AWS Glue 目录功能来从您自己的账户以外的账户注册 AWS Glue 目录。在您为 AWS Glue 配置所需的 IAM 权限并将目录注册为 Athena `DataCatalog` 资源后，您可以使用 Athena 运行跨账户查询。有关配置所需权限的信息，请参阅 [配置 AWS Glue 数据目录的跨账户存取](security-iam-cross-account-glue-catalog-access.md)。 以下过程说明如何使用 Athena 将 AWS Glue Data Catalog 在不属于您的 Amazon Web Services 账户中配置为数据来源。 ## 从控制台注册 1. 请按 [配置 AWS Glue 数据目录的跨账户存取](security-iam-cross-account-glue-catalog-access.md) 中的步骤操作，以确保您有权查询其他账户中的数据目录。 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 选择**数据来源和目录**。 1. 选择右上角的 **Connect data source**（连接数据来源）。 1. 在 **Choose a data source**（选择数据来源）页面上，对于**Data sources**（数据来源），选择 **S3 - AWS Glue Data Catalog**，然后选择 **Next**（下一步）。 1. 在**输入数据来源详细信息**页面的 **AWS Glue Data Catalog** 部分中，对于**选择 AWS Glue Data Catalog**，选择 **AWS Glue Data Catalog 中的其他账户**。 1. 对于 **Data source details**（数据源详细信息），提供以下信息： + **Data source name**（数据源名称）– 输入要在 SQL 查询中使用的名称，以引用其他账户中的数据目录。 + **Description**（描述）–（可选）输入其他账户中数据目录的描述。 + **Catalog ID**（目录编号）– 输入数据目录所属账户的 12 位 Amazon Web Services 账户 ID。Amazon Web Services 账户 ID 即是目录 ID。 1. （可选）对于 **Tags**（标签），输入要与数据源关联的键-值对。有关标签的更多信息，请参阅[标记 Athena 资源](tags.md)。 1. 选择**下一步**。 1. 在 **Review and create**（审核和创建）页面中，检查数据来源的详细信息，然后选择 **Create data source**（创建数据来源）。**Data source details**（数据来源详细信息）页面列出了所注册数据目录的数据库和标签。 1. 选择**数据来源和目录**。您注册的数据目录在 **Data source name**（数据来源名称）列中列出。 1. 要查看或编辑有关数据目录的信息，请选择该目录，然后选择**Actions**（操作）、**Edit**（编辑）。 1. 要删除新数据目录，请选择该目录，然后选择 **Actions**（操作）、**Delete**（删除）。 ## 使用 API 操作进行注册 1. 以下 `CreateDataCatalog` 请求正文为跨账户访问注册了 AWS Glue 目录： ``` # Example CreateDataCatalog request to register a cross-account Glue catalog: { "Description": "Cross-account Glue catalog", "Name": "ownerCatalog", "Parameters": {"catalog-id" : "" # Owner's account ID }, "Type": "GLUE" } ``` 1. 以下示例代码使用 Java 客户端创建 `DataCatalog` 对象。 ``` # Sample code to create the DataCatalog through Java client CreateDataCatalogRequest request = new CreateDataCatalogRequest() .withName("ownerCatalog") .withType(DataCatalogType.GLUE) .withParameters(ImmutableMap.of("catalog-id", "")); athenaClient.createDataCatalog(request); ``` 完成这些步骤后，借入者应会在调用 [ListDataCatalogs](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDataCatalogs.html) API 操作时看到 *`ownerCatalog`*。 ## 使用 AWS CLI 进行注册 使用以下示例 CLI 命令从另一个账户注册 AWS Glue Data Catalog ``` aws athena create-data-catalog \ --name cross_account_catalog \ --type GLUE \ --description "Cross Account Catalog" \ --parameters catalog-id= ``` 有关更多信息，请参阅 *AWS 大数据博客*中的[使用 Amazon Athena 查询跨账户 AWS Glue Data Catalog](https://aws.amazon.com/blogs/big-data/query-cross-account-aws-glue-data-catalogs-using-amazon-athena/)。 # 使用 IAM 策略控制对数据目录的访问权限 要控制对数据目录的访问，请使用资源级 IAM 权限或基于身份的 IAM policy。 以下是 Athena 的特定过程。 有关 IAM 的特定信息，请参阅本节末尾列出的链接。有关示例 JSON 数据目录策略的信息，请参阅 [数据目录示例策略](datacatalogs-example-policies.md)。 **在 IAM 控制台中使用可视化编辑器创建数据目录策略** 1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。 1. 在左侧的导航窗格中，选择 **Policies (策略)**，然后选择 **Create policy (创建策略)**。 1. 在**可视化编辑器**选项卡上，选择**选择服务**。然后，选择要添加到策略的 Athena。 1. 选择 **Select actions (选择操作)**，然后选择要添加到策略的操作。可视化编辑器会显示 Athena 中可用的操作。有关更多信息，请参阅《服务授权参考》**中的 [Amazon Athena 的操作、资源和条件键](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html)。 1. 选择 **add actions (添加操作)** 以键入特定操作，或使用通配符 (\$1) 指定多个操作。 预设情况下，您创建的策略允许执行选择的操作。如果您在 Athena 中选择对 `datacatalog` 资源执行一个或多个支持资源级权限的操作，则编辑器会列出 `datacatalog` 资源。 1. 选择**资源**，为您的策略指定特定的数据目录。有关 JSON 数据目录策略的示例，请参阅[数据目录示例策略](datacatalogs-example-policies.md)。 1. 指定 `datacatalog` 资源，如下所示： ``` arn:aws:athena:::datacatalog/ ``` 1. 选择 **Review policy (查看策略)**，然后为您创建的策略键入 **Name (名称)** 和 **Description (描述)**（可选）。查看策略摘要以确保您已授予所需的权限。 1. 选择**创建策略**可保存您的新策略。 1. 将此基于身份的策略附加到用户、组或角色，并指定他们可访问的 `datacatalog` 资源。 有关详细信息，请参阅*服务授权参考*和 *IAM 用户指南*中的以下主题： + [Amazon Athena 的操作、资源和条件键](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html) + [使用可视化编辑器创建策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor) + [添加和移除 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) + [控制对资源的访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#access_controlling-resources) 有关 JSON 数据目录策略的示例，请参阅[数据目录示例策略](datacatalogs-example-policies.md)。 有关 AWS Glue 权限和 AWS Glue 爬网程序权限的信息，请参阅《AWS Glue 开发人员指南》中的 [为 AWS Glue 设置 IAM 权限](https://docs.aws.amazon.com/glue/latest/dg/getting-started-access.html) 和 [爬网程序先决条件](https://docs.aws.amazon.com/glue/latest/dg/crawler-prereqs.html)。 有关 Amazon Athena 操作的完整列表，请参阅 [Amazon Athena API 参考](https://docs.aws.amazon.com/athena/latest/APIReference/)中的 API 操作名称。 # 数据目录示例策略 此部分包含可用于允许对数据目录执行各种操作的示例策略。 数据目录是由 Athena 管理的 IAM 资源。因此，如果您的数据目录策略使用将 `datacatalog` 用作输入的操作，则您必须指定数据目录的 ARN，如下所示： ``` "Resource": [arn:aws:athena:::datacatalog/] ``` `` 是数据目录的名称。例如，对于名为 `test_datacatalog` 的数据目录，请将其指定为资源，如下所示： ``` "Resource": ["arn:aws:athena:us-east-1:123456789012:datacatalog/test_datacatalog"] ``` 有关 Amazon Athena 操作的完整列表，请参阅 [Amazon Athena API 参考](https://docs.aws.amazon.com/athena/latest/APIReference/)中的 API 操作名称。有关 IAM policy 的更多信息，请参阅《IAM 用户指南》中的 [使用可视化编辑器创建策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor)。有关为工作组创建 IAM policy 的更多信息，请参阅 [使用 IAM 策略控制对数据目录的访问权限](datacatalogs-iam-policy.md)。 + [Example Policy for Full Access to All Data Catalogs](#datacatalog-policy-full-access-to-all-data-catalogs) + [Example Policy for Full Access to a Specified Data Catalog](#datacatalog-policy-full-access-to-a-specified-catalog) + [Example Policy for Querying a Specified Data Catalog](#datacatalog-policy-querying-a-specified-data-catalog) + [Example Policy for Management Operations on a Specified Data Catalog](#datacatalog-policy-management-operations-on-a-specified-catalog) + [Example Policy for Listing Data Catalogs](#datacatalog-policy-listing-data-catalogs) + [Example Policy for Metadata Operations on Data Catalogs](#datacatalog-policy-metadata-operations) **Example 对所有数据目录具有完全访问权限的策略示例** 以下策略允许对账户中可能存在的所有数据目录资源进行完全访问。对于您账户中必须为其他所有用户监督和管理数据目录的那些用户，建议您使用此策略。 **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "athena:*" ], "Resource":[ "*" ] } ] } ``` **Example 对指定数据目录具有完全访问权限的策略示例** 以下策略允许对单个名为 `datacatalogA` 的特定数据目录资源进行完全访问。对于对特定数据目录具有完全控制权限的用户，您可以使用此策略。 **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "athena:ListDataCatalogs", "athena:ListWorkGroups", "athena:GetDatabase", "athena:ListDatabases", "athena:ListTableMetadata", "athena:GetTableMetadata" ], "Resource":"*" }, { "Effect":"Allow", "Action":[ "athena:StartQueryExecution", "athena:GetQueryResults", "athena:DeleteNamedQuery", "athena:GetNamedQuery", "athena:ListQueryExecutions", "athena:StopQueryExecution", "athena:GetQueryResultsStream", "athena:ListNamedQueries", "athena:CreateNamedQuery", "athena:GetQueryExecution", "athena:BatchGetNamedQuery", "athena:BatchGetQueryExecution", "athena:DeleteWorkGroup", "athena:UpdateWorkGroup", "athena:GetWorkGroup", "athena:CreateWorkGroup" ], "Resource":[ "arn:aws:athena:us-east-1:123456789012:workgroup/*" ] }, { "Effect":"Allow", "Action":[ "athena:CreateDataCatalog", "athena:DeleteDataCatalog", "athena:GetDataCatalog", "athena:GetDatabase", "athena:GetTableMetadata", "athena:ListDatabases", "athena:ListTableMetadata", "athena:UpdateDataCatalog" ], "Resource":"arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA" } ] } ``` **Example 用于查询指定数据目录的策略示例** 在以下策略中，允许用户对指定的 `datacatalogA` 运行查询。不允许用户对数据目录本身执行管理任务，例如，更新或删除它。 **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "athena:StartQueryExecution" ], "Resource":[ "arn:aws:athena:us-east-1:123456789012:workgroup/*" ] }, { "Effect":"Allow", "Action":[ "athena:GetDataCatalog" ], "Resource":[ "arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA" ] } ] } ``` **Example 对指定数据目录执行管理操作的策略示例** 在以下策略中，允许用户创建、删除、获取详细信息并更新数据目录 `datacatalogA`。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:CreateDataCatalog", "athena:GetDataCatalog", "athena:DeleteDataCatalog", "athena:UpdateDataCatalog" ], "Resource": [ "arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA" ] } ] } ``` **Example 列出数据目录的策略示例** 以下策略允许所有用户列出所有数据目录： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:ListDataCatalogs" ], "Resource": "*" } ] } ``` **Example 对数据目录执行元数据操作的策略示例** 以下策略允许对数据目录执行元数据操作： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:GetDatabase", "athena:GetTableMetadata", "athena:ListDatabases", "athena:ListTableMetadata" ], "Resource": "*" } ] } ``` # 在 Athena 控制台中使用表单添加 AWS Glue 表 以下过程演示了如何使用 Athena 控制台通过**根据 S3 存储桶数据创建表**表单添加表。 **使用表单添加表并输入架构信息** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 在查询编辑器中，选择 **Tables and views**（表和视图）旁边的 **Create**（创建），然后选择 **S3 bucket data**（S3 存储桶数据）。 1. 在**根据 S3 存储桶数据创建表**表单中，对于 **Table name**（表名称），输入表的名称。有关 Athena 中可接受的数据库名称、表名以及列名的字符的信息，请参阅[命名数据库、表和列](tables-databases-columns-names.md)。 1. 对于 **Database configuration**（数据库配置），选择现有数据库或新建一个数据库。 1. 对于 **Location of Input Data Set**（输入数据集的位置），在 Amazon S3 中指定包含要处理的数据集的文件夹的路径。请勿在路径中包含文件的名称。Athena 会扫描指定文件夹中的所有文件。如果您的数据已经分区（例如， s3://amzn-s3-demo-bucket/logs/year=2004/month=12/day=11/)，仅输入基本路径（例如 s3://amzn-s3-demo-bucket/logs/）。 1. 对于 **Data Format**（数据格式），请选择以下选项： + 对于**Table type**（表格类型），选择 **Apache Hive**、**Apache Iceberg** 或 **Delta Lake**。Athena 的默认表类型是 Apache Hive。有关在 Athena 中查询 Apache Iceberg 表的信息，请参阅 [查询 Apache Iceberg 表](querying-iceberg.md)。有关在 Athena 中使用 Delta Lake 表的信息，请参阅 [查询 Linux Foundation Delta Lake 表](delta-lake-tables.md)。 + 对于 **File format**（文件格式），选择您的数据将采用的文件或日志格式。 + 对于 **Text File with Custom Delimiters (带自定义分隔符的文本文件)** 选项，请指定 **Field terminator (字段终止符)**（即列分隔符）。您也可以指定用于标记数组类型结束的 **Collection terminator**（集合终止符）或用于标记映射数据类型结束的 **Collection terminator**（集合终止符）。 + **SerDe 库** – SerDe（串行器解串器）库用于解析特定的数据格式，以便 Athena 可以为其创建表。对于大多数格式，系统会为您选择默认 SerDe 库。对于以下格式，请根据您的需要选择库： + **Apache Web 日志** – 选择 **RegexSerDe** 或 **GrokSerDe** 库。对于 RegexSerDe，请在 **Regex definition**（正则表达式定义）框中提供一个正则表达式。对于 GrokSerDe，为 `input.format` SerDe 属性提供一个已命名正则表达式系列。已命名正则表达式比正则表达式更便于阅读和维护。有关更多信息，请参阅 [查询存储在 Amazon S3 中的 Apache 日志](querying-apache-logs.md)。 + **CSV** – 如果以逗号分隔的数据不包含用双引号括起的值或者使用 `java.sql.Timestamp` 格式，请选择 **LazySimpleSerDe**。如果数据包含引号或为使用 UNIX 数字格式的 `TIMESTAMP`（例如，`1564610311`）时，请选择 **OpenCSVSerDe**。有关更多信息，请参阅[用于 CSV、TSV 和自定义分隔文件的 Lazy Simple SerDe](lazy-simple-serde.md)和[用于处理 CSV 的 Open CSV SerDe](csv-serde.md)。 + **JSON** – 选择 **OpenX** 或 **Hive** JSON SerDe 库。这两种格式都要求每个 JSON 文档均位于单行文本中，并且不使用换行字符分隔字段。OpenX SerDe 提供了一些额外的属性。有关这些属性的更多信息，请参阅[OpenX JSON SerDe](openx-json-serde.md)。有关 Hive SerDe 的多信息，请参阅 [Hive JSON SerDe](hive-json-serde.md)。 有关在 Athena 中使用 SerDe 库的更多信息，请参阅 [为您的数据选择 SerDE](supported-serdes.md)。 1. 对于 **SerDe properties**（SerDe 属性），请根据您使用的 SerDe 库以及您的需求添加、编辑或移除属性及值。 + 要添加 SerDe 属性，请选择**Add SerDe property**（添加 SerDe 属性）。 + 在 **Name**（名称）字段中，输入属性的名称。 + 在 **Value**（值）字段中，输入属性的值。 + 要移除 SerDe 属性，请选择 **Remove**（移除）。 1. 对于 **Table properties**（表属性），请根据您的需要选择或编辑表属性。 + 对于 **Write compression**（写入压缩），选择一个压缩选项。写入压缩选项以及可用压缩选项的可用性取决于数据格式。有关更多信息，请参阅 [在 Athena 中使用压缩](compression-formats.md)。 + 对于 **Encryption**（加密），如果基础数据已在 Amazon S3 中加密，则选择 **Encrypted data set**（加密数据集）。此选项在 `CREATE TABLE` 语句中会将 `has_encrypted_data` 表属性设置为 true。 1. 对于 **Column details**（列详细信息），输入要添加到表中的列名称和数据类型。 + 要添加更多列（一次添加一列），请选择 **Add a column (添加列)**。 + 要快速添加更多列，请选择 **Bulk add columns (批量添加列)**。在文本框中，输入以逗号分隔的列列表，格式为 *column\$1name* *data\$1type*, *column\$1name* *data\$1type*[,…]，然后选择 **Add**（添加）。 1. （可选）对于 **Partition details**（分区详情），添加一个或多个列名称和数据类型。分区会根据列值将相关数据组合在一起，这可帮助减少每次查询扫描的数据量。有关分区的信息，请参阅 [对您的数据进行分区](partitions.md)。 1. （可选）对于 **Bucketing**（分桶），您可以指定包含要组合在一起的行的一列或多列，然后将这些行放入多个桶中。这让您能够在指定分桶列值时仅查询要读取的桶。 + 对于 **Buckets**（桶），选择一个或多个具有大量唯一值（例如，主键）且经常用于筛选查询中数据的列。 + 对于 **Number of buckets**（桶数量），输入可优化文件大小的数字。有关更多信息，请参阅 AWS 大数据博客中的 [Top 10 Performance Tuning Tips for Amazon Athena](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)（Amazon Athena 的十大性能优化技巧）。 + 要指定分桶列，`CREATE TABLE` 语句将使用以下语法： ``` CLUSTERED BY (bucketed_columns) INTO number_of_buckets BUCKETS ``` **注意** **Bucketing**（分桶）选项不适用于 **Iceberg** 表类型。 1. **Preview table query**（预览表查询）方框显示您在表单中输入的信息所生成的 `CREATE TABLE` 语句。无法直接编辑预览语句。要更改语句，请修改预览部分以上的表单字段，或在查询编辑器中 [直接创建语句](creating-tables-how-to.md#to-create-a-table-using-hive-ddl)，而不使用表单。 1. 选择 **Create table**（创建表），在查询编辑器中运行生成的语句并创建表。 # 使用爬网程序添加表 AWS Glue 爬网程序可帮助发现数据集的架构，并在 AWS Glue Data Catalog 中将其注册为表。爬网程序会遍历您的数据并确定架构。此外，爬网程序还可以检测并注册分区。有关更多信息，请参阅《AWS Glue 开发人员指南**》中的[定义爬网程序](https://docs.aws.amazon.com/glue/latest/dg/add-crawler.html)。可以从 Athena 查询成功抓取的数据中的表。 **注意** Athena 不承认您为 AWS Glue 爬网程序指定的[排除模式](https://docs.aws.amazon.com/glue/latest/dg/define-crawler.html#crawler-data-stores-exclude)。例如，如果您有一个 Amazon S3 存储桶，其中包含 `.csv` 和 `.json` 文件，并且您从爬网程序中排除了 `.json` 文件时，Athena 会查询两组文件。要避免这种情况，请将要排除的文件放置在其他位置。 ## 创建 AWS Glue 爬网程序 您可以通过在 Athena 控制台中启动，然后以集成方式使用 AWS Glue 控制台来创建爬网程序。创建爬网程序时，您可以在 Amazon S3 中指定要爬取的数据位置。 **在 AWS Glue 中从 Athena 控制台开始创建爬网程序** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 在查询编辑器中，选择 **Tables and views**（表和视图）旁的 **Create**（创建），然后选择 **AWS Glue crawler**（爬网程序）。 1. 在 **AWS Glue** 控制台的 **Add crawler (添加爬网程序)** 页面上，按照步骤创建爬网程序。有关更多信息，请参阅本指南中的[使用 AWS Glue 爬网程序](#schema-crawlers)和《*AWS Glue 开发人员指南*》中的[填充 AWS Glue Data Catalog](https://docs.aws.amazon.com/glue/latest/dg/populate-catalog-methods.html)。 **注意** Athena 不承认您为 AWS Glue 爬网程序指定的[排除模式](https://docs.aws.amazon.com/glue/latest/dg/define-crawler.html#crawler-data-stores-exclude)。例如，如果您有一个 Amazon S3 存储桶，其中包含 `.csv` 和 `.json` 文件，并且您从爬网程序中排除了 `.json` 文件时，Athena 会查询两组文件。要避免这种情况，请将要排除的文件放置在其他位置。 在爬取之后，AWS Glue 爬网程序会自动分配某些表元数据，以帮助它与其他外部技术（如 Apache Hive、Presto 和 Spark）兼容。有时，爬网程序可能会错误地分配元数据属性。在使用 Athena 查询表之前，手动更正 AWS Glue 中的属性。有关更多信息，请参阅《AWS Glue 开发人员指南**》中的[查看和编辑表详细信息](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html#console-tables-details)。 当 CSV 文件将每个数据字段都用引号引起来，使 `serializationLib` 属性错误时，AWS Glue 可能会错误分配元数据。有关更多信息，请参阅 [处理引号中包含的 CSV 数据](schema-csv.md#schema-csv-quotes)。 # 将多个数据源和爬网程序结合使用 当 AWS Glue 爬网程序扫描 Amazon S3 并检测到多个目录时，它会使用启发法来确定表的根在目录结构中的位置，以及表的分区所在的目录。在某些情况下，如果在两个或更多目录中检测到的架构相似，则爬网程序可能将它们视为分区而不是单独的表。一种帮助爬网程序发现单个表的方法是将每个表的根目录添加为爬网程序的数据存储。 以下示例是 Amazon S3 中的分区： ``` s3://amzn-s3-demo-bucket/folder1/table1/partition1/file.txt s3://amzn-s3-demo-bucket/folder1/table1/partition2/file.txt s3://amzn-s3-demo-bucket/folder1/table1/partition3/file.txt s3://amzn-s3-demo-bucket/folder1/table2/partition4/file.txt s3://amzn-s3-demo-bucket/folder1/table2/partition5/file.txt ``` 如果 `table1` 和 `table2` 的架构类似，并且单个数据源在 AWS Glue 中设置为 `s3://amzn-s3-demo-bucket/folder1/`，则爬网程序可能创建一个具有两个分区列的表：一个分区列包含 `table1` 和 `table2`，另一个分区列包含 `partition1` 到 `partition5`。 要让 AWS Glue 爬网程序创建两个单独的表，请将爬网程序设置为具有两个数据源 `s3://amzn-s3-demo-bucket/folder1/table1/` 和 `s3://amzn-s3-demo-bucket/folder1/table2`，如以下过程所示。 **向 AWS Glue 中的现有爬网程序中添加 S3 数据存储** 1. 登录 AWS 管理控制台，然后打开 AWS Glue 控制台，网址为：[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)。 1. 在导航窗格中，选择 **爬网程序**。 1. 选择指向爬网程序的链接，然后选择 **Edit**（编辑）。 1. 对于**步骤 2：选择数据源和分类器**，选择 **Edit**（编辑）。 1. 对于**数据来源和目录**，选择**添加数据来源**。 1. 在 **Add data source**（添加数据来源）对话框中，对于 **S3 path**（S3 路径），选择 **Browse**（浏览）。 1. 选择要使用的计划，然后选择 **Choose**（选择）。 您添加的数据来源显示在 **Data sources**（数据来源）列表中。 1. 选择**下一步**。 1. 在 **Configure security settings**（配置安全设置）页面中，创建或选择爬网程序的 IAM 角色，然后选择 **Next**（下一步）。 1. 确保 S3 路径以斜杠结尾，然后选择 **Add an S3 data source**（添加 S3 数据来源）。 1. 在 **Set output and scheduling**（设置输出和计划）页面中，对于 **Output configuration**（输出配置），选择目标数据库。 1. 选择**下一步**。 1. 在 **Review and update**（审核和更新）页面中，查看您所做的选择。要编辑步骤，请选择 **Edit**（编辑）。 1. 选择**更新**。 # 安排爬网程序以保持 AWS Glue Data Catalog 和 Amazon S3 同步 AWS Glue 爬网程序可以设置为按计划或按需运行。有关更多信息，请参阅《AWS Glue 开发人员指南**》中的[基于时间的任务和爬网程序安排](https://docs.aws.amazon.com/glue/latest/dg/monitor-data-warehouse-schedule.html)。 如果您的数据在固定时间到达分区表，则可以设置 AWS Glue 爬网程序按计划运行以检测和更新表分区。这样就不需要运行耗时长且昂贵的 `MSCK REPAIR` 命令或手动运行 `ALTER TABLE ADD PARTITION` 命令。有关更多信息，请参阅《AWS Glue 开发人员指南**》中的[表分区](https://docs.aws.amazon.com/glue/latest/dg/tables-described.html#tables-partition)。 # 使用 AWS Glue 分区索引和筛选来优化查询 在 Athena 查询分区表时，其会检索可用的表分区并筛选出与查询相关的子集。随着新数据和分区的添加，处理分区需要更多时间，查询运行时间可能会增加。如果您的表包含随着时间的推移而增长的大量分区，请考虑使用 AWS Glue 分区索引和筛选。使用分区索引，Athena 可以优化分区处理并提升高度分区表的查询性能。在表的属性中设置分区筛选包括两个步骤： 1. 在 AWS Glue 中创建分区索引。 1. 为表启用分区筛选。 ## 创建分区索引 有关在 AWS Glue 中创建分区索引的步骤，请参阅《AWS Glue 开发人员指南》中的[使用分区索引](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)。有关 AWS Glue 中对分区索引的限制，请参阅该页面上的[关于分区索引](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html#partition-index-1)部分。 ## 启用分区筛选 要为表启用分区筛选，必须在 AWS Glue 中设置新的表属性。有关如何在 AWS Glue 中设置表属性的步骤，请参阅[设置分区投影](https://docs.aws.amazon.com/athena/latest/ug/partition-projection-setting-up.html)页面。当您在 AWS Glue 中编辑表详细信息时，将以下键值对添加到 **Table properties**（表属性）部分： + 对于 **Key**（键），请添加 `partition_filtering.enabled` + 对于 **Value**（值），请添加 `true` 您可以随时通过将 `partition_filtering.enabled` 值设置为 `false` 来对此表禁用分区筛选。 完成上述步骤后，您可以返回 Athena 控制台查询数据。 有关使用分区索引和筛选的更多信息，请参阅 *AWS 大数据博客*中的[使用 AWS Glue Data Catalog 分区索引提高 Amazon Athena 查询性能](https://aws.amazon.com/blogs/big-data/improve-amazon-athena-query-performance-using-aws-glue-data-catalog-partition-indexes/)。 # 使用 AWS CLI 重新创建 AWS Glue 数据库及其表 无法直接重命名 AWS Glue 数据库，但可以复制其定义，修改定义，然后使用该定义重新创建具有其他名称的数据库。同样，您可以复制旧数据库中的表定义，修改定义，然后使用修改后的定义在新数据库中重新创建表。 **注意** 所提供的方法不会复制表分区。 适用于 Windows 的以下过程假设 AWS CLI 已针对 JSON 输出进行配置。要更改 AWS CLI 中的默认输出格式，运行 `aws configure`。 **使用 AWS CLI 复制 AWS Glue 数据库** 1. 在命令提示符处，运行以下 AWS CLI 命令检索要复制的 AWS Glue 数据库的定义。 ``` aws glue get-database --name database_name ``` 有关 `get-database` 命令的更多信息，请参阅 [get-database](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-database.html)。 1. 将 JSON 输出保存到桌面上以新数据库名称命名的文件中（例如，`new_database_name.json`）。 1. 在文本编辑器中打开 `new_database_name.json` 文件。 1. 在 JSON 文件中，执行以下步骤： 1. 移除文件末尾的外部 `{ "Database":` 条目和相应的右大括号 `}`。 1. 将 `Name` 条目更改为新的数据库名称。 1. 删除 `CatalogId` 字段。 1. 保存该文件。 1. 在命令提示符处，运行以下 AWS CLI 命令使用修改后的数据库定义文件创建具有新名称的数据库。 ``` aws glue create-database --database-input "file://~/Desktop\new_database_name.json" ``` 有关 `create-database` 命令的更多信息，请参阅 [create-database](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/create-database.html)。有关从文件中加载 AWS CLI 参数的更多信息，请参阅《*AWS Command Line Interface 用户指南*》中的[从文件中加载 AWS CLI 参数](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html)。 1. 要验证是否已在 AWS Glue 中创建新数据库，请运行以下命令： ``` aws glue get-database --name new_database_name ``` 现在，您可以随时获取要复制到新数据库的表的定义，修改定义，然后使用修改后的定义在新数据库中重新创建表。此过程不会更改表名称。 **使用 AWS CLI 复制 AWS Glue 表** 1. 在命令提示符处，运行以下 AWS CLI 命令。 ``` aws glue get-table --database-name database_name --name table_name ``` 有关 `get-table` 命令的更多信息，请参阅 [get-table](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-table.html)。 1. 将 JSON 输出保存到 Windows 桌面上以表名称命名的文件中（例如，*table\$1name*.json）。 1. 在文本编辑器中打开该文件。 1. 在 JSON 文件中，移除文件末尾的外部 `{"Table": ` 条目和相应的右大括号 `}`。 1. 在 JSON 文件中，移除以下条目及其值： + `DatabaseName` - 此条目不是必需项，因为 `create-table` CLI 命令使用 `--database-name` 参数。 + `CreateTime` + `UpdateTime` + `CreatedBy` + `IsRegisteredWithLakeFormation` + `CatalogId` + `VersionId` 1. 保存表定义文件。 1. 在命令提示符处，运行以下 AWS CLI 命令在新数据库中重新创建表： ``` aws glue create-table --database-name new_database_name --table-input "file://~/Desktop\table_name.json" ``` 有关 `create-table` 命令的更多信息，请参阅 [create-table](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/create-table.html)。 现在，该表出现在 AWS Glue 的新数据库中，可以从 Athena 进行查询。 1. 重复上述步骤，将每个附加表复制到 AWS Glue 的新数据库中。 # 为 ETL 作业创建表 可以使用 Athena 来创建 AWS Glue 可用于 ETL 作业的表。AWS Glue 作业执行 ETL 操作。AWS Glue 任务运行一个从源中提取数据、转换数据并将其加载到目标中的脚本。有关更多信息，请参阅《AWS Glue 开发人员指南》中的[在 AWS Glue 中编写任务](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)。 ## 为 AWS Glue ETL 作业创建 Athena 表 您在 Athena 中创建的表必须添加有名为 `classification` 的表属性，该属性标识数据的格式。这使 AWS Glue 能够将这些表用于 ETL 任务。分类值可以是 `avro`、`csv`、`json`、`orc`、`parquet` 或 `xml`。下面是 Athena 中的示例 `CREATE TABLE` 语句： ``` CREATE EXTERNAL TABLE sampleTable ( column1 INT, column2 INT ) STORED AS PARQUET TBLPROPERTIES ( 'classification'='parquet') ``` 如果在创建表时未添加 `classification` 表属性，则可以使用 AWS Glue 控制台添加它。 **使用 AWS Glue 控制台添加分类表属性** 1. 登录 AWS 管理控制台，然后打开 AWS Glue 控制台，网址为：[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)。 1. 在控制台导航窗格中。选择 **Tables**（表）。 1. 选择您要编辑的表的链接，然后依次选择 **Action**（操作）、**Edit table**（编辑表）。 1. 向下滚动到 **Table properties**（表属性）部分。 1. 选择**添加**。 1. 对于**键**，输入 **classification**。 1. 对于 **Value**（值），输入数据类型（例如 **json**)。 1. 选择**保存**。 在 **Table details**（表详细信息）部分中，您输入的数据类型显示在表的 **Classification**（分类）字段中。 有关更多信息，请参阅《AWS Glue 开发人员指南**》中的[使用表](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html)。 ## 使用 ETL 作业优化查询性能 AWS Glue 任务可帮助您将数据转换为一种可优化 Athena 中的查询性能的格式。数据格式会极大影响 Athena 中的查询性能和查询成本。 AWS Glue 支持写入 Parquet 和 ORC 数据格式。可以使用此功能来转换数据以在 Athena 中使用。有关使用 Parquet 和 ORC 以及提高 Athena 性能的其他方法的更多信息，请参阅 [Top 10 performance tuning tips for Amazon Athena](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)。 **注意** 要减少 Athena 无法读取 AWS Glue ETL 作业生成的 `SMALLINT` 和 `TINYINT` 数据类型的可能性，请在创建将数据转换为 ORC 的 ETL 作业时，将 `SMALLINT` 和 `TINYINT` 转换为 `INT`。 ## 为 ETL 自动执行 AWS Glue 作业 您可以将 AWS Glue ETL 任务配置为基于触发器自动运行。当来自 AWS 外部的数据被以次优格式推送到 Amazon S3 存储桶以便在 Athena 中查询时，此功能非常适用。有关更多信息，请参阅《AWS Glue 开发人员指南**》中的[触发 AWS Glue 任务](https://docs.aws.amazon.com/glue/latest/dg/trigger-job.html)。 # 使用 AWS Glue 中的 CSV 数据 本页介绍了如何使用 AWS Glue 从在每列数据值前后加引号的 CSV 文件或包含标题值的 CSV 文件创建架构。 ## 处理引号中包含的 CSV 数据 假设 CSV 文件的数据字段用双引号括起来，如下例所示。 ``` "John","Doe","123-555-1231","John said \"hello\"" "Jane","Doe","123-555-9876","Jane said \"hello\"" ``` 要在 Athena 中对使用具有引号值的 CSV 文件创建的表运行查询，必须修改 AWS Glue 中的表属性以使用 OpenCSVSerDe。有关 OpenCSV SerDe 的更多信息，请参阅 [用于处理 CSV 的 Open CSV SerDe](csv-serde.md)。 **要在 AWS Glue 控制台中编辑表属性** 1. 在 AWS Glue 控制台中，选择导航窗格中的 **Tables**（表）。 1. 选择您要编辑的表的链接，然后依次选择 **Action**（操作）、**Edit table**（编辑表）。 1. 在 **Edit table**（编辑表）页面上，进行以下更改： + 对于 **Serialization lib**（序列化库），输入 `org.apache.hadoop.hive.serde2.OpenCSVSerde`。 + 对于 **Serde parameters**（SerDe 参数），为键 `escapeChar`、`quoteChar` 和 `separatorChar` 输入以下值： + 对于 `escapeChar`，输入一个反斜杠 (**\$1**)。 + 对于 `quoteChar`，输入一个双引号 (**"**)。 + 对于 `separatorChar`，输入一个逗号 (**,**)。 1. 选择**保存**。 有关更多信息，请参阅《AWS Glue 开发人员指南**》中的[查看和编辑表详细信息](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html#console-tables-details)。 也可以通过编程方式更新 AWS Glue 表属性。使用 AWS Glue [UpdateTable](https://docs.aws.amazon.com/glue/latest/webapi/API_UpdateTable.html) API 操作或 [update-table](https://docs.aws.amazon.com/cli/latest/reference/glue/update-table.html) AWS CLI 命令来修改表定义中的 `SerDeInfo` 块，如以下示例 JSON 所示。 ``` "SerDeInfo": { "name": "", "serializationLib": "org.apache.hadoop.hive.serde2.OpenCSVSerde", "parameters": { "separatorChar": "," "quoteChar": "\"" "escapeChar": "\\" } }, ``` ## 处理具有标题的 CSV 文件 当您在 Athena 中使用 `CREATE TABLE` 语句定义一个表时，可以使用 `skip.header.line.count` 表属性以忽略 CSV 数据中的标题，如下例所示。 ``` ... STORED AS TEXTFILE LOCATION 's3://amzn-s3-demo-bucket/csvdata_folder/'; TBLPROPERTIES ("skip.header.line.count"="1") ``` 或者，您可以事先删除 CSV 标题，以便不将标题信息包含在 Athena 查询结果中。实现此操作的一种方法是使用 AWS Glue 任务，它执行提取、转换和加载 (ETL) 工作。您可以使用 PySpark Python 方言的扩展语言在 AWS Glue 中编写脚本。有关更多信息，请参阅《AWS Glue 开发人员指南》中的[在 AWS Glue 中编写任务](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)。 以下示例显示 AWS Glue 脚本中的一个函数，它使用 `from_options` 写出动态帧，并将 `writeHeader` 格式选项设置为 false，从而删除标题信息： ``` glueContext.write_dynamic_frame.from_options(frame = applymapping1, connection_type = "s3", connection_options = {"path": "s3://amzn-s3-demo-bucket/MYTABLEDATA/"}, format = "csv", format_options = {"writeHeader": False}, transformation_ctx = "datasink2") ``` # 使用 AWS Glue 中的地理空间数据 AWS Glue 不内在支持已知文本 (WKT)、已知二进制 (WKB) 或其他 PostGIS 数据类型。AWS Glue 分类器解析地理空间数据并使用相应格式支持的数据类型对其进行分类，例如用于 CSV 的 `varchar`。与其他 AWS Glue 表一样，您可能需要更新从地理空间数据创建的表的属性，以允许 Athena 按原样解析这些数据类型。有关更多信息，请参阅 [使用爬网程序添加表](schema-crawlers.md) 和 [使用 AWS Glue 中的 CSV 数据](schema-csv.md)。Athena 可能无法按原样解析 AWS Glue 表中的某些地理空间数据类型。有关在 Athena 中使用地理空间数据的更多信息，请参阅[查询地理空间数据](querying-geospatial-data.md)。 # 使用 Amazon Athena 联合查询 如果您在 Amazon S3 以外的源中拥有数据，则可以使用 Athena Federated Query 来查询数据或构建从多个数据来源提取数据并将其存储在 Amazon S3 中的管道。通过 Athena Federated Query，您可以对存储在关系数据来源、非关系数据来源、对象数据来源和自定义数据来源中的数据运行 SQL 查询。 Athena 使用在 AWS Lambda 上运行的*数据来源连接器*来运行联合查询。数据来源连接器是一段代码，可以在目标数据来源和 Athena 之间进行转换。您可以将连接器视为 Athena 查询引擎的扩展。使用 Apache 2.0 许可证的 Amazon CloudWatch Logs、Amazon DynamoDB、Amazon DocumentDB 和 Amazon RDS 等数据来源以及 MySQL 和 PostgreSQL 等兼容 JDBC 的关系数据来源中存在预构建的 Athena 数据来源连接器。您还可以使用 Athena Query Federation SDK 编写自定义连接器。要选择、配置数据来源连接器并将其部署到您的账户，可以使用 Athena 和 Lambda 控制台或 AWS Serverless Application Repository。部署数据来源连接器后，连接器将与可以在 SQL 查询中指定的目录相关联。您可以使用单个查询来组合来自多个目录的 SQL 语句和跨多个数据来源。 针对某个数据来源提交查询时，Athena 调用相应的连接器以识别需要读取的表部分、管理并行度以及下移筛选器谓词。根据提交查询的用户，连接器可以提供或限制对特定数据元素的访问。连接器使用 Apache Arrow 作为查询中请求的数据的返回格式，这使得连接器能够以 C、C\$1\$1、Java、Python 和 Rust 等语言实现。由于连接器在 Lambda 中处理，因此它们可用于访问来自云中的任何数据来源或可从 Lambda 访问的本地数据来源的数据。 要编写自己的数据来源连接器，您可以使用 Athena Query Federation SDK 自定义 Amazon Athena 提供和维护的预构建连接器之一。您可以修改来自 [GitHub 存储库](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors)的源代码的副本，然后使用[连接器发布工具](https://github.com/awslabs/aws-athena-query-federation/wiki/Connector_Publish_Tool)创建您自己的 AWS Serverless Application Repository 软件包。 **注意** 第三方开发人员可能已经使用 Athena Query Federation SDK 来写入数据来源连接器。有关这些数据来源连接器的支持或许可问题，请与您的连接器提供商联系。这些连接器不受 AWS 的测试或支持。 有关 Athena 编写和测试的数据来源连接器列表，请参阅 [可用数据来源连接器](connectors-available.md)。 有关编写自己的数据来源连接器的信息，请参阅 GitHub 上的 [Example Athena connector](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-example)。 ## 注意事项和限制 + **引擎版本**：Athena 联合查询仅在 Athena 引擎版本 2 及更高版本中受支持。有关 Athena 引擎版本的更多信息，请参阅 [Athena 引擎版本控制](engine-versions.md)。 + **视图** - 您可以创建和查询联合数据来源的视图。联合视图存储在 AWS Glue 中，而不是底层数据来源中。有关更多信息，请参阅 [查询联合视图](running-federated-queries.md#running-federated-queries-federated-views)。 + **分隔标识符**：分隔标识符（也称为“带引号的标识符”）以双引号 (") 开头和结尾。目前，Athena 联合查询不支持分隔标识符。 + **写入操作** – 写入操作不受支持，例如 [INSERT INTO](insert-into.md)。尝试这样做可能会导致出现错误消息 This operation is currently not supported for external catalogs（外部目录目前不支持此操作）。 + **定价** – 有关定价信息，请参阅 [Amazon Athena 定价](https://aws.amazon.com/athena/pricing/)。 + **JDBC 驱动程序**：若要将 JDBC 驱动程序与联合查询或[外部 Hive 元存储](connect-to-data-source-hive.md)结合使用，请在 JDBC 连接字符串中加入 `MetadataRetrievalMethod=ProxyAPI`。有关 JDBC 驱动程序的信息，请参阅 [通过 JDBC 连接到 Amazon Athena](connect-with-jdbc.md)。 + **Secrets Manager** – 要将 Athena Federated Query 功能与 AWS Secrets Manager 结合使用，您必须为 Secrets Manager 配置 Amazon VPC 私有端点。有关更多信息，请参阅《AWS Secrets Manager 用户指南**》中的 [创建 Secrets Manager VPC 私有端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)。 ## 所需权限 数据来源连接器可能需要访问以下资源才能正常工作。如果您使用预构建的连接器，请检查连接器的信息，以确保您已正确配置 VPC。此外，请确保运行查询和创建连接器的 IAM 主体具有执行所需操作的权限。有关更多信息，请参阅 [允许访问 Athena 联合查询：示例策略](federated-query-iam-access.md)。 + **Amazon S3** – 除了将查询结果写入 Amazon S3 中的 Athena 查询结果位置之外，数据连接器还会写入到 Amazon S3 中的溢出存储桶。此 Amazon S3 位置的连接和权限是必需的。我们建议为每个连接器使用磁盘溢写加密，并使用 [S3 生命周期配置](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)来使不再需要的溢写数据过期。 + **Athena**：数据来源需要连接到 Athena，反之亦然，以便检查查询状态并防止过扫描。 + **AWS Glue Data Catalog** – 如果连接器使用 Data Catalog 来获取补充元数据或主元数据，则需要连接和权限。 + **Amazon ECR** – 数据来源连接器 Lambda 函数使用来自 Amazon ECR 存储库的 Amazon ECR 映像。部署连接器的用户必须具有 `ecr:BatchGetImage` 和 `ecr:GetDownloadUrlForLayer` 权限。有关更多信息，请参阅《AWS Lambda 开发人员指南》**中的 [Amazon ECR 权限](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html#gettingstarted-images-permissions)。 ## 视频 观看以下视频，了解有关使用 Athena Federated Query 的更多信息。 **视频：在 Quick 中分析 Amazon Athena 中的联合查询结果** 以下视频说明了如何在 Quick 中分析 Athena 联合查询的结果。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/HyM5d0TmwAQ/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/HyM5d0TmwAQ) **视频：Gaming Analytics Pipeline** 以下视频演示了如何部署可扩展的无服务器数据管道，以便使用 Amazon Athena 联合查询从游戏和服务中获取、存储和分析遥测数据。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/xcS-flUMVbs/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/xcS-flUMVbs) # 可用数据来源连接器 本节列出了可用于查询 Amazon S3 外部的各种数据来源的预构建 Athena 数据来源连接器。要在 Athena 查询中使用连接器，请对其进行配置并部署到您的账户。 ## 注意事项和限制 + 一些预构建连接器需要您先创建 VPC 和安全组，才能使用该连接器。有关创建 VPC 的信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 + 若要将 Athena Federated Query 功能与 AWS Secrets Manager 结合使用，您必须为 Secrets Manager 配置 Amazon VPC 私有端点。有关更多信息，请参阅《AWS Secrets Manager 用户指南**》中的 [创建 Secrets Manager VPC 私有端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)。 + 对于不支持谓词下推的连接器，执行包含谓词的查询花费的时间会更长。对于小型数据集，扫描的数据很少，因而查询平均需要大约 2 分钟。但是，对于大型数据集，许多查询可能会超时。 + 一些联合数据来源使用术语来指代与 Athena 不同的数据对象。有关更多信息，请参阅 [了解联合表名限定词](tables-qualifiers.md)。 + 根据数据库或数据来源提供商的升级，我们会定期更新连接器。我们不支持生命周期已结束的数据来源。 + 对于在您列出表时不支持分页的连接器，如果您的数据库中有许多表和元数据，Web 服务可能会超时。以下连接器为列出表提供分页支持： + DocumentDB + DynamoDB + MySQL + OpenSearch + Oracle + PostgreSQL + Redshift + SQL Server ## Federation SDK 中的大小写解析器模式 Federation SDK 支持架构和表名的以下标准化大小写解析器模式： + `NONE`：不更改给定架构和表名的大小写。 + `LOWER`：所有给定的架构和表名全部小写。 + `UPPER`：所有给定的架构和表名全部大写。 + `ANNOTATION`：此模式仅为向后兼容而保留，并且仅由现有的 Snowflake 和 SAP HANA 连接器支持。 + `CASE_INSENSITIVE_SEARCH`：对架构和表名执行不区分大小写的搜索。 ## 支持大小写解析器模式的连接器 ### 基本模式支持 所有 JDBC 连接器都支持以下基本模式： + `NONE` + `LOWER` + `UPPER` ### 注释模式支持 只有以下连接器支持 `ANNOTATION` 模式： + Snowflake + SAP HANA **注意** 建议使用 CASE\$1INSENSITIVE\$1SEARCH 而不是 ANNOTATION。 ### 不区分大小写的搜索支持 以下连接器支持 `CASE_INSENSITIVE_SEARCH`： + DataLake Gen2 + Snowflake + Oracle + Synapse + MySQL + PostgreSQL + Redshift + ClickHouse + SQL Server + DB2 ## 大小写解析器限制 使用大小写解析器模式时，请注意以下限制： + 使用 `LOWER` 模式时，架构名称和架构中所有表都必须为小写。 + 使用 `UPPER` 模式时，架构名称和架构中所有表都必须为大写。 + 使用 `CASE_INSENSITIVE_SEARCH` 时： + 架构名称必须唯一 + 架构中的表名必须唯一（例如，不能同时使用“Apple”和“APPLE”） + Glue 集成限制： + Glue 仅支持小写名称 + 向 GlueDataCatalog/LakeFormation 注册 Lambda 函数时，仅支持 `NONE` 或 `LOWER` 模式 ## 附加信息 + 有关部署 Athena 数据来源连接器的信息，请参阅 [使用 Amazon Athena 联合查询](federated-queries.md)。 + 有关使用 Athena 数据来源连接器的查询的信息，请参阅 [运行联合查询](running-federated-queries.md)。 **Topics** + [注意事项和限制](#connectors-available-considerations) + [Federation SDK 中的大小写解析器模式](#case-resolver-modes) + [支持大小写解析器模式的连接器](#connector-support-matrix) + [大小写解析器限制](#case-resolver-limitations) + [附加信息](#connectors-available-additional-resources) + [Azure Data Lake 存储](connectors-adls-gen2.md) + [Azure Synapse](connectors-azure-synapse.md) + [Cloudera Hive](connectors-cloudera-hive.md) + [Cloudera Impala](connectors-cloudera-impala.md) + [CloudWatch](connectors-cloudwatch.md) + [CloudWatch 指标](connectors-cwmetrics.md) + [CMDB](connectors-cmdb.md) + [Db2](connectors-ibm-db2.md) + [Db2 iSeries](connectors-ibm-db2-as400.md) + [DocumentDB](connectors-docdb.md) + [DynamoDB](connectors-dynamodb.md) + [Google BigQuery](connectors-bigquery.md) + [Google Cloud Storage](connectors-gcs.md) + [HBase](connectors-hbase.md) + [Hortonworks](connectors-hortonworks.md) + [Kafka](connectors-kafka.md) + [MSK](connectors-msk.md) + [MySQL](connectors-mysql.md) + [Neptune](connectors-neptune.md) + [OpenSearch](connectors-opensearch.md) + [Oracle](connectors-oracle.md) + [PostgreSQL](connectors-postgresql.md) + [Redis OSS](connectors-redis.md) + [Redshift](connectors-redshift.md) + [SAP HANA](connectors-sap-hana.md) + [Snowflake](connectors-snowflake.md) + [SQL Server](connectors-microsoft-sql-server.md) + [Teradata](connectors-teradata.md) + [Timestream](connectors-timestream.md) + [TPC-DS](connectors-tpcds.md) + [Vertica](connectors-vertica.md) **注意** [AthenaJdbcConnector](https://serverlessrepo.aws.amazon.com/applications/us-east-1/292517598671/AthenaJdbcConnector)（最新版本 2022.4.1）已弃用。请改用特定于数据库的连接器，例如 [MySQL](connectors-mysql.md)、[Redshift](connectors-redshift.md) 或 [PostgreSQL](connectors-postgresql.md) 的连接器。 # Amazon Athena Azure Data Lake Storage（ADLS）Gen2 连接器 适用于 [Azure Data Lake Storage（ADLS）Gen2](https://docs.microsoft.com/en-us/azure/databricks/data/data-sources/azure/adls-gen2/) 的 Amazon Athena 连接器使 Amazon Athena 能够对存储在 ADLS 上的数据运行 SQL 查询。Athena 无法直接访问数据湖中存储的文件。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 + **工作流程** - 连接器实施 JDBC 接口，以使用 `com.microsoft.sqlserver.jdbc.SQLServerDriver` 驱动程序。连接器将查询传递给 Azure Synapse 引擎，以访问数据湖。 + **数据处理和 S3** - 通常，Lambda 连接器直接查询数据，无需传输到 Amazon S3。但是，如果 Lambda 函数返回的数据超过 Lambda 限值，该数据将写入指定 Amazon S3 溢出存储桶，这样 Athena 就可以读取多余的数据。 + **AAD 身份验证** - AAD 可用作 Azure Synapse 连接器的身份验证方法。要使用 AAD，连接器使用的 JDBC 连接字符串必须包含 URL 参数 `authentication=ActiveDirectoryServicePrincipal`、`AADSecurePrincipalId` 和 `AADSecurePrincipalSecret`。这些参数可以直接传入，也可以通过 Secrets Manager 传入。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 必须将筛选条件中的日期和时间戳数据类型转换为适当的数据类型。 ## 术语 以下术语与 Azure Data Lake Storage Gen2 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Azure Data Lake Storage Gen2 连接器。 **注意** 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 连接对象来配置 Azure Data Lake Storage Gen2 连接器。要执行此操作，请将 Azure Data Lake Storage Gen2 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type DATALAKEGEN2 ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Azure Data Lake Storage Gen2 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Azure Data Lake Storage Gen2 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` datalakegentwo://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | DataLakeGen2MuxCompositeHandler | | 元数据处理程序 | DataLakeGen2MuxMetadataHandler | | 记录处理程序 | DataLakeGen2MuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mydatalakegentwocatalog，则环境变量名称是 mydatalakegentwocatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 DataLakeGen2 MUX Lambda 函数：`datalakegentwo1`（默认）和 `datalakegentwo2`。 **** | 属性 | 值 | | --- | --- | | default | datalakegentwo://jdbc:sqlserver://adlsgentwo1.hostname:port;databaseName=database\$1name;\$1\$1secret1\$1name\$1 | | datalakegentwo\$1catalog1\$1connection\$1string | datalakegentwo://jdbc:sqlserver://adlsgentwo1.hostname:port;databaseName=database\$1name;\$1\$1secret1\$1name\$1 | | datalakegentwo\$1catalog2\$1connection\$1string | datalakegentwo://jdbc:sqlserver://adlsgentwo2.hostname:port;databaseName=database\$1name;\$1\$1secret2\$1name\$1 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${secret1_name}`。 ``` datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=database_name;${secret1_name} ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=database_name;user=user_name;password=password ``` #### 使用单个连接处理程序 您可以使用以下单一连接元数据和记录处理程序连接到单一 Azure Data Lake Storage Gen2 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | DataLakeGen2CompositeHandler | | 元数据处理程序 | DataLakeGen2MetadataHandler | | 记录处理程序 | DataLakeGen2RecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单一 Azure Data Lake Storage Gen2 实例。 **** | 属性 | 值 | | --- | --- | | default | datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 ADLS Gen2 和 Arrow 的相应数据类型。 **** | ADLS Gen2 | Arrow | | --- | --- | | bit | TINYINT | | tinyint | SMALLINT | | smallint | SMALLINT | | int | INT | | bigint | BIGINT | | decimal | DECIMAL | | numeric | FLOAT8 | | smallmoney | FLOAT8 | | money | DECIMAL | | float[24] | FLOAT4 | | float[53] | FLOAT8 | | real | FLOAT4 | | datetime | Date(MILLISECOND) | | datetime2 | Date(MILLISECOND) | | smalldatetime | Date(MILLISECOND) | | date | Date(DAY) | | 时间 | VARCHAR | | datetimeoffset | Date(MILLISECOND) | | char[n] | VARCHAR | | varchar[n/max] | VARCHAR | ## 分区和拆分 Azure Data Lake Storage Gen2 使用与 Hadoop 兼容的 Gen2 Blob 存储来存储数据文件。这些文件中的数据将从 Azure Synapse 引擎查询。Azure Synapse 引擎将存储在文件系统中的 Gen2 数据视为外部表。根据数据类型实施分区。如果已在 Gen2 存储系统中对数据进行了分区和分发，则该连接器将以单个拆分的形式检索数据。 ## 性能 当同时运行多个查询时，Azure Data Lake Storage Gen2 连接器的查询性能会变慢，并且会受到节流。 Azure Data Lake Storage Gen2 连接器可执行谓词下推，以减少查询扫描的数据量。简单谓词和复杂表达式将下推到连接器，以减少扫描的数据量并缩短查询执行的运行时间。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Azure Data Lake Storage Gen2 连接器可以组合这些表达式并将其直接推送到 Azure Data Lake Storage Gen2，以增强功能并减少扫描的数据量。 以下 Athena Azure Data Lake Storage Gen2 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 传递查询 Azure Data Lake Storage Gen2 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Azure Data Lake Storage Gen2 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Azure Data Lake Storage Gen2 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参阅 GitHub.com 上适用于 Azure Data Lake Storage Gen2 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-datalakegen2)。 # Amazon Athena Azure Synapse 连接器 适用于 [Azure Synapse Analytics](https://docs.microsoft.com/en-us/azure/synapse-analytics/overview-what-is) 的 Amazon Athena 连接器使 Amazon Athena 能够使用 JDBC 在您的 Azure Synapse 数据库上运行 SQL 查询。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出存储桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《AWS Lambda 开发人员指南》**中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 在筛选条件中，必须将 `Date` 和 `Timestamp` 数据类型转换为适当的数据类型。 + 要搜索类型 `Real` 和 `Float` 的负值，请使用 `<=` 或 `>=` 运算符。 + 不支持 `binary`、`varbinary`、`image` 和 `rowversion` 数据类型。 ## 术语 以下术语与 Synapse 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Synapse 连接器。 **注意** 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 连接对象来配置 Synapse 连接器。要执行此操作，请将 Synapse 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type SYNAPSE ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Synapse 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Synapse 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接（建议） #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` synapse://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | SynapseMuxCompositeHandler | | 元数据处理程序 | SynapseMuxMetadataHandler | | 记录处理程序 | SynapseMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mysynapsecatalog，则环境变量名称是 mysynapsecatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Synapse MUX Lambda 函数：`synapse1`（默认）和 `synapse2`。 **** | 属性 | 值 | | --- | --- | | default | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 | | synapse\$1catalog1\$1connection\$1string | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 | | synapse\$1catalog2\$1connection\$1string | synapse://jdbc:synapse://synapse2.hostname:port;databaseName=;\$1\$1secret2\$1name\$1 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 \$1\$1secret\$1name\$1。 ``` synapse://jdbc:synapse://hostname:port;databaseName=;${secret_name} ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` synapse://jdbc:synapse://hostname:port;databaseName=;user=;password= ``` #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Synapse 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | SynapseCompositeHandler | | 元数据处理程序 | SynapseMetadataHandler | | 记录处理程序 | SynapseRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 Synapse 实例。 **** | 属性 | 值 | | --- | --- | | default | synapse://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 | #### 配置 Active Directory 身份验证 Amazon Athena Azure Synapse 连接器支持 Microsoft Active Directory 身份验证。在开始之前，必须在 Microsoft Azure 门户中配置管理用户，然后使用 AWS Secrets Manager 创建密钥。 **设置 Active Directory 管理用户** 1. 使用具有管理权限的账户，登录 Microsoft Azure 门户，网址为 [https://portal.azure.com/](https://portal.azure.com/)。 1. 在搜索框中，输入 **Azure Synapse Analytics**，然后选择 **Azure Synapse Analytics**。 ![\[选择 Azure Synapse Analytics。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-azure-synapse-1.png) 1. 打开左侧菜单。 ![\[选择 Azure 门户菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-azure-synapse-2.png) 1. 在导航窗格中，选择 **Azure Active Directory**。 1. 在**设置管理员**选项卡中，将 **Active Directory 管理员**设置为新用户或现有用户。 ![\[使用设置管理员选项卡\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-azure-synapse-3.png) 1. 在 AWS Secrets Manager 中，存储管理员用户名和密码凭证。有关在 Secrets Manager 中创建密钥的信息，请参阅[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。 **在 Secrets Manager 中查看密钥** 1. 打开 Secrets Manager 控制台，网址为 [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。 1. 在导航窗格中，选择 **Secrets**（密钥）。 1. 在 **Secrets**（密钥）页面，选择密钥链接。 1. 在密钥的详细信息页面上，选择 **Retrieve secret value**（检索密钥值）。 ![\[在 AWS Secrets Manager 中查看密钥。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-azure-synapse-4.png) ##### 修改连接字符串 要为连接器启用 Active Directory 身份验证，使用以下语法修改连接字符串： ``` synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryPassword;{secret_name} ``` ##### 使用 ActiveDirectoryServicePrincipal Amazon Athena Azure Synapse 连接器还支持 `ActiveDirectoryServicePrincipal`。要启用此项，如下所示修改连接字符串。 ``` synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryServicePrincipal;{secret_name} ``` 对于 `secret_name`，将应用程序或客户端 ID 指定为用户名，并在密码中指定服务主体身份的密钥。 #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出存储桶名称。 | | spill\$1prefix | 必需。溢出存储桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 Synapse 和 Apache Arrow 的相应数据类型。 **** | Synapse | Arrow | | --- | --- | | bit | TINYINT | | tinyint | SMALLINT | | smallint | SMALLINT | | int | INT | | bigint | BIGINT | | decimal | DECIMAL | | numeric | FLOAT8 | | smallmoney | FLOAT8 | | money | DECIMAL | | float[24] | FLOAT4 | | float[53] | FLOAT8 | | real | FLOAT4 | | datetime | Date(MILLISECOND) | | datetime2 | Date(MILLISECOND) | | smalldatetime | Date(MILLISECOND) | | date | Date(DAY) | | 时间 | VARCHAR | | datetimeoffset | Date(MILLISECOND) | | char[n] | VARCHAR | | varchar[n/max] | VARCHAR | | nchar[n] | VARCHAR | | nvarchar[n/max] | VARCHAR | ## 分区和拆分 分区由类型为 `varchar` 的单个分区列表示。Synapse 支持范围分区，因此分区通过从 Synapse 元数据表中提取分区列和分区范围来实现。这些范围值用于创建拆分。 ## 性能 选择列的子集会显著减少查询运行时。由于并发，连接器显示出严重的节流。 Athena Synapse 连接器可执行谓词下推，以减少查询扫描的数据量。简单谓词和复杂表达式将下推到连接器，以减少扫描的数据量并缩短查询执行的运行时间。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Synapse 连接器可以组合这些表达式并将其直接推送到 Synapse，以增强功能并减少扫描的数据量。 以下 Athena Synapse 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 传递查询 Synapse 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Synapse 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Synapse 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 + 有关介绍如何使用 Quick 和 Amazon Athena 联合查询对存储在 Microsoft Azure Synapse 数据库中的数据构建控制面板和可视化的文章，请参阅 *AWS 大数据博客*中的 [Perform multi-cloud analytics using Quick, Amazon Athena Federated Query, and Microsoft Azure Synapse](https://aws.amazon.com/blogs/business-intelligence/perform-multi-cloud-analytics-using-amazon-quicksight-amazon-athena-federated-query-and-microsoft-azure-synapse/)。 + 有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 Synapse 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/pom.xml) 文件。 + 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-synapse)。 # Amazon Athena Cloudera Hive 连接器 适用于 Cloudera Hive 的 Amazon Athena 连接器使 Athena 能够对 [Cloudera Hive](https://www.cloudera.com/products/open-source/apache-hadoop/apache-hive.html) Hadoop 分配运行 SQL 查询。该连接器会将您的 Athena SQL 查询转换为其等效的 HiveQL 语法。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 + 使用此连接器前，请先设置 VPC 和安全组。有关更多信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 ## 术语 以下术语与 Cloudera Hive 连接器有关。 + **数据库实例** - 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Cloudera Hive 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Cloudera Hive 连接器。要执行此操作，请将 Cloudera Hive 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type CLOUDERAHIVE ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Cloudera Hive 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Cloudera Hive 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` hive://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | HiveMuxCompositeHandler | | 元数据处理程序 | HiveMuxMetadataHandler | | 记录处理程序 | HiveMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myhivecatalog，则环境变量名称是 myhivecatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Hive MUX Lambda 函数：`hive1`（默认）和 `hive2`。 **** | 属性 | 值 | | --- | --- | | default | hive://jdbc:hive2://hive1:10000/default;\$1\$1Test/RDS/hive1\$1 | | hive2\$1catalog1\$1connection\$1string | hive://jdbc:hive2://hive1:10000/default;\$1\$1Test/RDS/hive1\$1 | | hive2\$1catalog2\$1connection\$1string | hive://jdbc:hive2://hive2:10000/default;UID=sample&PWD=sample | ##### 提供 凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，Cloudera Hive 连接器需要来自 AWS Secrets Manager 的密钥。要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/hive1}`。 ``` hive://jdbc:hive2://hive1:10000/default;...&${Test/RDS/hive1}&... ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` hive://jdbc:hive2://hive1:10000/default;...&UID=sample2&PWD=sample2&... ``` 目前，Cloudera Hive 连接器可以识别 `UID` 和 `PWD` JDBC 属性。 #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Cloudera Hive 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | HiveCompositeHandler | | 元数据处理程序 | HiveMetadataHandler | | 记录处理程序 | HiveRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 Cloudera Hive 实例。 **** | 属性 | 值 | | --- | --- | | 默认 | hive://jdbc:hive2://hive1:10000/default;secret=\$1\$1Test/RDS/hive1\$1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC、Cloudera Hive 和 Arrow 的相应数据类型。 **** | JDBC | Cloudera Hive | Arrow | | --- | --- | --- | | 布尔值 | 布尔值 | Bit | | 整数 | TINYINT | Tiny | | 短型 | SMALLINT | Smallint | | 整数 | INT | Int | | 长整型 | BIGINT | Bigint | | 浮点数 | float4 | Float4 | | 双精度 | float8 | Float8 | | 日期 | date | DateDay | | Timestamp | timestamp | DateMilli | | 字符串 | VARCHAR | Varchar | | 字节 | bytes | Varbinary | | BigDecimal | 十进制 | 十进制 | | ARRAY | 不适用（见注释） | 列表 | **注意** 目前，Cloudera Hive 不支持聚合类型 `ARRAY`、`MAP`、`STRUCT` 或 `UNIONTYPE`。聚合类型的列被视为 SQL 中的 `VARCHAR` 列。 ## 分区和拆分 分区用于确定如何为该连接器生成拆分。Athena 将构建一个 `varchar` 类型的合成列，它将展示表的分区方案，以帮助该连接器生成拆分。该连接器不会修改实际的表定义。 ## 性能 Cloudera Hive 支持静态分区。Athena Cloudera Hive 连接器可从这些分区并行检索数据。如果您想查询具有均匀分区分布的非常大的数据集，强烈建议使用静态分区。Cloudera Hive 连接器能够灵活地应对并发造成的节流。 Athena Cloudera Hive 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Cloudera Hive 连接器可以组合这些表达式并将其直接推送到 Cloudera Hive，以增强功能并减少扫描的数据量。 以下 Athena Cloudera Hive 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 传递查询 Cloudera Hive 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Cloudera Hive 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Cloudera Hive 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参阅 GitHub.com 上适用于 Cloudera Hive 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudera-hive)。 # Amazon Athena Cloudera Impala 连接器 Amazon Athena Cloudera Impala 连接器可让 Athena 在 [Cloudera Impala](https://docs.cloudera.com/cdw-runtime/cloud/impala-overview/topics/impala-overview.html) 发行版上运行 SQL 查询。该连接器可将 Athena SQL 查询转换为等效的 Impala 语法。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 + 使用此连接器前，请先设置 VPC 和安全组。有关更多信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 ## 术语 以下术语与 Cloudera Impala 连接器有关。 + **数据库实例** - 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Cloudera Impala 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Cloudera Impala 连接器。要执行此操作，请将 Cloudera Impala 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type CLOUDERAIMPALA ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Cloudera Impala 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Cloudera Impala 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到 Impala 集群。 ``` impala://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | ImpalaMuxCompositeHandler | | 元数据处理程序 | ImpalaMuxMetadataHandler | | 记录处理程序 | ImpalaMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。Athena 目录的 Impala 集群连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myimpalacatalog，则环境变量名称是 myimpalacatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Impala MUX Lambda 函数：`impala1`（默认）和 `impala2`。 **** | 属性 | 值 | | --- | --- | | default | impala://jdbc:impala://some.impala.host.name:21050/?\$1\$1Test/impala1\$1 | | impala\$1catalog1\$1connection\$1string | impala://jdbc:impala://someother.impala.host.name:21050/?\$1\$1Test/impala1\$1 | | impala\$1catalog2\$1connection\$1string | impala://jdbc:impala://another.impala.host.name:21050/?UID=sample&PWD=sample | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/impala1host}`。 ``` impala://jdbc:impala://Impala1host:21050/?...&${Test/impala1host}&... ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` impala://jdbc:impala://Impala1host:21050/?...&UID=sample2&PWD=sample2&... ``` 目前，Cloudera Impala 可以识别 `UID` 和 `PWD` JDBC 属性。 #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Cloudera Impala 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | ImpalaCompositeHandler | | 元数据处理程序 | ImpalaMetadataHandler | | 记录处理程序 | ImpalaRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 Cloudera Impala 实例。 **** | 属性 | 值 | | --- | --- | | default | impala://jdbc:impala://Impala1host:21050/?secret=\$1\$1Test/impala1host\$1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC、Cloudera Impala 和 Arrow 的相应数据类型。 **** | JDBC | Cloudera Impala | Arrow | | --- | --- | --- | | 布尔值 | 布尔值 | Bit | | 整数 | TINYINT | Tiny | | 短型 | SMALLINT | Smallint | | 整数 | INT | Int | | 长整型 | BIGINT | Bigint | | 浮点数 | float4 | Float4 | | 双精度 | float8 | Float8 | | 日期 | date | DateDay | | Timestamp | timestamp | DateMilli | | 字符串 | VARCHAR | Varchar | | 字节 | bytes | Varbinary | | BigDecimal | 十进制 | 十进制 | | ARRAY | 不适用（见注释） | 列表 | **注意** 目前，Cloudera Impala 不支持聚合类型 `ARRAY`、`MAP`、`STRUCT` 或 `UNIONTYPE`。聚合类型的列被视为 SQL 中的 `VARCHAR` 列。 ## 分区和拆分 分区用于确定如何为该连接器生成拆分。Athena 将构建一个 `varchar` 类型的合成列，它将展示表的分区方案，以帮助该连接器生成拆分。该连接器不会修改实际的表定义。 ## 性能 Cloudera Impala 支持静态分区。Athena Cloudera Impala 连接器可从这些分区并行检索数据。如果您想查询具有均匀分区分布的非常大的数据集，强烈建议使用静态分区。Cloudera Impala 连接器能够灵活地应对并发造成的节流。 Athena Cloudera Impala 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Cloudera Impala 连接器可以组合这些表达式并将其直接推送到 Cloudera Impala，以增强功能并减少扫描的数据量。 以下 Athena Cloudera Impala 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 传递查询 Cloudera Impala 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Cloudera Impala 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Cloudera Impala 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参阅 GitHub.com 上适用于 Cloudera Impala 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/pom.xml)文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudera-impala)。 # Amazon Athena CloudWatch 连接器 Amazon Athena CloudWatch 连接器使 Amazon Athena 可以与 CloudWatch 通信，以便您可以使用 SQL 查询日志数据。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 连接器将您的 LogGroup 映射为架构，并将每个 LogStream 映射为表。连接器还映射一个特殊的 `all_log_streams` 视图，其中包含 LogGroup 中的所有 LogStream。此视图使您能够一次性查询 LogGroup 中的所有日志，而不是单个地搜索每个 LogStream。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 参数 使用本节中的参数来配置 CloudWatch 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 CloudWatch 连接器。要执行此操作，请将 CloudWatch 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type CLOUDWATCH ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 CloudWatch 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 CloudWatch 连接器仅支持 `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)时。 该连接器还支持 [AIMD 拥塞控制](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)，以通过 [Amazon Athena Query Federation SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) `ThrottlingInvoker`构造处理来自 CloudWatch 的节流事件。您可以通过设置以下任何可选环境变量来调整默认的节流行为： + **throttle\$1initial\$1delay\$1ms** - 在第一个拥塞事件之后应用的初始调用延迟。默认为 10 毫秒。 + **throttle\$1max\$1delay\$1ms** - 调用之间的最大延迟时间。您可以通过将其分成 1000 毫秒来推导 TPS。默认为 1000 毫秒。 + **throttle\$1decrease\$1factor** – Athena 降低调用速率的因子。默认值为 0.5。 + **throttle\$1increase\$1ms** – Athena 减少调用延迟的速率。默认为 10 毫秒。 ## 数据库和表 Athena CloudWatch 连接器将您的 LogGroup 映射为架构（即数据库），并将每个 LogStream 映射为表。连接器还映射一个特殊的 `all_log_streams` 视图，其中包含 LogGroup 中的所有 LogStream。此视图使您能够一次性查询 LogGroup 中的所有日志，而不是单个地搜索每个 LogStream。 Athena CloudWatch 连接器映射的每个表都有以下架构。此架构与 CloudWatch 日志提供的字段相匹配。 + **log\$1stream** - `VARCHAR`，包含该行来自的 LogStream 的名称。 + **时间** - `INT64`，包含生成日志行时的纪元时间。 + **消息** - `VARCHAR`，包含日志消息。 **示例** 以下示例演示了如何对指定的 LogStream 执行 `SELECT` 查询。 ``` SELECT * FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."log_stream_name" LIMIT 100 ``` 以下示例演示了如何使用 `all_log_streams` 视图对指定 LogGroup 中的所有 LogStream 执行查询。 ``` SELECT * FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."all_log_streams" LIMIT 100 ``` ## 所需权限 要获取有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-cloudwatch.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch/athena-cloudwatch.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **CloudWatch 日志读写** - 连接器使用此权限读取您的日志数据并写入其诊断日志。 ## 性能 Athena CloudWatch 连接器尝试通过并行扫描查询所需的日志流来优化针对 CloudWatch 的查询。在特定时间段筛选条件下，谓词下推既在 Lambda 函数内执行，也在 CloudWatch 日志中执行。 为了获得最佳性能，日志组名称和日志流名称仅限使用小写。使用混合大小写会使连接器执行不区分大小写的搜索，这种搜索的计算密集度更高。 **注意** CloudWatch 连接器不支持大写数据库名称。 ## 传递查询 CloudWatch 连接器支持使用 [CloudWatch Logs Insights 查询语法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)的[传递查询](federated-query-passthrough.md)。有关 CloudWatch Logs Insights 的更多信息，请参阅《*Amazon CloudWatch Logs 用户指南*》中的[使用 CloudWatch Logs Insights 分析日志数据](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html)。 要使用 Cloudera 创建传递查询，请使用以下语法： ``` SELECT * FROM TABLE( system.query( STARTTIME => 'start_time', ENDTIME => 'end_time', QUERYSTRING => 'query_string', LOGGROUPNAMES => 'log_group-names', LIMIT => 'max_number_of_results' )) ``` 以下示例 CloudWatch 传递查询会筛选不等于 1000 时的 `duration` 字段。 ``` SELECT * FROM TABLE( system.query( STARTTIME => '1710918615308', ENDTIME => '1710918615972', QUERYSTRING => 'fields @duration | filter @duration != 1000', LOGGROUPNAMES => '/aws/lambda/cloudwatch-test-1', LIMIT => '2' )) ``` ## 许可证信息 Amazon Athena CloudWatch 连接器项目已获得 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)授权。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch)。 # Amazon Athena CloudWatch 指标连接器 借助 Amazon Athena CloudWatch 指标连接器，Amazon Athena 可以使用 SQL 查询 CloudWatch 指标数据。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 有关从 Athena 本身向 CloudWatch 发布查询指标的信息，请参阅 [使用 CloudWatch 和 EventBridge 监控查询并控制成本](workgroups-control-limits.md)。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 参数 使用本节中的参数来配置 CloudWatch 指标连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 CloudWatch Metrics 连接器。要执行此操作，请将 CloudWatch Metrics 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type CLOUDWATCHMETRICS ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 CloudWatch Metrics 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 CloudWatch Metrics 连接器仅支持 `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)时。 该连接器还支持 [AIMD 拥塞控制](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)，以通过 [Amazon Athena Query Federation SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) `ThrottlingInvoker`构造处理来自 CloudWatch 的节流事件。您可以通过设置以下任何可选环境变量来调整默认的节流行为： + **throttle\$1initial\$1delay\$1ms** - 在第一个拥塞事件之后应用的初始调用延迟。默认为 10 毫秒。 + **throttle\$1max\$1delay\$1ms** - 调用之间的最大延迟时间。您可以通过将其分成 1000 毫秒来推导 TPS。默认为 1000 毫秒。 + **throttle\$1decrease\$1factor** – Athena 降低调用速率的因子。默认值为 0.5。 + **throttle\$1increase\$1ms** – Athena 减少调用延迟的速率。默认为 10 毫秒。 ## 数据库和表 Athena CloudWatch 指标连接器将您的命名空间、维度、指标和指标值映射到名为 `default` 的单个架构中的两个表中。 ### 指标表 `metrics` 表包含由命名空间、集合和名称的组合唯一定义的可用指标。`metrics` 表包含以下列。 + **命名空间** - 包含命名空间的 `VARCHAR`。 + **metric\$1name** - 包含指标名称的 `VARCHAR`。 + **维度** - `LIST``STRUCT` 对象，由 `dim_name (VARCHAR)` 和 `dim_value (VARCHAR)` 组成。 + **统计数据** - 可用于该指标的 `LIST``VARCH` 统计数据（例如，`p90`、`AVERAGE`...）。 ### metric\$1samples 表 `metric_samples` 表包含 `metrics` 表中每个指标的可用指标示例。`metric_samples` 表包含以下列。 + **命名空间** - 包含命名空间的 `VARCHAR`。 + **metric\$1name** - 包含指标名称的 `VARCHAR`。 + **维度** - `STRUCT` 对象的 `LIST`，由 `dim_name (VARCHAR)` 和 `dim_value (VARCHAR)` 组成。 + **dim\$1name** - 可用于轻松筛选单个维度名称的 `VARCHAR` 便捷字段。 + **dim\$1value** - 可用于轻松筛选单个维度值的 `VARCHAR` 便捷字段。 + **周期** - 表示指标“周期”的 `INT` 字段，以秒为单位（例如，60 秒指标）。 + **时间戳** - 表示指标样本纪元时间的 `BIGINT` 字段（以秒为单位）。 + **值** - 包含样本值的 `FLOAT8` 字段。 + **统计数据** - 包含样本统计类型的 `VARCHAR`（例如，`AVERAGE` 或 `p90`)。 ## 所需权限 要获取有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-cloudwatch-metrics.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch-metrics/athena-cloudwatch-metrics.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **CloudWatch 指标只读** - 连接器使用此权限来查询您的指标数据。 + **CloudWatch 日志写入** - 连接器使用此权限写入其诊断日志。 ## 性能 Athena CloudWatch 指标连接器尝试通过并行扫描查询所需的日志流来优化针对 CloudWatch 指标的查询。在特定时间段、指标、命名空间和维度筛选条件下，谓词下推既在 Lambda 函数内执行，也在 CloudWatch 日志中执行。 ## 许可证信息 Amazon Athena CloudWatch 指标连接器项目已根据 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)获得许可。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch-metrics)。 # Amazon Athena AWS CMDB 连接器 使用 Amazon Athena AWS CMDB 连接器使 Athena 可以与各种 AWS 服务通信，以便您可以使用 SQL 查询这些服务。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅[创建数据来源连接](connect-to-a-data-source.md)或[使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 参数 使用本节中的参数来配置 AWS CMDB 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 AWS CMDB 连接器。要执行此操作，请将 AWS CMDB 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type CMDB ``` **Lambda 环境属性** **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 AWS CMDB 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 AWS CMDB 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 **Lambda 环境属性** + **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)时。 + **default\$1ec2\$1image\$1owner** –（可选）设置后，控制筛选 [Amazon 机器映像 (AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) 的默认 Amazon EC2 映像所有者。如果您未设置此值，并且您对 EC2 映像表的查询不包含所有者筛选条件，则您的结果将包括所有公有映像。 ## 数据库和表 Athena AWS CMDB 连接器使以下数据库和表可用于查询您的 AWS 资源清单。有关每个表中可用列的更多信息，请使用 Athena 控制台或 API 运行 `DESCRIBE database.table` 语句。 + **ec2** - 该数据库包含 Amazon EC2 相关资源，包括以下内容。 + **ebs\$1volumes** - 包含您的 Amazon EBS 卷的详细信息。 + **ec2\$1instances** - 包含您的 EC2 实例的详细信息。 + **ec2\$1images** - 包含您的 EC2 实例映像的详细信息。 + **routing\$1tables** - 包含您的 VPC 路由表的详细信息。 + **security\$1groups** - 包含您的安全组的详细信息。 + **子网** - 包含您的 VPC 子网的详细信息。 + **vpcs** - 包含您的 VPC 的详细信息。 + **emr** - 该数据库包含 Amazon EMR 相关资源，包括以下内容。 + **emr\$1clusters** - 包含您的 EMR 集群的详细信息。 + **rds** - 该数据库包含 Amazon RDS 相关资源，包括以下内容。 + **rds\$1instances** - 包含您的 RDS 实例的详细信息。 + **s3** - 该数据库包含 RDS 相关资源，包括以下内容。 + **桶** - 包含您的 Amazon S3 存储桶的详细信息。 + **对象** - 包含您的 Amazon S3 对象（不包括其内容）的详细信息。 ## 所需权限 要获取有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-aws-cmdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-aws-cmdb/athena-aws-cmdb.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **S3 清单** - 连接器使用此权限列出您的 Amazon S3 存储桶和对象。 + **EC2 描述** - 连接器使用此权限来描述资源，例如您的 Amazon EC2 实例、安全组、VPC 和 Amazon EBS 卷。 + **EMR 描述/列表** - 连接器使用此权限来描述您的 EMR 集群。 + **RDS 描述** - 连接器使用此权限来描述您的 RDS 实例。 ## 性能 目前，Athena AWS CMDB 连接器不支持并行扫描。谓词下推在 Lambda 函数中执行。在可能的情况下，部分谓词会被推送到正在查询的服务。例如，查询特定 Amazon EC2 实例的详细信息会调用具有特定实例 ID 的 EC2 API 来运行目标描述操作。 ## 许可证信息 Amazon Athena AWS CMDB 连接器项目已获得 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)授权。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-aws-cmdb)。 # Amazon Athena IBM Db2 连接器 使用适用于 Db2 的 Amazon Athena 连接器，Amazon Athena 能够使用 JDBC 对 IBM Db2 数据库运行 SQL 查询。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 + 使用此连接器前，请先设置 VPC 和安全组。有关更多信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 必须将筛选条件中的日期和时间戳数据类型转换为适当的数据类型。 ## 术语 以下术语与 Db2 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Db2 连接器。 **注意** 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 连接对象来配置 Db2 连接器。要执行此操作，请将 Db2 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type DB2 ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Db2 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Db2 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` dbtwo://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | Db2MuxCompositeHandler | | 元数据处理程序 | Db2MuxMetadataHandler | | 记录处理程序 | Db2MuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mydbtwocatalog，则环境变量名称是 mydbtwocatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Db2 MUX Lambda 函数：`dbtwo1`（默认）和 `dbtwo2`。 **** | 属性 | 值 | | --- | --- | | default | dbtwo://jdbc:db2://dbtwo1.hostname:port/database\$1name:\$1\$1secret1\$1name\$1 | | dbtwo\$1catalog1\$1connection\$1string | dbtwo://jdbc:db2://dbtwo1.hostname:port/database\$1name:\$1\$1secret1\$1name\$1 | | dbtwo\$1catalog2\$1connection\$1string | dbtwo://jdbc:db2://dbtwo2.hostname:port/database\$1name:\$1\$1secret2\$1name\$1 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${secret_name}`。 ``` dbtwo://jdbc:db2://hostname:port/database_name:${secret_name} ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` dbtwo://jdbc:db2://hostname:port/database_name:user=user_name;password=password; ``` #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Db2 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | Db2CompositeHandler | | 元数据处理程序 | Db2MetadataHandler | | 记录处理程序 | Db2RecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 Db2 实例。 **** | 属性 | 值 | | --- | --- | | default | dbtwo://jdbc:db2://hostname:port/database\$1name:\$1\$1secret\$1name\$1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC 和 Arrow 的相应数据类型。 **** | Db2 | Arrow | | --- | --- | | CHAR | VARCHAR | | VARCHAR | VARCHAR | | DATE | DATEDAY | | TIME | VARCHAR | | TIMESTAMP | DATEMILLI | | DATETIME | DATEMILLI | | BOOLEAN | BOOL | | SMALLINT | SMALLINT | | INTEGER | INT | | BIGINT | BIGINT | | DECIMAL | DECIMAL | | REAL | FLOAT8 | | DOUBLE | FLOAT8 | | DECFLOAT | FLOAT8 | ## 分区和拆分 分区由一个或多个类型为 `varchar` 的分区列表示。Db2 连接器使用以下组织架构创建分区。 + 按哈希值分发 + 按范围分区 + 按维度组织 连接器从一个或多个 Db2 元数据表中检索分区详细信息，例如分区数和列名称。拆分根据指定的分区数而创建。 ## 性能 Athena Db2 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Db2 连接器可以组合这些表达式并将其直接推送到 Db2，以增强功能并减少扫描的数据量。 以下 Athena Db2 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 传递查询 Db2 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Db2 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Db2 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本的信息，请参阅 GitHub.com 上适用于 Db2 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-db2)。 # Amazon Athena IBM Db2 AS/400（Db2 iSeries）连接器 使用适用于 Db2 AS/400 的 Amazon Athena 连接器，Amazon Athena 能够使用 JDBC 在 IBM Db2 AS/400（Db2 iSeries）数据库上运行 SQL 查询。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 + 使用此连接器前，请先设置 VPC 和安全组。有关更多信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 必须将筛选条件中的日期和时间戳数据类型转换为适当的数据类型。 ## 术语 以下术语与 Db2 AS/400 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Db2 AS/400 连接器。 **注意** 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 连接对象来配置 Db2 AS/400 连接器。要执行此操作，请将 Db2 AS/400 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type DB2AS400 ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Db2 AS/400 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Db2 AS/400 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` db2as400://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | Db2MuxCompositeHandler | | 元数据处理程序 | Db2MuxMetadataHandler | | 记录处理程序 | Db2MuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mydb2as400catalog，则环境变量名称是 mydb2as400catalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Db2 MUX Lambda 函数：`db2as4001`（默认）和 `db2as4002`。 **** | 属性 | 值 | | --- | --- | | default | db2as400://jdbc:as400://;;:\$1\$1\$1; | | db2as400\$1catalog1\$1connection\$1string | db2as400://jdbc:as400://db2as4001.hostname/:\$1\$1secret1\$1name\$1 | | db2as400\$1catalog2\$1connection\$1string | db2as400://jdbc:as400://db2as4002.hostname/:\$1\$1secret2\$1name\$1 | | db2as400\$1catalog3\$1connection\$1string | db2as400://jdbc:as400://;user=;password=;; | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${secret_name}`。 ``` db2as400://jdbc:as400://;;:${}; ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` db2as400://jdbc:as400://;user=;password=;; ``` #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序来连接到单个 Db2 AS/400实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | Db2CompositeHandler | | 元数据处理程序 | Db2MetadataHandler | | 记录处理程序 | Db2RecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 Db2 AS/400 实例。 **** | 属性 | 值 | | --- | --- | | default | db2as400://jdbc:as400://;;:\$1\$1\$1; | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC 和 Apache Arrow 的相应数据类型。 **** | Db2 AS/400 | Arrow | | --- | --- | | CHAR | VARCHAR | | VARCHAR | VARCHAR | | DATE | DATEDAY | | TIME | VARCHAR | | TIMESTAMP | DATEMILLI | | DATETIME | DATEMILLI | | BOOLEAN | BOOL | | SMALLINT | SMALLINT | | INTEGER | INT | | BIGINT | BIGINT | | DECIMAL | DECIMAL | | REAL | FLOAT8 | | DOUBLE | FLOAT8 | | DECFLOAT | FLOAT8 | ## 分区和拆分 分区由一个或多个类型为 `varchar` 的分区列表示。Db2 AS/400 连接器使用以下组织架构创建分区。 + 按哈希值分发 + 按范围分区 + 按维度组织 该连接器从一个或多个 Db2 AS/400 元数据表中检索分区详细信息，例如分区数和列名称。拆分根据指定的分区数而创建。 ## 性能 要提高性能，请使用谓词“下推”从 Athena 进行查询，如下例所示。 ``` SELECT * FROM "lambda:".""."" WHERE integercol = 2147483647 ``` ``` SELECT * FROM "lambda: ".""."" WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878' ``` ## 传递查询 Db2 AS/400 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Db2 AS/400 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Db2 AS/400 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本的信息，请参阅 GitHub.com 上适用于 Db2 AS/400 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-db2-as400)。 # Amazon Athena DocumentDB 连接器 Amazon Athena DocumentDB 连接器使 Athena 可以与您的 DocumentDB 实例通信，以便您可以使用 SQL 查询 DocumentDB 数据。该连接器还可与任何与 MongoDB 兼容的端点配合使用。 与传统的关系数据存储不同，Amazon DocumentDB 集合没有集架构。DocumentDB 没有元数据存储。DocumentDB 集合中的每个条目均可具有不同字段和数据类型。 DocumentDB 连接器支持两种生成表架构信息的机制：基本架构推理和 AWS Glue Data Catalog 元数据。 默认设置为架构推理。此选项将扫描您的集合中的少量文档，形成所有字段的并集，并强制使用非重叠数据类型的字段。此选项适用于条目大多为统一的集合。 对于具有更多数据类型的集合，该连接器支持从 AWS Glue Data Catalog 检索元数据。如果该连接器发现与您的 DocumentDB 数据库和集合名称相匹配的 AWS Glue 数据库和表，它将从相应的 AWS Glue 表中获取其架构信息。在您创建 AWS Glue 表时，我们建议您将其设置为您可能想从 DocumentDB 集合访问的所有字段的超集。 如果您在账户中启用了 Lake Formation，则您在 AWS Serverless Application Repository 中部署的 Athena 联合身份 Lambda 连接器的 IAM 角色必须在 Lake Formation 中具有 AWS Glue Data Catalog 的读取权限。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 参数 使用本节中的参数来配置 DocumentDB 连接器。 **注意** 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 连接对象来配置 DocumentDB 连接器。要执行此操作，请将 DocumentDB 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type DOCUMENTDB ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 DocumentDB 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 DocumentDB 连接器仅支持 `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 检索补充元数据。 + **glue\$1catalog** –（可选）使用此选项指定[跨账户 AWS Glue 目录](data-sources-glue-cross-account.md)。默认情况下，该连接器将尝试从其自己的 AWS Glue 账户中获取元数据。 + **default\$1docdb** – 如果存在，则指定在不存在特定于目录的环境变量时要使用的 DocumentDB 连接字符串。 + **disable\$1projection\$1and\$1casing** –（可选）禁用投影和大小写。在您需要查询使用区分大小写的列名称的 Amazon DocumentDB 表时使用。`disable_projection_and_casing` 参数使用以下值来指定大小写和列映射的行为： + **false** – 这是默认设置。投影已启用，连接器要求所有列名称为小写。 + **true** – 禁用投影和区分大小写。在使用 `disable_projection_and_casing` 参数时，请记住以下几点： + 使用该参数可能会导致更高的带宽使用量。此外，如果 Lambda 函数与数据来源处于不同的 AWS 区域，则由于带宽使用量较高，会产生更高的标准 AWS 跨区域传输成本。有关跨区域传输成本的更多信息，请参阅 AWS 合作伙伴网络博客中的[服务器和无服务器架构的 AWS 数据传输费用](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)。 + 由于传输的字节数越多，并且字节数越大，需要反序列化时间越长，因此整体延迟可能会增加。 + **enable\$1case\$1insensitive\$1match** –（可选）如果是 `true`，则对 Amazon DocumentDB 中的架构和表名执行搜索，搜索不区分大小写。默认值为 `false`。如果查询包含大写的架构名或表名，则使用该参数。 #### 指定连接字符串 您可以提供一个或多个属性，用于定义与该连接器配合使用的 DocumentDB 实例的 DocumentDB 连接详细信息。为此，请设置一个与您要在 Athena 中使用的目录名称相对应的 Lambda 环境变量。例如，假设您要使用以下查询来查询 Athena 中的两个不同 DocumentDB 实例： ``` SELECT * FROM "docdb_instance_1".database.table ``` ``` SELECT * FROM "docdb_instance_2".database.table ``` 您必须向 Lambda 函数中添加以下两个环境变量，然后才能使用这两个 SQL 语句：`docdb_instance_1` 和 `docdb_instance_2`。每个环境变量的值均应为以下格式的 DocumentDB 连接字符串： ``` mongodb://:@:/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0 ``` ##### 使用密钥 您可以选择将 AWS Secrets Manager 用于您的连接字符串详细信息的部分值或全部值。要将 Athena 联合查询功能与 Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 如果您使用语法 `${my_secret}` 将来自 Secrets Manager 的密钥的名称放入连接字符串，该连接器会将 `${my_secret}` 替换为来自 Secrets Manager 的纯文本值。密钥应存储为具有值 `:` 的纯文本密钥。存储为 `{username:,password:}` 的密钥将无法正确传递到连接字符串。 密钥也可以完全用于整个连接字符串，并且可以在密钥中定义用户名和密码。 例如，假设您将 `docdb_instance_1` 的 Lambda 环境变量设置为以下值： ``` mongodb://${docdb_instance_1_creds}@myhostname.com:123/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0 ``` Athena 查询联合软件开发工具包 (SDK) 将自动尝试从 Secrets Manager 检索名为的密钥 `docdb_instance_1_creds` 的密钥，然后注入该值来替换 `${docdb_instance_1_creds}`。`${ }` 字符组合所包含的该连接字符串的任何部分将被解释为来自 Secrets Manager 的密钥。如果您指定了该连接器在 Secrets Manager 中无法找到的密钥名称，则该连接器不会替换该文本。 ## 检索补充元数据 要检索补充元数据，请按照以下步骤配置您的 Glue 数据库和表。 ### 设置 Glue 数据库 1. 创建一个与您的 DocumentDB 集合同名的 Glue 数据库。 1. 在“位置 URI”字段中输入 `docdb-metadata-flag`。 ### 配置 Glue 表 将以下参数添加到 Glue 表： + `docdb-metadata-flag = true` + `columnMapping = apple=APPLE` 在本例中，`apple` 表示 Glue 中的小写列名，而 `APPLE` 表示 DocumentDB 集合中区分大小写的实际列名。 ### 验证元数据检索 1. 运行您的查询。 1. 查看 Lambda 函数的 CloudWatch 日志，确保成功检索元数据。成功的检索将显示以下日志条目： ``` doGetTable: Retrieved schema for table[TableName{schemaName=test, tableName=profiles}] from AWS Glue. ``` **注意** 如果您的表已配置 `columnMapping` 字段，则只需将 `docdb-metadata-flag = true` 参数添加到表属性即可。 ## 在 AWS Glue 中设置数据库和表 由于该连接器的内置架构推理功能扫描有限数量的文档，并且仅支持一部分数据类型，因此您可能需要改为将 AWS Glue 用于元数据。 要使 AWS Glue 表可与 Amazon DocumentDB 配合使用，您必须拥有 AWS Glue 数据库和表，适用于您要为其提供补充元数据的 DocumentDB 数据库和集合。 **将 AWS Glue 表用于补充元数据** 1. 使用 AWS Glue 控制台创建与您的 Amazon DocumentDB 数据库名称同名的 AWS Glue 数据库。 1. 将数据库的 URI 属性设置为包含 **docdb-metadata-flag**。 1. （可选）添加 **sourceTable** 表属性。此属性用于定义 Amazon DocumentDB 中的源表名称。如果您的 AWS Glue 表名称与 Amazon DocumentDB 中的表名称不同，请使用此属性。由于 AWS Glue 与 Amazon DocumentDB 之间的命名规则差异，有必要使用此属性。例如，AWS Glue 表名称中不允许大写字母，但 Amazon DocumentDB 表名称中允许使用大写字母。 1. （可选）添加 **columnMapping** 表属性。此属性用于定义列名映射。如果 AWS Glue 列命名规则阻止您创建列名称与 Amazon DocumentDB 表相同的 AWS Glue 表，请使用此属性。这可能很有用，因为 Amazon DocumentDB 列名称中允许使用大写字母，但 AWS Glue 列名称中不允许使用。 `columnMapping` 属性值应为采用 `col1=Col1,col2=Col2` 格式的一组映射。 **注意** 列映射仅适用于顶级列名称，不适用于嵌套字段。 在添加 AWS Glue `columnMapping` 表属性后，您可以移除 `disable_projection_and_casing` Lambda 环境变量。 1. 请确保使用适合 AWS Glue 的数据类型，如本文档中所列。 ## 数据类型支持 本节列出了 DocumentDB 连接器用于架构推断的数据类型，以及使用 AWS Glue 元数据时的数据类型。 ### 架构推理数据类型 DocumentDB 连接器的架构推断功能会尝试将值推断为属于以下数据类型之一。该表显示了适用于 Amazon DocumentDB、Java 和 Apache Arrow 的相应数据类型。 **** | Apache Arrow | Java 或 DocDB | | --- | --- | | VARCHAR | 字符串 | | INT | 整数 | | BIGINT | 长整型 | | BIT | 布尔值 | | FLOAT4 | 浮点型 | | FLOAT8 | 双精度 | | TIMESTAMPSEC | 日期 | | VARCHAR | ObjectId | | LIST | 列表 | | STRUCT | 文档 | ### AWS Glue 数据类型 如果将 AWS Glue 用于补充元数据，则可配置以下数据类型。该表显示了适用于 AWS Glue 和 Apache Arrow 的相应数据类型。 **** | AWS Glue | Apache Arrow | | --- | --- | | int | INT | | bigint | BIGINT | | double | FLOAT8 | | 浮点数 | FLOAT4 | | 布尔值 | BIT | | binary | VARBINARY | | 字符串 | VARCHAR | | 列表 | LIST | | Struct | STRUCT | ## 所需权限 有关此连接器所需 IAM 策略的完整详细信息，请查看 [athena-docdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-docdb/athena-docdb.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **AWS Glue Data Catalog** – DocumentDB 连接器需要针对 AWS Glue Data Catalog 的只读访问权限，以获取架构信息。 + **CloudWatch Logs** – 该连接器需要针对 CloudWatch Logs 的访问权限，以存储日志。 + **AWS Secrets Manager 读取权限** - 如果您选择在 Secrets Manager 中存储 DocumentDB 端点详细信息，则必须授予该连接器针对这些秘密的访问权限。 + **VPC 访问权限** - 该连接器需要能够连接和断开您的 VPC 接口，以便它能连接到 VPC 并与您的 DocumentDB 实例通信。 ## 性能 Athena Amazon DocumentDB 连接器当前不支持并行扫描，但会尝试下推谓词作为其 DocumentDB 查询的组成部分，并且针对 DocumentDB 集合索引的谓词将显著减少扫描的数据。 Lambda 函数执行投影下推，以减少查询扫描的数据。但是，选择列的子集有时会导致更长的查询执行运行时。`LIMIT` 子句可减少扫描的数据量，但如果未提供谓词，则预期要使用包含 `LIMIT` 子句的 `SELECT` 查询来扫描至少 16 MB 的数据。 ## 传递查询 Athena Amazon DocumentDB 连接器支持[传递查询](federated-query-passthrough.md)，并且以 NoSQL 为基础。有关查询 Amazon DocumentDB 的信息，请参阅《Amazon DocumentDB Developer Guide》**中的 [Querying](https://docs.aws.amazon.com/documentdb/latest/developerguide/querying.html)。 要在 Amazon DocumentDB 中执行传递查询，请使用以下语法： ``` SELECT * FROM TABLE( system.query( database => 'database_name', collection => 'collection_name', filter => '{query_syntax}' )) ``` 以下示例对 `TPCDS` 集合中的 `example` 数据库进行了查询，筛选出书名为《Bill of Rights》**的所有书籍。 ``` SELECT * FROM TABLE( system.query( database => 'example', collection => 'tpcds', filter => '{title: "Bill of Rights"}' )) ``` ## 其他资源 + 有关使用 [Amazon Athena 联合查询](federated-queries.md)将 MongoDB 数据库连接到 [Quick](https://aws.amazon.com/quicksight/) 以构建控制面板和可视化的文章，请参阅 *AWS 大数据博客*中的 [Visualize MongoDB data from Quick using Amazon Athena Federated Query](https://aws.amazon.com/blogs/big-data/visualize-mongodb-data-from-amazon-quicksight-using-amazon-athena-federated-query/)。 + 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-docdb)。 # Amazon Athena DynamoDB 连接器 Amazon Athena DynamoDB 连接器使 Amazon Athena 可以与 DynamoDB 通信，以便您可以使用 SQL 查询表。写入操作不受支持，例如 [INSERT INTO](insert-into.md)。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 如果您在账户中启用了 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)。 ## 限制 如果您将 DynamoDB 连接迁移到 Glue Catalog 和 Lake Formation，则只能识别小写的表名和列名。 ## 参数 使用本节中的参数来配置 DynamoDB 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 DynamoDB 连接器。要执行此操作，请将 DynamoDB 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type DYNAMODB ``` **Lambda 环境属性** **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 DynamoDB 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 DynamoDB 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 **Lambda 环境属性** + **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 检索补充元数据。 + **glue\$1catalog** –（可选）使用此选项指定[跨账户 AWS Glue 目录](data-sources-glue-cross-account.md)。默认情况下，该连接器将尝试从其自己的 AWS Glue 账户中获取元数据。 + **disable\$1projection\$1and\$1casing** –（可选）禁用投影和大小写。如果您要查询列名中有大小写的 DynamoDB 表，并且不想在您的 AWS Glue 表上指定 `columnMapping` 属性，请使用此参数。 `disable_projection_and_casing` 参数使用以下值来指定大小写和列映射的行为： + **auto** – 当检测到以前不支持的类型，并且未在表上设置列名称映射时，禁用投影和大小写。这是默认设置。 + **always** – 无条件禁用投影和大小写。当您的 DynamoDB 列名称中有大小写，但您不想指定任何列名称映射时，此参数很有用。 在使用 `disable_projection_and_casing` 参数时，请记住以下几点： + 使用该参数可能会导致更高的带宽使用量。此外，如果 Lambda 函数与数据来源处于不同的 AWS 区域，则由于带宽使用量较高，会产生更高的标准 AWS 跨区域传输成本。有关跨区域传输成本的更多信息，请参阅 AWS 合作伙伴网络博客中的[服务器和无服务器架构的 AWS 数据传输费用](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)。 + 由于传输的字节数越多，并且字节数越大，需要反序列化时间越长，因此整体延迟可能会增加。 ## 在 AWS Glue 中设置数据库和表 由于该连接器的内置架构推理功能有限，因此您可能需要将 AWS Glue 用于元数据。为此，您必须在 AWS Glue 中有一个数据库和表。要将其与 DynamoDB 一起使用，您必须编辑其属性。 **在 AWS Glue 控制台中编辑表属性** 1. 登录 AWS 管理控制台，然后打开 AWS Glue 控制台，网址为：[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)。 1. 在导航窗格中，展开**数据目录**，然后选择**数据库**。 在 **Databases**（数据库）页面上，您可以编辑现有的数据库，也可以选择 **Add database**（添加数据库）来创建数据库。 1. 在数据库列表中，选择要编辑的数据库的链接。 1. 选择**编辑**。 1. 在**更新数据库**页面上，在**数据库设置**下，对于**位置**，添加字符串 **dynamo-db-flag**。此关键字指示数据库包含 Athena DynamoDB 连接器用于补充元数据的表，并且是除 `default` 以外其他 AWS Glue 数据库所需要的。`dynamo-db-flag` 属性非常适合用于筛选出具有多个数据库的账户中的数据库。 1. 选择 **Update Database**（更新数据库）。 **要在 AWS Glue 控制台中编辑表属性** 1. 登录 AWS 管理控制台，然后打开 AWS Glue 控制台，网址为：[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)。 1. 在导航窗格中，展开**数据目录**，然后选择**表**。 1. 在**表**页面上的表列表中，选择要编辑的表的链接名称。 1. 依次选择 **Actions**（操作）、**Edit table**（编辑表）。 1. 在 **Edit table**（编辑表）页面的 **Table properties**（表属性）部分，根据需要添加以下表属性。如果您使用 AWS Glue DynamoDB 爬网程序，将自动设置这些属性。 + **dynamodb** – 向 Athena DynamoDB 连接器指明可将该表用于补充元数据的字符串。在表属性中名为 **classification**（分类）的字段下输入字符串 `dynamodb`（完全匹配）。 **注意** **设置表属性**页面是 AWS Glue 控制台中的表创建过程的一部分，内含带**分类**字段的**数据格式**部分。您无法在此处输入或选择 `dynamodb`。但在创建表之后，请按照步骤编辑表，并在**表属性**部分中以键值对的形式输入 `classification` 和 `dynamodb`。 + **sourceTable** – 可选的表属性，用于定义 DynamoDB 中的源表名称。如果 AWS Glue 表命名规则阻止您创建与 DynamoDB 表同名的 AWS Glue 表，请使用此属性。例如，AWS Glue 表名称中不允许大写字母，但允 DynamoDB 表名称中允许大写字母。 + **columnMapping** – 可选的表属性，用于定义列名称映射。如果 AWS Glue 列命名规则阻止您创建与 DynamoDB 表具有相同列名称的 AWS Glue 表，请使用此属性。例如，AWS Glue 列名称中不允许大写字母，但允 DynamoDB 列名称中允许大写字母。该属性值的格式应为 col1=Col1,col2=Col2。请注意，列映射仅适用于顶级列名，不适用于嵌套字段。 + **defaultTimeZone** – 可选的表属性，应用于没有明确时区的 `date` 或 `datetime` 值。设置此值是一种很好的做法，可以避免数据来源默认时区与 Athena 会话时区之间存在差异。 + **datetimeFormatMapping** – 可选的表属性，用于指定要在解析 AWS Glue `date` 或 `timestamp` 数据类型的列中的数据时使用的 `date` 或 `datetime` 格式。如果未指定此属性，则该连接器将尝试[推断](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/time/DateFormatUtils.html) ISO-8601 格式。如果该连接器无法推断 `date` 或 `datetime` 格式或无法解析原始字符串，则将在结果中省略该值。 `datetimeFormatMapping` 值应该采用 `col1=someformat1,col2=someformat2` 格式。下面是一些示例格式： ``` yyyyMMdd'T'HHmmss ddMMyyyy'T'HH:mm:ss ``` 如果您的列包含没有时区的 `date` 或 `datetime` 值，并且您想使用 `WHERE` 子句中的列，请为该列设置 `datetimeFormatMapping` 属性。 1. 如果您手动定义列，请确保使用适当的数据类型。如果您使用了爬网程序，请验证该爬网程序发现的列和类型。 1. 选择**保存**。 ## 所需权限 有关此连接器所需 IAM 策略的完整详细信息，请查看 [athena-dynamodb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-dynamodb/athena-dynamodb.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **AWS Glue Data Catalog** – DynamoDB 连接器需要针对 AWS Glue Data Catalog 的只读访问权限，以获取架构信息。 + **CloudWatch Logs** – 该连接器需要针对 CloudWatch Logs 的访问权限，以存储日志。 + **DynamoDB 读取权限** – 该连接器使用 `DescribeTable`、`ListSchemas`、`ListTables`、`Query` 和 `Scan` API 操作。 ## 性能 Athena DynamoDB 连接器支持并行扫描，并尝试下推谓词作为其 DynamoDB 查询的组成部分。具有 `X` 个不同值的哈希键谓词将导致 `X` 个指向 DynamoDB 的查询调用。所有其他谓词场景都会导致 `Y` 次扫描调用，其中 `Y` 是根据您的表的大小及其预调配吞吐量以启发方式确定的。但是，选择一部分列有时会导致查询执行的运行时间延长。 `LIMIT` 子句和简单谓词将下推，这可以减少扫描的数据量，从而缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。为了增强功能并减少扫描的数据量，Athena DynamoDB 连接器可以组合这些表达式并将其直接推送到 DynamoDB。 以下 Athena DynamoDB 连接器运算符支持谓词下推： + **布尔值：**AND + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 and col_b < 10 LIMIT 10 ``` 有关使用谓词下推来提高联合查询（包括 DynamoDB）性能的文章，请参阅 *AWS 大数据博客*中的[在 Amazon Athena 中使用谓词下推改善联合查询](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)。 ## 传递查询 DynamoDB 连接器支持[传递查询](federated-query-passthrough.md)，且使用 PartiQL 语法。不支持 DynamoDB [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) API 操作。有关使用 PartiQL 查询 DynamoDB 的信息，请参阅《Amazon DynamoDB Developer Guide》**中的 [PartiQL select statements for DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html)。 要在 DynamoDB 中执行传递查询，请使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query_string' )) ``` 以下 DynamoDB 传递查询示例使用了 PartiQL 来返回 `DateWatched` 属性晚于 2022 年 12 月 24 日的 Fire TV Stick 设备列表。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT Devices FROM WatchList WHERE Devices.FireStick.DateWatched[0] > '12/24/22'' )) ``` ## 问题排查 ### 排序键列上的多个筛选器 **错误消息**：keyConditionExpressions 每个键仅限包含一个条件 **原因**：在 Athena 引擎版本 3 中，如果查询在 DynamoDB 排序键列上同时具有下限和上限筛选器，可能会出现此问题。由于 DynamoDB 在排序键上不支持多个筛选条件，因此当连接器尝试下推同时应用这两个条件的查询时，会引发错误。 **解决方案**：将连接器更新为 2023.11.1 或更高版本。有关更新连接器的说明，请参阅 [更新数据来源连接器](connectors-updating.md)。 ## 成本 该连接器的使用成本取决于所使用的底层 AWS 资源。因为使用扫描的查询可能会消耗大量[读取容量单位 (RCU)](https://aws.amazon.com/dynamodb/pricing/provisioned/)，请认真考虑有关 [Amazon DynamoDB 定价](https://aws.amazon.com/dynamodb/pricing/)的信息。 ## 其他资源 + 有关使用 Amazon Athena DynamoDB 连接器的介绍，请参阅 *AWS 规范性指导模式*指南中的[使用 Athena 访问、查询和连接 Amazon DynamoDB 表](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/access-query-and-join-amazon-dynamodb-tables-using-athena.html)。 + 有关如何使用 Athena DynamoDB 连接器通过 SQL 在 DynamoDB 中查询数据并在 Amazon Quick 中可视化见解的文章，请参阅 *AWS 大数据博客*文章 [Visualize Amazon DynamoDB insights in Quick using the Amazon Athena DynamoDB connector and AWS Glue](https://aws.amazon.com/blogs/big-data/visualize-amazon-dynamodb-insights-in-amazon-quicksight-using-the-amazon-athena-dynamodb-connector-and-aws-glue/)。 + 有关将 Amazon Athena DynamoDB 连接器与 Amazon DynamoDB、Athena 和 Quick 结合使用来创建简单监管控制面板的文章，请参阅 *AWS 大数据博客*文章 [Query cross-account Amazon DynamoDB tables using Amazon Athena Federated Query](https://aws.amazon.com/blogs/big-data/query-cross-account-amazon-dynamodb-tables-using-amazon-athena-federated-query/)。 + 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-dynamodb)。 # Amazon Athena Google BigQuery 连接器 适用于 Google [BigQuery](https://cloud.google.com/bigquery/) 的 Amazon Athena 连接器使 Amazon Athena 能够对您的 Google BigQuery 数据运行 SQL 查询。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + Lambda 函数的最大超时值为 15 分钟。每次拆分都会在 BigQuery 上执行一次查询，并且必须有足够的时间来存储结果，以便 Athena 读取。如果 Lambda 函数超时，查询将失败。 + Google BigQuery 区分大小写。连接器尝试更正数据集名称、表名称和项目 ID。这很有必要，因为 Athena 所有元数据均采用小写形式。这些更正对 Google BigQuery 进行了许多额外的调用。 + 不支持 Binary 数据类型。 + 由于 Google BigQuery 的并发和配额限制，连接器可能会遇到 Google 配额限制问题。为了避免这些问题，请尽可能多地向 Google BigQuery 施加限制。有关 BigQuery 配额的信息，请参阅 Google BigQuery 文档中的 [配额和限制](https://cloud.google.com/bigquery/quotas)。 ## 参数 使用本节中的参数来配置 Google BigQuery 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Google BigQuery 连接器。要执行此操作，请将 Google BigQuery 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type BIGQUERY ``` **Lambda 环境属性** **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Google BigQuery 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Google BigQuery 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 **Lambda 环境属性** + **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)时。 + **gcp\$1project\$1id** - 项目 ID（不是项目名称），包含连接器应从中读取的数据集（例如 `semiotic-primer-1234567`)。 + **secret\$1manager\$1gcp\$1creds\$1name** - AWS Secrets Manager 中的密钥名称，包含 JSON 格式的 BigQuery 凭证（例如 `GoogleCloudPlatformCredentials`)。 + **big\$1query\$1endpoint** –（可选）BigQuery 私有端点的 URL。如果您想通过私有端点访问 BigQuery，使用此参数。 ## 拆分与视图 由于 BigQuery 连接器使用 BigQuery 存储读取 API 来查询表，而 BigQuery 存储 API 不支持视图，所以该连接器使用具有单个视图拆分功能的 BigQuery 客户端。 ## 性能 为了查询表，BigQuery 连接器使用了 BigQuery 存储读取 API，该 API 使用基于 RPC 的协议，支持快速访问 BigQuery 托管存储。有关 BigQuery 存储读取 API 的更多信息，请参阅 Google Cloud 文档中的[使用 BigQuery 存储读取 API 读取表格数据](https://cloud.google.com/bigquery/docs/reference/storage)。 选择列的子集可以显著减少查询运行时及扫描的数据。随着并发增加，连接器容易出现查询失败，并且通常是慢速连接器。 Athena Google BigQuery 连接器执行谓词下推，以减少查询扫描的数据。`LIMIT` 子句、`ORDER BY` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### 前 N 个查询 前 `N` 个查询用于指定结果集的顺序以及返回的行数限值。您可以使用此类查询确定数据集的前 `N` 个最大值或前 `N` 个最小值。前 `N` 个查询下推时，连接器仅向 Athena 返回 `N` 个已排序行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Google BigQuery 连接器可以组合这些表达式并将其直接推送到 Google BigQuery，以增强功能并减少扫描数据量。 以下 Athena Google BigQuery 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') ORDER BY col_a DESC LIMIT 10; ``` ## 传递查询 Google BigQuery 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Google BigQuery 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Google BigQuery 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 Amazon Athena Google BigQuery 连接器项目已获得 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)授权。 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-google-bigquery)。 # Amazon Athena Google Cloud Storage 连接器 借助 Amazon Athena Google Cloud Storage 连接器，Amazon Athena 可以对存储在 Google Cloud Storage（GCS）存储桶中的 Parquet 和 CSV 文件运行查询。将一个或多个 Parquet 或 CSV 文件分组到 GCS 存储桶中的未分区或已分区文件夹中后，即可以在 [AWS Glue](https://aws.amazon.com/glue/) 数据库表中进行组织。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 如果您在账户中启用了 Lake Formation，则您在 AWS Serverless Application Repository 中部署的 Athena 联合身份 Lambda 连接器的 IAM 角色必须在 Lake Formation 中具有 AWS Glue Data Catalog 的读取权限。 有关介绍如何使用 Athena 对 GCS 存储桶中的 Parquet 或 CSV 文件运行查询的文章，请参阅 AWS 大数据博客文章使用 [Use Amazon Athena to query data stored in Google Cloud Platform](https://aws.amazon.com/blogs/big-data/use-amazon-athena-to-query-data-stored-in-google-cloud-platform/)。 ## 先决条件 + 根据您在 Google Cloud Storage 中的存储桶和文件夹设置对应的 AWS Glue 数据库和表。有关详细步骤，请参阅本文档后面的 [在 AWS Glue 中设置数据库和表](#connectors-gcs-setting-up-databases-and-tables-in-glue) 部分。 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 目前，此连接器仅支持分区列的 `VARCHAR` 类型（AWS Glue 表 Schema 中的 `string` 或 `varchar`）。当您在 Athena 中查询其他分区字段类型时会引发错误。 ## 术语 以下术语与 GCS 连接器有关。 + **处理程序** – 访问您的 GCS 存储桶的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** – 从您的 GCS 存储桶中检索元数据的 Lambda 处理程序。 + **记录处理程序** – 从您的 GCS 存储桶中检索数据记录的 Lambda 处理程序。 + **复合处理程序** – 从您的 GCS 存储桶中检索元数据和数据记录的 Lambda 处理程序。 ## 支持的文件类型 GCS 连接器支持 Parquet 和 CSV 文件类型。 **注意** 注意不要将 CSV 和 Parquet 文件放在同一 GCS 存储桶或路径中。这样做可能会导致尝试以 CSV 格式读取 Parquet 文件，或相反操作，从而出现运行时错误。 ## 参数 使用本节中的参数来配置 GCS 连接器。 **注意** 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 连接对象来配置 GCS 连接器。要执行此操作，请将 GCS 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type GOOGLECLOUDSTORAGE ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 GCS 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 GCS 连接器仅支持 `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)时。 + **secret\$1manager\$1gcp\$1creds\$1name** - AWS Secrets Manager 中的密钥名称，包含 JSON 格式的 GCS 凭证（例如 `GoogleCloudPlatformCredentials`)。 ## 在 AWS Glue 中设置数据库和表 由于 GCS 连接器的内置 Schema 推理能力有限，因此我们建议您使用 AWS Glue 来处理元数据。下面的过程演示了如何在 AWS Glue 中创建您可以从 Athena 访问的数据库和表。 ### 在 AWS Glue 中创建数据库 您可以通过 AWS Glue 控制台创建可以与 GCS 连接器一起使用的数据库。 **在 AWS Glue 创建数据库** 1. 登录 AWS 管理控制台，然后打开 AWS Glue 控制台，网址为：[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)。 1. 从导航窗格中选择 **Databases**（数据库）。 1. 选择 **Add database**（添加数据库）。 1. 对于 **Name**（名称），输入您要用于 GCS 连接器的数据库名称。 1. 在**位置**中，指定 `google-cloud-storage-flag`。此位置将告诉 GCS 连接器，AWS Glue 数据库包含要在 Athena 中查询的 GCS 数据的表。此连接器会识别 Athena 中具有此标志的数据库，并且会忽略没有此标志的数据库。 1. 选择**创建数据库**。 ### 在 AWS Glue 中创建表 现在您可以为该数据库创建一个表。创建用于 GCS 连接器的 AWS Glue 表时，您必须指定额外的元数据。 **在 AWS Glue 控制台中创建表** 1. 在 AWS Glue 控制台中，从导航窗格中选择 **Tables**（表）。 1. 在 **Tables**（表）页面上，选择 **Add table**（添加表）。 1. 在 **Set table properties**（设置表属性）页面上，输入以下信息。 + **Name**（名称）– 输入表的唯一名称。 + **Database**（数据库）– 选择您为 GCS 连接器创建的 AWS Glue 数据库。 + **Include path**（包含路径）– 对于 **Data store**（数据存储）部分中的 **Include path**（包含路径），输入前缀为 `gs://` 的 GCS URI 位置（例如 `gs://gcs_table/data/`）。如果您有一个或多个分区文件夹，请不要将其包含在路径中。 **注意** 当您输入非 `s3://` 表路径时，AWS Glue 控制台会显示错误。您可以忽略该错误。该表将会成功创建。 + **Data format**（数据格式）–对于 **Classification**（分类），选择 **CSV** 或 **Parquet**。 1. 选择**下一步**。 1. 在 **Choose or define schema**（选择或定义 Schema）页面上，强烈建议定义表 Schema，但这不是强制性的。如果您未定义 Schema，GCS 连接器会尝试为您推断 Schema。 请执行以下操作之一： + 如果您希望 GCS 连接器尝试为您推断 Schema，请选择 **Next**（下一步），然后选择 **Create**（创建）。 + 要自己定义 Schema，请执行下一部分中的步骤。 ### 在 AWS Glue 中定义表 Schema 在 AWS Glue 中定义表 Schema 需要更多步骤，但可以更好地控制表创建过程。 **在 AWS Glue 中定义表 Schema** 1. 在 **Choose or define schema**（选择或定义 Schema）页面上，选择 **Add**（添加）。 1. 在 **Add schema entry**（添加 Schema 条目）对话框中提供列名称和数据类型。 1. 要将该列指定为分区列，请选中 **Set as partition key**（设为分区键）选项。 1. 选择 **Save**（保存）以保存更改。 1. 选择 **Add**（添加）以添加其他列。 1. 添加完列后，选择 **Next**（下一步）。 1. 在 **Review and create**（检查并创建）页面上检查表，然后选择 **Create**（创建）。 1. 如果您的 Schema 包含分区信息，请按照下一部分中的步骤，在 AWS Glue 中为表的属性添加分区模式。 ### 在 AWS Glue 中将分区模式添加到表属性 如果您的 GCS 存储桶有分区，则必须在 AWS Glue 中将分区模式添加到表属性中。 **在 AWS Glue 中将分区信息添加到表属性** 1. 在您在 AWS Glue 中创建的表格的详细信息页面上，选择 **Actions**（操作），然后选择 **Edit table**（编辑表）。 1. 在 **Edit table**（编辑表）页面上，向下滚动到 **Table properties**（表属性）部分。 1. 选择 **Add**（添加）以添加分区键。 1. 对于**键**，输入 **partition.pattern**。此键将会定义文件夹路径模式。 1. 对于 **Value**（值），输入文件夹路径模式（例如 **StateName=\$1\$1statename\$1/ZipCode=\$1\$1zipcode\$1/**），其中用 **\$1\$1\$1** 括起来的 **statename** 和 **zipcode** 是分区列名称。GCS 连接器支持 Hive 和非 Hive 分区 Schema。 1. 完成后，选择 **Save**。 1. 要查看刚才创建的表属性，请选择 **Advanced properties**（高级属性）选项卡。 然后，您可以导航到 Athena 控制台。您可以在 Athena 中查询您在 AWS Glue 中创建的数据库和表。 ## 数据类型支持 下表显示了支持的 CSV 和 Parquet 数据类型。 ### CSV **** | **数据性质** | **推断的数据类型** | | --- | --- | | 数据看起来像一个数字 | BIGINT | | 数据看起来像一个字符串 | VARCHAR | | 数据看起来像一个浮点数（浮点、双精度或十进制） | DOUBLE | | 数据看起来像一个日期 | Timestamp | | 数据包含 true/false 值 | BOOL | ### Parquet **** | **PARQUET** | **Athena（箭头）** | | --- | --- | | BINARY | VARCHAR | | BOOLEAN | BOOL | | DOUBLE | DOUBLE | | ENUM | VARCHAR | | FIXED\$1LEN\$1BYTE\$1ARRAY | DECIMAL | | FLOAT | FLOAT（32 位） | | INT32 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-gcs.html) | | INT64 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-gcs.html) | | INT96 | Timestamp | | MAP | MAP | | STRUCT | STRUCT | | LIST | LIST | ## 所需权限 有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-gcs.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/athena-gcs.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **AWS Glue Data Catalog** – GCS 连接器需要 AWS Glue Data Catalog 的只读访问权限，以获取 Schema 信息。 + **CloudWatch Logs** – 该连接器需要针对 CloudWatch Logs 的访问权限，以存储日志。 ## 性能 当表 Schema 包含分区字段并且 `partition.pattern` 表属性配置正确时，可以在查询的 `WHERE` 子句中包含该分区字段。对于此类查询，GCS 连接器使用分区列来优化 GCS 文件夹路径，避免扫描 GCS 文件夹中不需要的文件。 对于 Parquet 数据集，选择列的子集可减少要扫描的数据量。这通常可在应用列投影时缩短查询执行时间。 CSV 数据集不支持列投影，并且不会减少扫描的数据量。 `LIMIT` 子句可减少扫描的数据量，但如果未提供谓词，则预期要使用包含 `LIMIT` 子句的 `SELECT` 查询来扫描至少 16 MB 的数据。无论是否应用 `LIMIT` 子句，GCS 连接器为较大数据集扫描的数据量都高于较小的数据集。例如，查询 `SELECT * LIMIT 10000` 为较大基础数据集扫描的数据高于较小的基础数据集。 ### 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ### 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-gcs)。 # Amazon Athena HBase 连接器 Amazon Athena HBase 连接器使 Amazon Athena 可以与 Apache HBase 实例通信，以便您可以使用 SQL 查询 HBase 数据。 与传统的关系数据存储不同，HBase 集合没有集架构。HBase 没有元数据存储。HBase 集合中的每个条目均可具有不同字段和数据类型。 HBase 连接器支持两种生成表架构信息的机制：基本架构推理和 AWS Glue Data Catalog 元数据。 默认设置为架构推理。此选项将扫描您的集合中的少量文档，形成所有字段的并集，并强制使用非重叠数据类型的字段。此选项适用于条目大多为统一的集合。 对于具有更多数据类型的集合，该连接器支持从 AWS Glue Data Catalog 检索元数据。如果该连接器发现与您的 HBase 命名空间和集合名称相匹配的 AWS Glue 数据库和表，它将从相应的 AWS Glue 表中获取其架构信息。在您创建 AWS Glue 表时，我们建议您将其设置为您可能想从 HBase 集合访问的所有字段的超集。 如果您在账户中启用了 Lake Formation，则您在 AWS Serverless Application Repository 中部署的 Athena 联合身份 Lambda 连接器的 IAM 角色必须在 Lake Formation 中具有 AWS Glue Data Catalog 的读取权限。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 参数 使用本节中的参数来配置 HBase 连接器。 **注意** 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 连接对象来配置 HBase 连接器。要执行此操作，请将 HBase 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type HBASE ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 HBase 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 HBase 连接器仅支持 `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 检索补充元数据。 + **glue\$1catalog** –（可选）使用此选项指定[跨账户 AWS Glue 目录](data-sources-glue-cross-account.md)。默认情况下，该连接器将尝试从其自己的 AWS Glue 账户中获取元数据。 + **default\$1hbase** – 如果存在，则指定在不存在特定于目录的环境变量时要使用的 HBase 连接字符串。 + **enable\$1case\$1insensitive\$1match** –（可选）如果是 `true`，则对 HBase 中的表名执行不区分大小写的搜索。默认值为 `false`。如果查询包含大写的表名，则使用该参数。 #### 指定连接字符串 您可以提供一个或多个属性，用于定义与该连接器配合使用的 HBase 实例的 HBase 连接详细信息。为此，请设置一个与您要在 Athena 中使用的目录名称相对应的 Lambda 环境变量。例如，假设您要使用以下查询来查询 Athena 中的两个不同 HBase 实例： ``` SELECT * FROM "hbase_instance_1".database.table ``` ``` SELECT * FROM "hbase_instance_2".database.table ``` 您必须向 Lambda 函数中添加以下两个环境变量，然后才能使用这两个 SQL 语句：`hbase_instance_1` 和 `hbase_instance_2`。每个环境变量的值均应为以下格式的 HBase 连接字符串： ``` master_hostname:hbase_port:zookeeper_port ``` ##### 使用密钥 您可以选择将 AWS Secrets Manager 用于您的连接字符串详细信息的部分值或全部值。要将 Athena 联合查询功能与 Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 如果您使用语法 `${my_secret}` 将来自 Secrets Manager 的密钥的名称放入您的连接字符串中，该连接器会将该密钥名称替换为来自 Secrets Manager 的您的用户名和密码值。 例如，假设您将 `hbase_instance_1` 的 Lambda 环境变量设置为以下值： ``` ${hbase_host_1}:${hbase_master_port_1}:${hbase_zookeeper_port_1} ``` Athena 查询联合软件开发工具包 (SDK) 将自动尝试从 Secrets Manager 检索名为的密钥 `hbase_instance_1_creds` 的密钥，然后注入该值来替换 `${hbase_instance_1_creds}`。`${ }` 字符组合所包含的该连接字符串的任何部分将被解释为来自 Secrets Manager 的密钥。如果您指定了该连接器在 Secrets Manager 中无法找到的密钥名称，则该连接器不会替换该文本。 ## 在 AWS Glue 中设置数据库和表 该连接器的内置架构推理仅支持在 HBase 中序列化为字符串的值（例如，`String.valueOf(int)`)。由于该连接器的内置架构推理功能有限，因此您可能需要改为将 AWS Glue 用于元数据。要使 AWS Glue 表可与 HBase 配合使用，您必须拥有名称与 HBase 命名空间相匹配的 AWS Glue 数据库和表，以及您要为其提供补充元数据的表。使用 HBase 列系列命名约定是可选的，但不是必需的。 **将 AWS Glue 表用于补充元数据** 1. 当您在 AWS Glue 控制台中编辑表和数据库时，可以添加以下表属性： + **hbase-metadata-flag** – 此属性将向 HBase 连接器指明该连接器可将该表用于补充元数据。只要表属性的列表中存在 `hbase-metadata-flag` 属性，您就可以为 `hbase-metadata-flag` 提供任何值。 + **hbase-native-storage-flag** – 可以使用此标记切换该连接器支持的两种值序列化模式。默认情况下，当此字段不存在时，该连接器将假定所有值都以字符串形式存储在 HBase 中。因此，它将尝试解析来自 HBase 的字符串形式的数据类型（如 `INT`、`BIGINT` 和 `DOUBLE`）。如果使用 AWS Glue 中的表上的任何值设置此字段，该连接器将切换到“本机”存储模式，并尝试使用以下函数以字节形式读取 `INT`、`BIGINT`、`BIT` 和 `DOUBLE`： ``` ByteBuffer.wrap(value).getInt() ByteBuffer.wrap(value).getLong() ByteBuffer.wrap(value).get() ByteBuffer.wrap(value).getDouble() ``` 1. 请确保使用适合 AWS Glue 的数据类型，如本文档中所列。 ### 为列系列建模 Athena HBase 连接器支持两种为 HBase 列系列建模的方法：完全限定（扁平化）命名（如 `family:column`），或使用 `STRUCT` 对象。 在 `STRUCT` 模型中，`STRUCT` 字段的名称应与列系列相匹配，并且 `STRUCT` 的子级应与该系列的列名称相匹配。但是，由于复杂类型（如 `STRUCT`）尚不完全支持谓词下推和列式读取，因此目前不建议使用 `STRUCT`。 下图显示了使用两种方法的组合在 AWS Glue 中配置的表。 ![\[在适用于 Apache Hbase 的 AWS Glue 中对列系列进行建模。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-hbase-1.png) ## 数据类型支持 该连接器将以基本字节类型的形式检索所有 HBase 值。然后，根据您在 AWS Glue Data Catalog 中定义表的方式，它会将值映射到下表中的一种 Apache Arrow 数据类型。 **** | AWS Glue 数据类型 | Apache Arrow 数据类型 | | --- | --- | | int | INT | | bigint | BIGINT | | double | FLOAT8 | | 浮点数 | FLOAT4 | | 布尔值 | BIT | | binary | VARBINARY | | 字符串 | VARCHAR | **注意** 如果您不使用 AWS Glue 补充您的元数据，则该连接器的架构推理将仅使用数据类型 `BIGINT`、`FLOAT8` 和 `VARCHAR`。 ## 所需权限 有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-hbase.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hbase/athena-hbase.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **AWS Glue Data Catalog** – HBase 连接器需要针对 AWS Glue Data Catalog 的只读访问权限，以获取架构信息。 + **CloudWatch Logs** – 该连接器需要针对 CloudWatch Logs 的访问权限，以存储日志。 + **AWS Secrets Manager 读取权限** - 如果您选择在 Secrets Manager 中存储 HBase 端点详细信息，则必须授予该连接器针对这些秘密的访问权限。 + **VPC 访问权限** - 该连接器需要能够连接和断开您的 VPC 接口，以便它能连接到 VPC 并与您的 HBase 实例通信。 ## 性能 Athena HBase 连接器将尝试通过并行读取每个区域服务器，来并行处理针对您的 HBase 实例的查询。Athena HBase 连接器可执行谓词下推，以减少查询扫描的数据量。 Lambda 函数还执行*投影*下推，以减少查询扫描的数据。但是，选择列的子集有时会导致更长的查询执行运行时。`LIMIT` 子句可减少扫描的数据量，但如果未提供谓词，则预期要使用包含 `LIMIT` 子句的 `SELECT` 查询来扫描至少 16 MB 的数据。 HBase 容易出现查询失败和不同的查询执行时间。您可能需要多次重试查询才能成功。HBase 连接器能够灵活地应对并发造成的节流。 ## 传递查询 HBase 连接器支持[传递查询](federated-query-passthrough.md)，并且以 NoSQL 为基础。有关使用筛选查询 Apache HBase 的信息，请参阅 Apache 文档中的 [Filter language](https://hbase.apache.org/book.html#thrift.filter_language)。 要在 HBase 中执行传递查询，请使用以下语法： ``` SELECT * FROM TABLE( system.query( database => 'database_name', collection => 'collection_name', filter => '{query_syntax}' )) ``` 以下 HBase 传递查询示例对 `default` 数据库 `employee` 集合中年龄为 24 或 30 岁的员工进行了筛选。 ``` SELECT * FROM TABLE( system.query( DATABASE => 'default', COLLECTION => 'employee', FILTER => 'SingleColumnValueFilter(''personaldata'', ''age'', =, ''binary:30'')' || ' OR SingleColumnValueFilter(''personaldata'', ''age'', =, ''binary:24'')' )) ``` ## 许可证信息 Amazon Athena HBase 连接器项目已经根据 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)获得许可。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hbase)。 # Amazon Athena HortonWorks 连接器 适用于 Hortonworks 的 Amazon Athena 连接器使 Amazon Athena 能够在 Cloudera [Hortonworks](https://www.cloudera.com/products/hdp.html) 数据平台上运行 SQL 查询。该连接器会将您的 Athena SQL 查询转换为其等效的 HiveQL 语法。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 ## 术语 以下术语与 Hortonworks Hive 连接器有关。 + **数据库实例** - 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Hortonworks Hive 连接器。 ### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` hive://${jdbc_connection_string} ``` ### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | HiveMuxCompositeHandler | | 元数据处理程序 | HiveMuxMetadataHandler | | 记录处理程序 | HiveMuxRecordHandler | #### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myhivecatalog，则环境变量名称是 myhivecatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Hive MUX Lambda 函数：`hive1`（默认）和 `hive2`。 **** | 属性 | 值 | | --- | --- | | default | hive://jdbc:hive2://hive1:10000/default?\$1\$1Test/RDS/hive1\$1 | | hive\$1catalog1\$1connection\$1string | hive://jdbc:hive2://hive1:10000/default?\$1\$1Test/RDS/hive1\$1 | | hive\$1catalog2\$1connection\$1string | hive://jdbc:hive2://hive2:10000/default?UID=sample&PWD=sample | #### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/hive1host}`。 ``` hive://jdbc:hive2://hive1host:10000/default?...&${Test/RDS/hive1host}&... ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` hive://jdbc:hive2://hive1host:10000/default?...&UID=sample2&PWD=sample2&... ``` 目前，Hortonworks Hive 连接器可以识别 `UID` 和 `PWD` JDBC 属性。 ### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Hortonworks Hive 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | HiveCompositeHandler | | 元数据处理程序 | HiveMetadataHandler | | 记录处理程序 | HiveRecordHandler | #### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 Hortonworks Hive 实例。 **** | 属性 | 值 | | --- | --- | | default | hive://jdbc:hive2://hive1host:10000/default?secret=\$1\$1Test/RDS/hive1host\$1 | ### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC、Hortonworks Hive 和 Arrow 的相应数据类型。 **** | JDBC | Hortonworks Hive | Arrow | | --- | --- | --- | | 布尔值 | 布尔值 | Bit | | 整数 | TINYINT | Tiny | | 短型 | SMALLINT | Smallint | | 整数 | INT | Int | | 长整型 | BIGINT | Bigint | | 浮点数 | float4 | Float4 | | 双精度 | float8 | Float8 | | 日期 | date | DateDay | | Timestamp | timestamp | DateMilli | | 字符串 | VARCHAR | Varchar | | 字节 | bytes | Varbinary | | BigDecimal | 十进制 | 十进制 | | ARRAY | 不适用（见注释） | 列表 | **注意** 目前，Hortonworks Hive 不支持聚合类型 `ARRAY`、`MAP`、`STRUCT` 或 `UNIONTYPE`。聚合类型的列被视为 SQL 中的 `VARCHAR` 列。 ## 分区和拆分 分区用于确定如何为该连接器生成拆分。Athena 将构建一个 `varchar` 类型的合成列，它将展示表的分区方案，以帮助该连接器生成拆分。该连接器不会修改实际的表定义。 ## 性能 Hortonworks Hive 支持静态分区。Athena Hortonworks Hive 连接器可从这些分区并行检索数据。如果您想查询具有均匀分区分布的非常大的数据集，强烈建议使用静态分区。选择列的子集可以显著减少查询运行时及扫描的数据。Hortonworks Hive 连接器能够灵活地应对并发造成的节流。 Athena Hortonworks Hive 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Hortonworks Hive 连接器可以组合这些表达式并将其直接推送到 Hortonworks Hive，以增强功能并减少扫描的数据量。 以下 Athena Hortonworks Hive 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 传递查询 Hortonworks Hive 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Hortonworks Hive 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Hortonworks Hive 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参阅 GitHub.com 上适用于 Hortonworks Hive 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hortonworks-hive)。 # Amazon Athena Apache Kafka 连接器 可通过适用于 Apache Kafka 的 Amazon Athena 连接器支持 Amazon Athena 对 Apace Kafka 主题运行 SQL 查询。使用此连接器在 Athena 中以表的形式查看 [Apache Kafka](https://kafka.apache.org/) 主题，以行的形式查看消息。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 ## 先决条件 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《AWS Lambda 开发人员指南》**中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 必须将筛选条件中的日期和时间戳数据类型转换为适当的数据类型。 + CSV 文件类型不支持日期和时间戳数据类型，它们被视为 VARCHAR 值。 + 不支持映射到嵌套 JSON 字段。连接器仅映射顶级字段。 + 连接器不支持复杂类型。复杂类型解释为字符串。 + 要提取或处理复杂的 JSON 值，请使用 Athena 中可用的 JSON 相关函数。有关更多信息，请参阅 [从字符串中提取 JSON 数据](extracting-data-from-JSON.md)。 + 连接器不支持对 Kafka 消息元数据的访问。 ## 术语 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **Kafka 端点** – 文本字符串，用于建立与 Kafka 实例的连接。 ## 集群兼容性 Kafka 连接器可用于以下集群类型。 + **独立 Kafka** - 与 Kafka 直接连接（经过或未经身份验证）。 + **Confluent** - 与 Confluent Kafka 直接连接。有关将 Athena 与 Confluent Kafka 数据配合使用的信息，请参阅 *AWS 商业智能博客*中的 [Visualize Confluent data in Quick using Amazon Athena](https://aws.amazon.com/blogs/business-intelligence/visualize-confluent-data-in-amazon-quicksight-using-amazon-athena/)。 ### 连接到 Confluent 要连接到 Confluent，需要执行以下步骤： 1. 从 Confluent 生成 API 密钥。 1. 将 Confluent API 密钥的用户名和密码存储到 AWS Secrets Manager 中。 1. 在 Kafka 连接器中提供 `secrets_manager_secret` 环境变量的密钥名称。 1. 按照本文档的 [设置 Kafka 连接器](#connectors-kafka-setup) 节中的步骤执行操作。 ## 支持的身份验证方法 连接器支持以下身份验证方法。 + [SSL](https://kafka.apache.org/documentation/#security_ssl) + [SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram) + SASL/PLAIN + SASL/PLAINTEXT + NO\$1AUTH + **自行管理的 Kafka 和 Confluent 平台** – SSL、SASL/SCRAM、SASL/PLAINTEXT、NO\$1AUTH + **自行管理的 Kafka 和 Confluent Cloud** - SASL/PLAIN 有关更多信息，请参阅 [为 Athena Kafka 连接器配置身份验证](#connectors-kafka-setup-configuring-authentication)。 ## 支持的输入数据格式 连接器支持以下输入数据格式。 + JSON + CSV + AVRO + PROTOBUF (PROTOCOL BUFFERS) ## 参数 使用本节中的参数来配置 Athena Kafka 连接器。 + **auth\$1type** – 指定集群的身份验证类型。连接器支持以下身份验证类型： + **NO\$1AUTH** - 直接连接到 Kafka（例如，连接到部署在 EC2 实例上的 Kafka 集群，但不使用身份验证）。 + **SASL\$1SSL\$1PLAIN** – 此方法使用 `SASL_SSL` 安全协议和 `PLAIN` SASL 机制。有关更多信息，请参阅 Apache Kafka 文档中的 [SASL 配置](https://kafka.apache.org/documentation/#security_sasl_config)。 + **SASL\$1PLAINTEXT\$1PLAIN** – 此方法使用 `SASL_PLAINTEXT` 安全协议和 `PLAIN` SASL 机制。有关更多信息，请参阅 Apache Kafka 文档中的 [SASL 配置](https://kafka.apache.org/documentation/#security_sasl_config)。 + **SASL\$1SSL\$1SCRAM\$1SHA512** - 您可以使用此身份验证类型控制对 Apache Kafka 集群的访问权限。此方法将用户名和密码存储在 AWS Secrets Manager 中。密钥必须与 Kafka 集群相关。有关更多信息，请参阅 Apache Kafka 文档中的[使用 SASL/SCRAM 进行身份验证](https://kafka.apache.org/documentation/#security_sasl_scram)。 + **SASL\$1PLAINTEXT\$1SCRAM\$1SHA512** - 此方法使用 `SASL_PLAINTEXT` 安全协议和 `SCRAM_SHA512 SASL` 机制。此方法使用存储在 AWS Secrets Manager 中的用户名和密码。有关更多信息，请参阅 Apache Kafka 文档中的 [SASL 配置](https://kafka.apache.org/documentation/#security_sasl_config)一节。 + **SSL** - SSL 身份验证使用密钥存储和信任存储文件来连接 Apache Kafka 集群。您必须生成信任存储和密钥存储文件，将其上传到 Amazon S3 存储桶，并在部署连接器时提供对 Amazon S3 的引用。密钥存储、信任存储和 SSL 密钥存储在 AWS Secrets Manager 中。部署连接器时需要提供 AWS 私有密钥。有关更多信息，请参阅 Apache Kafka 文档中的[使用 SSL 进行加密和身份验证](https://kafka.apache.org/documentation/#security_ssl)。 有关更多信息，请参阅 [为 Athena Kafka 连接器配置身份验证](#connectors-kafka-setup-configuring-authentication)。 + **certificates\$1s3\$1reference** – 包含证书（密钥存储和信任存储文件）的 Amazon S3 位置。 + **disable\$1spill\$1encryption** -（可选）当设置为 `True` 时，将禁用溢出加密。默认值为 `False`，此时将使用 AES-GCM 对溢出到 S3 的数据使用进行加密 - 使用随机生成的密钥，或者使用 KMS 生成密钥。禁用溢出加密可以提高性能，尤其是当您的溢出位置使用[服务器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)时。 + **kafka\$1endpoint** – 提供给 Kafka 的端点详细信息。 + **schema\$1registry\$1url** – 架构注册表的 URL 地址（例如 `http://schema-registry.example.org:8081`）。适用于 `AVRO` 和 `PROTOBUF` 数据格式。Athena 仅支持 Confluent 架构注册表。 + **secrets\$1manager\$1secret** – 保存凭证的 AWS 密钥名称。 + **溢出参数** – Lambda 函数将不适合内存的数据临时存储（“溢出”）到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。使用下表中的参数指定溢出位置。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-kafka.html) + **子网 ID** - 与 Lambda 函数可用于访问数据来源的子网对应的一个或多个子网 ID。 + **公有 Kafka 集群或标准 Confluent Cloud 集群** - 将连接器与具有 NAT 网关的私有子网关联。 + **具有私有连接的 Confluent Cloud 集群** - 将连接器与具有通往 Confluent Cloud 集群的路由的私有子网关联。 + 对于 [AWS 中转网关](https://docs.confluent.io/cloud/current/networking/aws-transit-gateway.html)，子网必须位于连接到 Confluent Cloud 使用的相同中转网关的 VPC 中。 + 对于 [VPC 对等](https://docs.confluent.io/cloud/current/networking/peering/aws-peering.html)，子网必须位于与 Confluent Cloud VPC 对等的 VPC 中。 + 对于 [AWS PrivateLink](https://docs.confluent.io/cloud/current/networking/private-links/aws-privatelink.html)，子网必须位于具有通往 VPC 端点的路由的 VPC 中，该端点连接到 Confluent Cloud。 **注意** 如果您将连接器部署到 VPC 中以访问私有资源，并且还想连接到 Confluent 等可公开访问的服务，则必须将连接器关联到某个具有 NAT 网关的私有子网。有关更多信息，请参阅《Amazon VPC 用户指南》中的 [NAT 网关](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)。 ## 数据类型支持 下表显示了 Kafka 和 Apache Arrow 支持的相应数据类型。 **** | Kafka | Arrow | | --- | --- | | CHAR | VARCHAR | | VARCHAR | VARCHAR | | TIMESTAMP | MILLISECOND | | DATE | DAY | | BOOLEAN | BOOL | | SMALLINT | SMALLINT | | INTEGER | INT | | BIGINT | BIGINT | | DECIMAL | FLOAT8 | | DOUBLE | FLOAT8 | ## 分区和拆分 Kafka 主题分为多个分区。每个分区会进行排序。分区中的每条消息都有一个增量 ID，称为*偏移*。每个 Kafka 分区进一步分为多个分区，以进行并行处理。数据在 Kafka 集群中配置的保留期内可用。 ## 最佳实践 最佳做法是在查询 Athena 时使用谓词下推，如下例所示。 ``` SELECT * FROM "kafka_catalog_name"."glue_schema_registry_name"."glue_schema_name" WHERE integercol = 2147483647 ``` ``` SELECT * FROM "kafka_catalog_name"."glue_schema_registry_name"."glue_schema_name" WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878' ``` ## 设置 Kafka 连接器 在使用连接器之前，您必须设置 Apache Kafka 集群，使用 [AWS Glue 架构注册表](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)定义架构，并为连接器配置身份验证。 使用 AWS Glue 架构注册表时，请注意以下几点： + 确保 AWS Glue 架构注册表的 **Description**（描述）字段中的文本包含 `{AthenaFederationKafka}` 字符串。此标记字符串是与 Amazon Athena Kafka 连接器一起使用的 AWS Glue 注册表中的必需项。 + 为了获得最佳性能，数据库名称和表名称仅限使用小写。使用混合大小写会使连接器执行不区分大小写的搜索，这种搜索的计算密集度更高。 **设置 Apache Kafka 环境和 AWS Glue 架构注册表** 1. 设置 Apache Kafka 环境。 1. 将 JSON 格式的 Kafka 主题描述文件（即其架构）上传到 AWS Glue 架构注册表。有关更多信息，请参阅《AWS Glue 开发人员指南》中的[与 AWS Glue 架构注册表集成](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html)。 1. 要在 AWS Glue 架构注册表中定义架构时使用 `AVRO` 或 `PROTOBUF` 数据格式，请执行以下操作： + 对于**架构名称**，以原始名称相同的大小写输入 Kafka 主题名称。 + 对于**数据格式**，选择 **Apache Avro** 或 **Protocol Buffers**。 有关详细示例，请参阅以下章节。 ### AWS Glue 架构注册表的架构示例 将架构上传到 [AWS Glue 架构注册表](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)时，请使用本节中的示例格式。 #### JSON 类型架构示例 在以下示例中，要在 AWS Glue 架构注册表中创建的架构指定 `json` 作为 `dataFormat` 的值，并将 `datatypejson` 用于 `topicName`。 **注意** `topicName` 的值应使用与 Kafka 中主题名称相同的大小写。 ``` { "topicName": "datatypejson", "message": { "dataFormat": "json", "fields": [ { "name": "intcol", "mapping": "intcol", "type": "INTEGER" }, { "name": "varcharcol", "mapping": "varcharcol", "type": "VARCHAR" }, { "name": "booleancol", "mapping": "booleancol", "type": "BOOLEAN" }, { "name": "bigintcol", "mapping": "bigintcol", "type": "BIGINT" }, { "name": "doublecol", "mapping": "doublecol", "type": "DOUBLE" }, { "name": "smallintcol", "mapping": "smallintcol", "type": "SMALLINT" }, { "name": "tinyintcol", "mapping": "tinyintcol", "type": "TINYINT" }, { "name": "datecol", "mapping": "datecol", "type": "DATE", "formatHint": "yyyy-MM-dd" }, { "name": "timestampcol", "mapping": "timestampcol", "type": "TIMESTAMP", "formatHint": "yyyy-MM-dd HH:mm:ss.SSS" } ] } } ``` #### CSV 类型架构示例 在以下示例中，要在 AWS Glue 架构注册表中创建的架构指定 `csv` 作为 `dataFormat` 的值，并将 `datatypecsvbulk` 用于 `topicName`。`topicName` 的值应使用与 Kafka 中主题名称相同的大小写。 ``` { "topicName": "datatypecsvbulk", "message": { "dataFormat": "csv", "fields": [ { "name": "intcol", "type": "INTEGER", "mapping": "0" }, { "name": "varcharcol", "type": "VARCHAR", "mapping": "1" }, { "name": "booleancol", "type": "BOOLEAN", "mapping": "2" }, { "name": "bigintcol", "type": "BIGINT", "mapping": "3" }, { "name": "doublecol", "type": "DOUBLE", "mapping": "4" }, { "name": "smallintcol", "type": "SMALLINT", "mapping": "5" }, { "name": "tinyintcol", "type": "TINYINT", "mapping": "6" }, { "name": "floatcol", "type": "DOUBLE", "mapping": "7" } ] } } ``` #### AVRO 类型架构示例 以下示例用于在 AWS Glue 架构注册表中创建基于 AVRO 的架构。在 AWS Glue 架构注册表中定义架构时，对于**架构名称**，以原始名称相同的大小写输入 Kafka 主题名称；对于**数据格式**，选择 **Apache Avro**。由于您直接在注册表中指定了此信息，因此 `dataformat` 和 `topicName` 字段不是必填字段。 ``` { "type": "record", "name": "avrotest", "namespace": "example.com", "fields": [{ "name": "id", "type": "int" }, { "name": "name", "type": "string" } ] } ``` #### PROTOBUF 类型架构示例 以下示例用于在 AWS Glue 架构注册表中创建基于 PROTOBUF 的架构。在 AWS Glue 架构注册表中定义架构时，对于**架构名称**，以原始名称相同的大小写输入 Kafka 主题名称；对于**数据格式**，选择 **Protocol Buffers**。由于您直接在注册表中指定了此信息，因此 `dataformat` 和 `topicName` 字段不是必填字段。第一行将架构定义为 PROTOBUF。 ``` syntax = "proto3"; message protobuftest { string name = 1; int64 calories = 2; string colour = 3; } ``` 有关在 AWS Glue 架构注册表中添加注册表和架构的更多信息，请参阅 AWS Glue 文档中的[架构注册表入门](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-gs.html)。 ### 为 Athena Kafka 连接器配置身份验证 您可以使用多种方法对 Apache Kafka 集群进行身份验证，包括 SSL、SASL/SCRAM、SASL/PLAIN 和 SASL/PLAINTEXT。 下表显示了连接器的身份验证类型以及每种连接器的安全协议和 SASL 机制。有关更多信息，请参阅 Apache Kafka 文档中的[安全性](https://kafka.apache.org/documentation/#security)一节。 **** | auth\$1type | security.protocol | sasl.mechanism | 集群类型兼容性 | | --- | --- | --- | --- | | SASL\$1SSL\$1PLAIN | SASL\$1SSL | PLAIN | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-kafka.html) | | SASL\$1PLAINTEXT\$1PLAIN | SASL\$1PLAINTEXT | PLAIN | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-kafka.html) | | SASL\$1SSL\$1SCRAM\$1SHA512 | SASL\$1SSL | SCRAM-SHA-512 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-kafka.html) | | SASL\$1PLAINTEXT\$1SCRAM\$1SHA512 | SASL\$1PLAINTEXT | SCRAM-SHA-512 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-kafka.html) | | SSL | SSL | 不适用 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-kafka.html) | #### SSL 如果集群经过 SSL 身份验证，则您必须生成信任存储和密钥存储文件，并将其上传到 Amazon S3 存储桶。部署连接器时，必须提供此 Amazon S3 参考资料。密钥存储、信任存储和 SSL 密钥存储在 AWS Secrets Manager 中。部署连接器时需要提供 AWS 密钥。 有关在 Secrets Manager 中创建密钥的信息，请参阅[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。 要使用此身份验证类型，请按下表所示设置环境变量。 **** | 参数 | 值 | | --- | --- | | auth\$1type | SSL | | certificates\$1s3\$1reference | 包含证书的 Amazon S3 位置。 | | secrets\$1manager\$1secret | 您的 AWS 密钥名称。 | 在 Secrets Manager 中创建密钥后，您可以在 Secrets Manager 控制台中查看该密钥。 **在 Secrets Manager 中查看密钥** 1. 打开 Secrets Manager 控制台，网址为 [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。 1. 在导航窗格中，选择 **Secrets**（密钥）。 1. 在 **Secrets**（密钥）页面，选择密钥链接。 1. 在密钥的详细信息页面上，选择 **Retrieve secret value**（检索密钥值）。 下图显示了示例密钥，其中包含三个键值对：`keystore_password`、`truststore_password` 和 `ssl_key_password`。 ![\[在 Secrets Manager 中检索 SSL 密钥\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-kafka-setup-1.png) 有关在 Kafka 中使用 SSL 的更多信息，请参阅 Apache Kafka 文档中的[使用 SSL 进行加密和身份验证](https://kafka.apache.org/documentation/#security_ssl)。 #### SASL/SCRAM 如果您的集群使用 SCRAM 身份验证，请在部署连接器时提供与集群关联的 Secrets Manager 密钥。用户的 AWS 凭证（密钥和访问密钥）用于与集群进行身份验证。 按下表所示设置环境变量。 **** | 参数 | 值 | | --- | --- | | auth\$1type | SASL\$1SSL\$1SCRAM\$1SHA512 | | secrets\$1manager\$1secret | 您的 AWS 密钥名称。 | 下图显示了 Secrets Manager 控制台中的示例密钥，其中包含两个键值对：一个用于 `username`，另一个用于 `password`。 ![\[在 Secrets Manager 中检索 SCRAM 密钥\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-kafka-setup-2.png) 有关在 Kafka 中使用 SASL/SCRAM 的更多信息，请参阅 Apache Kafka 文档中的[使用 SASL/SCRAM 进行身份验证](https://kafka.apache.org/documentation/#security_sasl_scram)。 ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-kafka/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-kafka/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-kafka)。 # Amazon Athena MSK 连接器 使用适用于 [Amazon MSK](https://aws.amazon.com/msk/) 的 Amazon Athena 连接器，Amazon Athena 能够对 Apace Kafka 主题运行 SQL 查询。使用此连接器在 Athena 中以表的形式查看 [Apache Kafka](https://kafka.apache.org/) 主题，以行的形式查看消息。有关更多信息，请参阅 AWS 大数据博客中的 [Analyze real-time streaming data in Amazon MSK with Amazon Athena](https://aws.amazon.com/blogs/big-data/analyze-real-time-streaming-data-in-amazon-msk-with-amazon-athena/)（使用 Amazon Athena 分析 Amazon MSK 中的实时流数据）。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 ## 先决条件 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 必须将筛选条件中的日期和时间戳数据类型转换为适当的数据类型。 + CSV 文件类型不支持日期和时间戳数据类型，它们被视为 VARCHAR 值。 + 不支持映射到嵌套 JSON 字段。连接器仅映射顶级字段。 + 连接器不支持复杂类型。复杂类型解释为字符串。 + 要提取或处理复杂的 JSON 值，请使用 Athena 中可用的 JSON 相关函数。有关更多信息，请参阅 [从字符串中提取 JSON 数据](extracting-data-from-JSON.md)。 + 连接器不支持对 Kafka 消息元数据的访问。 ## 术语 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **Kafka 端点** – 文本字符串，用于建立与 Kafka 实例的连接。 ## 集群兼容性 MSK 连接器可用于以下集群类型。 + **MSK 预置集群** – 您可以手动指定、监控和扩展集群容量。 + **MSK 无服务器集群** – 提供随应用程序 I/O 扩展而自动扩展的按需容量。 + **独立 Kafka** - 与 Kafka 直接连接（经过或未经身份验证）。 ## 支持的身份验证方法 连接器支持以下身份验证方法。 + [SASL/IAM](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html) + [SSL](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html) + [SASL/SCRAM](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html) + SASL/PLAIN + SASL/PLAINTEXT + NO\$1AUTH 有关更多信息，请参阅 [为 Athena MSK 连接器配置身份验证](#connectors-msk-setup-configuring-authentication)。 ## 支持的输入数据格式 连接器支持以下输入数据格式。 + JSON + CSV ## 参数 使用本节中的参数来配置 Athena MSK 连接器。 + **auth\$1type** – 指定集群的身份验证类型。连接器支持以下身份验证类型： + **NO\$1AUTH** – 无需身份验证即可直接连接到 Kafka（例如，连接到部署在 EC2 实例上的 Kafka 集群，但不使用身份验证）。 + **SASL\$1SSL\$1PLAIN** – 此方法使用 `SASL_SSL` 安全协议和 `PLAIN` SASL 机制。 + **SASL\$1PLAINTEXT\$1PLAIN** – 此方法使用 `SASL_PLAINTEXT` 安全协议和 `PLAIN` SASL 机制。 **注意** Apache Kafka 支持 `SASL_SSL_PLAIN` 和 `SASL_PLAINTEXT_PLAIN` 身份验证类型，但 Amazon MSK 不支持。 + **SASL\$1SSL\$1AWS\$1MSK\$1IAM** – Amazon MSK 的 IAM 访问控制使您能够处理 MSK 集群的身份验证和授权。您用户的 AWS 凭证（密钥和访问密钥）用于与集群连接。有关更多信息，请参阅《Amazon Managed Streaming for Apache Kafka 开发人员指南》中的 [IAM access control](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html)（IAM 访问控制）。 + **SASL\$1SSL\$1SCRAM\$1SHA512** – 您可以使用这种身份验证类型来控制对 Amazon MSK 集群的访问权限。此方法将用户名和密码存储在 AWS Secrets Manager 上。密钥必须与 Amazon MSK 集群相关。有关更多信息，请参阅《Amazon Managed Streaming for Apache Kafka 开发人员指南》中的[为 Amazon MSK 集群设置 SASL/SCRAM 身份验证](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html#msk-password-tutorial)。 + **SSL** – SSL 身份验证使用密钥存储和信任存储文件来连接 Amazon MSK 集群。您必须生成信任存储和密钥存储文件，将其上传到 Amazon S3 存储桶，并在部署连接器时提供对 Amazon S3 的引用。密钥存储、信任存储和 SSL 密钥存储在 AWS Secrets Manager 中。部署连接器时需要提供 AWS 私有密钥。有关更多信息，请参阅《Amazon Managed Streaming for Apache Kafka 开发人员指南》中的 [Mutual TLS authentication](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html)（双向 TLS 身份验证）。 有关更多信息，请参阅 [为 Athena MSK 连接器配置身份验证](#connectors-msk-setup-configuring-authentication)。 + **certificates\$1s3\$1reference** – 包含证书（密钥存储和信任存储文件）的 Amazon S3 位置。 + **disable\$1spill\$1encryption** -（可选）当设置为 `True` 时，将禁用溢出加密。默认值为 `False`，此时将使用 AES-GCM 对溢出到 S3 的数据使用进行加密 - 使用随机生成的密钥，或者使用 KMS 生成密钥。禁用溢出加密可以提高性能，尤其是当您的溢出位置使用[服务器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)时。 + **kafka\$1endpoint** – 提供给 Kafka 的端点详细信息。例如，对于 Amazon MSK 集群，您可以为该集群提供[引导 URL](https://docs.aws.amazon.com/msk/latest/developerguide/msk-get-bootstrap-brokers.html)。 + **secrets\$1manager\$1secret** – 保存凭证的 AWS 密钥名称。IAM 身份验证不需要此参数。 + **溢出参数** – Lambda 函数将不适合内存的数据临时存储（“溢出”）到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。使用下表中的参数指定溢出位置。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/connectors-msk.html) ## 数据类型支持 下表显示了 Kafka 和 Apache Arrow 支持的相应数据类型。 **** | Kafka | Arrow | | --- | --- | | CHAR | VARCHAR | | VARCHAR | VARCHAR | | TIMESTAMP | MILLISECOND | | DATE | DAY | | BOOLEAN | BOOL | | SMALLINT | SMALLINT | | INTEGER | INT | | BIGINT | BIGINT | | DECIMAL | FLOAT8 | | DOUBLE | FLOAT8 | ## 分区和拆分 Kafka 主题分为多个分区。每个分区会进行排序。分区中的每条消息都有一个增量 ID，称为*偏移*。每个 Kafka 分区进一步分为多个分区，以进行并行处理。数据在 Kafka 集群中配置的保留期内可用。 ## 最佳实践 最佳做法是在查询 Athena 时使用谓词下推，如下例所示。 ``` SELECT * FROM "msk_catalog_name"."glue_schema_registry_name"."glue_schema_name" WHERE integercol = 2147483647 ``` ``` SELECT * FROM "msk_catalog_name"."glue_schema_registry_name"."glue_schema_name" WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878' ``` ## 设置 MSK 连接器 在使用连接器之前，您必须设置 Amazon MSK 集群，使用 [AWS Glue 架构注册表](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)定义架构，并为连接器配置身份验证。 **注意** 如果您将连接器部署到 VPC 中以访问私有资源，并且还想连接到 Confluent 等可公开访问的服务，则必须将连接器关联到某个具有 NAT 网关的私有子网。有关更多信息，请参阅《Amazon VPC 用户指南》中的 [NAT 网关](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)。 使用 AWS Glue 架构注册表时，请注意以下几点： + 确保 AWS Glue 架构注册表的 **Description**（描述）字段中的文本包含 `{AthenaFederationMSK}` 字符串。此标记字符串是与 Amazon Athena MSK 连接器一起使用的 AWS Glue 注册表中的必填字段。 + 为了获得最佳性能，数据库名称和表名称仅限使用小写。使用混合大小写会使连接器执行不区分大小写的搜索，这种搜索的计算密集度更高。 **设置 Amazon MSK 环境和 AWS Glue 架构注册表** 1. 设置 Amazon MSK 环境。有关信息和步骤，请参阅《Amazon Managed Streaming for Apache Kafka 开发人员指南》中的 [Setting up Amazon MSK](https://docs.aws.amazon.com/msk/latest/developerguide/before-you-begin.html)（设置 Amazon MSK）和 [Getting started using Amazon MSK](https://docs.aws.amazon.com/msk/latest/developerguide/getting-started.html)（开始使用 Amazon MSK）。 1. 将 JSON 格式的 Kafka 主题描述文件（即其架构）上传到 AWS Glue 架构注册表。有关更多信息，请参阅《AWS Glue 开发人员指南》中的[与 AWS Glue 架构注册表集成](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html)。有关详细示例，请参阅以下章节。 ### AWS Glue 架构注册表的架构示例 将架构上传到 [AWS Glue 架构注册表](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)时，请使用本节中的示例格式。 #### JSON 类型架构示例 在以下示例中，要在 AWS Glue 架构注册表中创建的架构指定 `json` 作为 `dataFormat` 的值，并将 `datatypejson` 用于 `topicName`。 **注意** `topicName` 的值应使用与 Kafka 中主题名称相同的大小写。 ``` { "topicName": "datatypejson", "message": { "dataFormat": "json", "fields": [ { "name": "intcol", "mapping": "intcol", "type": "INTEGER" }, { "name": "varcharcol", "mapping": "varcharcol", "type": "VARCHAR" }, { "name": "booleancol", "mapping": "booleancol", "type": "BOOLEAN" }, { "name": "bigintcol", "mapping": "bigintcol", "type": "BIGINT" }, { "name": "doublecol", "mapping": "doublecol", "type": "DOUBLE" }, { "name": "smallintcol", "mapping": "smallintcol", "type": "SMALLINT" }, { "name": "tinyintcol", "mapping": "tinyintcol", "type": "TINYINT" }, { "name": "datecol", "mapping": "datecol", "type": "DATE", "formatHint": "yyyy-MM-dd" }, { "name": "timestampcol", "mapping": "timestampcol", "type": "TIMESTAMP", "formatHint": "yyyy-MM-dd HH:mm:ss.SSS" } ] } } ``` #### CSV 类型架构示例 在以下示例中，要在 AWS Glue 架构注册表中创建的架构指定 `csv` 作为 `dataFormat` 的值，并将 `datatypecsvbulk` 用于 `topicName`。`topicName` 的值应使用与 Kafka 中主题名称相同的大小写。 ``` { "topicName": "datatypecsvbulk", "message": { "dataFormat": "csv", "fields": [ { "name": "intcol", "type": "INTEGER", "mapping": "0" }, { "name": "varcharcol", "type": "VARCHAR", "mapping": "1" }, { "name": "booleancol", "type": "BOOLEAN", "mapping": "2" }, { "name": "bigintcol", "type": "BIGINT", "mapping": "3" }, { "name": "doublecol", "type": "DOUBLE", "mapping": "4" }, { "name": "smallintcol", "type": "SMALLINT", "mapping": "5" }, { "name": "tinyintcol", "type": "TINYINT", "mapping": "6" }, { "name": "floatcol", "type": "DOUBLE", "mapping": "7" } ] } } ``` ### 为 Athena MSK 连接器配置身份验证 您可以使用多种方法对 Amazon MSK 集群进行身份验证，包括 IAM、SSL、SCRAM 和独立的 Kafka。 下表显示了连接器的身份验证类型以及每种连接器的安全协议和 SASL 机制。有关更多信息，请参阅《Amazon Managed Streaming for Apache Kafka 开发人员指南》中的 [Authentication and authorization for Apache Kafka APIs](https://docs.aws.amazon.com/msk/latest/developerguide/kafka_apis_iam.html)（Apache Kafka API 的身份验证和授权）。 **** | auth\$1type | security.protocol | sasl.mechanism | | --- | --- | --- | | SASL\$1SSL\$1PLAIN | SASL\$1SSL | PLAIN | | SASL\$1PLAINTEXT\$1PLAIN | SASL\$1PLAINTEXT | PLAIN | | SASL\$1SSL\$1AWS\$1MSK\$1IAM | SASL\$1SSL | AWS\$1MSK\$1IAM | | SASL\$1SSL\$1SCRAM\$1SHA512 | SASL\$1SSL | SCRAM-SHA-512 | | SSL | SSL | 不适用 | **注意** Apache Kafka 支持 `SASL_SSL_PLAIN` 和 `SASL_PLAINTEXT_PLAIN` 身份验证类型，但 Amazon MSK 不支持。 #### SASL/IAM 如果集群使用 IAM 身份验证，则在设置集群时必须为用户配置 IAM policy。有关更多信息，请参阅《Amazon Managed Streaming for Apache Kafka 开发人员指南》中的 [IAM access control](https://docs.aws.amazon.com/msk/latest/developerguide/IAM-access-control.html)（IAM 访问控制）。 要使用此身份验证类型，请将连接器的 `auth_type` Lambda 环境变量设置为 `SASL_SSL_AWS_MSK_IAM`。 #### SSL 如果集群经过 SSL 身份验证，则您必须生成信任存储和密钥存储文件，并将其上传到 Amazon S3 存储桶。部署连接器时，必须提供此 Amazon S3 参考资料。密钥存储、信任存储和 SSL 密钥存储在 AWS Secrets Manager 中。部署连接器时需要提供 AWS 密钥。 有关在 Secrets Manager 中创建密钥的信息，请参阅[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。 要使用此身份验证类型，请按下表所示设置环境变量。 **** | 参数 | 值 | | --- | --- | | auth\$1type | SSL | | certificates\$1s3\$1reference | 包含证书的 Amazon S3 位置。 | | secrets\$1manager\$1secret | 您的 AWS 密钥名称。 | 在 Secrets Manager 中创建密钥后，您可以在 Secrets Manager 控制台中查看该密钥。 **在 Secrets Manager 中查看密钥** 1. 打开 Secrets Manager 控制台，网址为 [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。 1. 在导航窗格中，选择 **Secrets**（密钥）。 1. 在 **Secrets**（密钥）页面，选择密钥链接。 1. 在密钥的详细信息页面上，选择 **Retrieve secret value**（检索密钥值）。 下图显示了示例密钥，其中包含三个键值对：`keystore_password`、`truststore_password` 和 `ssl_key_password`。 ![\[在 Secrets Manager 中检索 SSL 密钥\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-msk-setup-1.png) #### SASL/SCRAM 如果您的集群使用 SCRAM 身份验证，请在部署连接器时提供与集群关联的 Secrets Manager 密钥。用户的 AWS 凭证（密钥和访问密钥）用于与集群进行身份验证。 按下表所示设置环境变量。 **** | 参数 | 值 | | --- | --- | | auth\$1type | SASL\$1SSL\$1SCRAM\$1SHA512 | | secrets\$1manager\$1secret | 您的 AWS 密钥名称。 | 下图显示了 Secrets Manager 控制台中的示例密钥，其中包含两个键值对：一个用于 `username`，另一个用于 `password`。 ![\[在 Secrets Manager 中检索 SCRAM 密钥\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-msk-setup-2.png) ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-msk/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-msk/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-msk)。 # Amazon Athena MySQL 连接器 Amazon Athena Lambda MySQL 连接器使 Amazon Athena 可以访问 MySQL 数据库。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 + 使用此连接器前，请先设置 VPC 和安全组。有关更多信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 由于 Athena 会将查询转换为小写，所以 MySQL 表名称必须使用小写。例如，针对名为 `myTable` 的表进行的 Athena 查询将失败。 + 如果您将 MySQL 连接迁移到 Glue Catalog 和 Lake Formation，则只能识别小写的表名和列名。 ## 术语 以下术语与 MySQL 连接器有关。 + **数据库实例** - 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 MySQL 连接器。 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 MySQL 连接器。 要执行此操作，请将 MySQL 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type MYSQL ``` **Lambda 环境属性** **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 MySQL 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 MySQL 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` mysql://${jdbc_connection_string} ``` **注意** 如果您在对 MySQL 表执行 `SELECT` 查询时收到错误 java.sql.SQLException: Zero date value prohibited（java.sql.SQLException：禁止零日期值），请将以下参数添加到您的连接字符串中： ``` zeroDateTimeBehavior=convertToNull ``` 有关更多信息，请参阅 GitHub.com 上的[尝试从 MySQL 表中进行选择时出现“Zero date value prohibited”（禁止零日期值）错误](https://github.com/awslabs/aws-athena-query-federation/issues/760)。 #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | MySqlMuxCompositeHandler | | 元数据处理程序 | MySqlMuxMetadataHandler | | 记录处理程序 | MySqlMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mymysqlcatalog，则环境变量名称是 mymysqlcatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。当目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 MySql MUX Lambda 函数：`mysql1`（默认值）和 `mysql2`。 **** | 属性 | 值 | | --- | --- | | default | mysql://jdbc:mysql://mysql2.host:3333/default?user=sample2&password=sample2 | | mysql\$1catalog1\$1connection\$1string | mysql://jdbc:mysql://mysql1.host:3306/default?\$1\$1Test/RDS/MySql1\$1 | | mysql\$1catalog2\$1connection\$1string | mysql://jdbc:mysql://mysql2.host:3333/default?user=sample2&password=sample2 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/MySql1}`。 ``` mysql://jdbc:mysql://mysql1.host:3306/default?...&${Test/RDS/MySql1}&... ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` mysql://jdbc:mysql://mysql1host:3306/default?...&user=sample2&password=sample2&... ``` 目前，MySQL 连接器可以识别 `user` 和 `password` JDBC 属性。 #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 MySQL 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | MySqlCompositeHandler | | 元数据处理程序 | MySqlMetadataHandler | | 记录处理程序 | MySqlRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 MySQL 实例。 **** | 属性 | 值 | | --- | --- | | default | mysql://mysql1.host:3306/default?secret=Test/RDS/MySql1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC 和 Arrow 的相应数据类型。 **** | JDBC | Arrow | | --- | --- | | 布尔值 | Bit | | 整数 | Tiny | | 短型 | Smallint | | 整数 | Int | | 长整型 | Bigint | | 浮点数 | Float4 | | 双精度 | Float8 | | 日期 | DateDay | | Timestamp | DateMilli | | 字符串 | Varchar | | 字节 | Varbinary | | BigDecimal | 十进制 | | ARRAY | 列表 | ## 分区和拆分 分区用于确定如何为该连接器生成拆分。Athena 将构建一个 `varchar` 类型的合成列，它将展示表的分区方案，以帮助该连接器生成拆分。该连接器不会修改实际的表定义。 ## 性能 MySQL 支持本机分区。Athena MySQL 连接器可从这些分区并行检索数据。如果您想查询具有统一分区分布的超大型数据集，强烈建议使用本机分区。 Athena MySQL 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena MySQL 连接器可以组合这些表达式并将其直接推送到 MySQL，以增强功能并减少扫描的数据量。 以下 Athena MySQL 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` 有关使用谓词下推来提高联合查询（包括 MySQL）性能的文章，请参阅 *AWS 大数据博客*中的[在 Amazon Athena 中使用谓词下推改善联合查询](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)。 ## 传递查询 MySQL 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 MySQL 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 MySQL 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参阅 GitHub.com 上适用于 MySQL 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-mysql)。 # Amazon Athena Neptune 连接器 Amazon Neptune 是一项快速、可靠且完全托管式的图数据库服务，可帮助您轻松构建和运行适用于高度互连数据集的应用程序。Neptune 的核心是一个专门打造的高性能图数据库引擎，它经过优化，可存储数十亿个关系并能以毫秒级延迟进行图形查询。有关更多信息，请参阅《[Neptune 用户指南](https://docs.aws.amazon.com/neptune/latest/userguide/intro.html)》。 Amazon Athena Neptune 连接器使 Athena 能够与您的 Neptune 图数据库实例进行通信，从而使您的 Neptune 图数据可以通过 SQL 查询访问。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 如果您在账户中启用了 Lake Formation，则您在 AWS Serverless Application Repository 中部署的 Athena 联合身份 Lambda 连接器的 IAM 角色必须在 Lake Formation 中具有 AWS Glue Data Catalog 的读取权限。 ## 先决条件 使用 Neptune 连接器需要以下三个步骤。 + 设置 Neptune 集群 + 设置 AWS Glue Data Catalog + 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。有关特定于部署 Neptune 连接器的更多详细信息，请参阅 GitHub.com 上的[部署 Amazon Athena Neptune 连接器](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/neptune-connector-setup)。 ## 限制 目前，Neptune 连接器具有以下限制。 + 不支持投影列，包括主键（ID）。 ## 设置 Neptune 集群 如果您现在没有 Amazon Neptune 集群，或者您要使用的这种集群中没有属性图数据集，则您必须设置一个。 确保您在托管 Neptune 集群的 VPC 中拥有互联网网关和 NAT 网关。Neptune 连接器 Lambda 函数使用的私有子网应该具有通过此 NAT 网关连接到互联网的路由。Neptune 连接器 Lambda 函数使用 NAT 网关与 AWS Glue 通信。 有关设置新 Neptune 集群并使用示例数据集加载它的说明，请参阅 GitHub.com 上的 [Neptune 集群设置示例](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/neptune-cluster-setup)。 ## 设置 AWS Glue Data Catalog 与传统的关系数据存储不同，Neptune 图形数据库 (DB) 节点和边缘不使用集架构。每个条目均可具有不同字段和数据类型。但是，由于 Neptune 连接器从 AWS Glue Data Catalog 检索元数据，您必须使用所需架构创建一个包含多个表的 AWS Glue 数据库。在创建 AWS Glue 数据库和表之后，该连接器可以填充表（可用于来自 Athena 的查询）的列表。 ### 启用不区分大小写的列匹配 要使用正确的大小写来解析 Neptune 表中的列名称，即使列名称在 AWS Glue 全部为小写，也可以将 Neptune 连接器配置为不区分大小写的匹配。 要启用此功能，将 Neptune 连接器 Lambda 函数环境变量 `enable_caseinsensitivematch` 设置为 `true`。 ### 为大小写的表名称指定 AWS Glue glabel 表参数 由于 AWS Glue 仅支持小写表名称，因此在为 Neptune 创建 AWS Glue 表并且 Neptune 表名称包含大小写时，需要指定 `glabel` AWS Glue 表参数。 在 AWS Glue 表定义中，包含 `glabel` 参数并将其值设置为采用原始大小写的表名称。这样可以确保在 AWS Glue 与 Neptune 表进行交互时保留正确的大小写。以下示例将 `glabel` 的值设置为表名称 `Airport`。 ``` glabel = Airport ``` ![\[设置 glabel AWS Glue 表属性以保留 Neptune 表的表名称大小写\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-neptune-1.png) 有关设置 AWS Glue Data Catalog 以与 Neptune 配合使用的更多信息，请参阅 GitHub.com 上的[设置 AWS Glue 目录](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/aws-glue-sample-scripts)。 ## 性能 Athena Neptune 连接器可执行谓词下推，以减少查询扫描的数据量。但是，使用主键结果的谓词会导致查询失败。`LIMIT` 子句会减少扫描的数据量，但如果未提供谓词，则预期要使用包含 `LIMIT` 子句的 `SELECT` 查询来扫描至少 16 MB 的数据。Neptune 连接器能够灵活地应对并发造成的节流。 ## 传递查询 Neptune 连接器支持[传递查询](federated-query-passthrough.md)。可以使用此功能在属性图上运行 Gremlin 查询，也可以对 RDF 数据运行 SPARQL 查询。 要使用 Neptune 创建传递查询，请使用以下语法： ``` SELECT * FROM TABLE( system.query( DATABASE => 'database_name', COLLECTION => 'collection_name', QUERY => 'query_string' )) ``` 以下示例 Neptune 传递查询会筛选带有代码 `ATL` 的机场。双引号用于转义。 ``` SELECT * FROM TABLE( system.query( DATABASE => 'graph-database', COLLECTION => 'airport', QUERY => 'g.V().has(''airport'', ''code'', ''ATL'').valueMap()' )) ``` ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune)。 # 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)。 # Amazon Athena Oracle 连接器 适用于 Oracle 的 Amazon Athena 连接器使 Amazon Athena 能够对存储在 Oracle（在本地或在 Amazon EC2 或 Amazon RDS 上运行）中的数据运行 SQL 查询。您还可以使用该连接器查询存储在 [Oracle Exadata](https://www.oracle.com/engineered-systems/exadata/) 上的数据。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 仅支持 12.1.0.2 版本的 Oracle 数据库。 + 如果 Oracle 连接器不使用 Glue 连接，则该连接器会将数据库、表和列的名称转换为大写字母。 如果 Oracle 连接器使用 Glue 连接，则该连接器在默认情况下不会将数据库、表和列的名称转换为大写字母。要更改这种大小写行为，请根据需要将 Lambda 环境变量 `casing_mode` 更改为 `upper` 或 `lower`。 使用 Glue 连接的 Oracle 连接器不支持使用多路复用处理程序。 + 在没有定义精度和刻度的情况下使用 Oracle `NUMBER` 时，Athena 会将其视为 `BIGINT`。要获取 Athena 中必需的小数位数，请在 Lambda 环境变量中指定 `default_scale=`。 ## 术语 以下术语与 Oracle 连接器有关。 + **数据库实例** - 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Oracle 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Oracle 连接器。要执行此操作，请将 Oracle 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type ORACLE ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **is\$1fips\$1enabled** —（可选）启用 FIPS 模式时设为 true。默认值为 false。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **小写** – 所有给定的架构和表名全部小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。对于未关联 Glue 连接的连接器，这是默认设置。 + **搜索不区分大小写** – 对 Oracle 中的架构和表名执行不区分大小写的搜索。如果查询包含的架构或表名与连接器的默认大小写模式不一致，请使用此值。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Oracle 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Oracle 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 **Lambda 环境属性** + **默认** — 用于连接至 Oracle 数据库实例的 JDBC 连接字符串。例如，`oracle://${jdbc_connection_string}` + **catalog\$1connection\$1string** — 供多路复用处理程序使用（使用 Glue 连接时不支持）。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myoraclecatalog，则环境变量名称是 myoraclecatalog\$1connection\$1string。 + **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)时。 + **is\$1fips\$1enabled** —（可选）启用 FIPS 模式时设为 true。默认值为 false。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **小写** – 所有给定的架构和表名全部小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。对于未关联 Glue 连接的连接器，这是默认设置。 + **搜索不区分大小写** – 对 Oracle 中的架构和表名执行不区分大小写的搜索。如果查询包含的架构或表名与连接器的默认大小写模式不一致，请使用此值。 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` oracle://${jdbc_connection_string} ``` **注意** 如果您的密码包含特殊字符（例如，`some.password`），则在将密码传递给连接字符串时将密码包含在双引号中（例如，`"some.password"`）。否则，可能会导致指定的 Oracle URL 无效错误。 #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Oracle 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | OracleCompositeHandler | | 元数据处理程序 | OracleMetadataHandler | | 记录处理程序 | OracleRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | | IsFIPSEnabled | 可选。在启用 FIPS 模式时设置为 true。默认值为 false。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 该连接器支持基于 SSL 的与 Amazon RDS 实例的连接。支持仅限于传输层安全性协议（TLS）以及客户端对服务器的身份验证。在 Amazon RDS 中不支持相互身份验证。下表中的第二行显示了使用 SSL 的语法。 以下示例属性适用于 Lambda 函数支持的单个 Oracle 实例。 **** | 属性 | 值 | | --- | --- | | default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@//hostname:port/servicename | | | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS) (HOST=)(PORT=))(CONNECT\$1DATA=(SID=))(SECURITY=(SSL\$1SERVER\$1CERT\$1DN=))) | #### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **注意** 如果您的密码包含特殊字符（例如，`some.password`），则在将密码存储在 Secrets Manager 中时将密码包含在双引号中（例如，`"some.password"`）。否则，可能会导致指定的 Oracle URL 无效错误。 **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/Oracle}`。 ``` oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` oracle://jdbc:oracle:thin:username/password@//hostname:port/servicename ``` 目前，Oracle 连接器可以识别 `UID` 和 `PWD` JDBC 属性。 #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | OracleMuxCompositeHandler | | 元数据处理程序 | OracleMuxMetadataHandler | | 记录处理程序 | OracleMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myoraclecatalog，则环境变量名称是 myoraclecatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。当目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Oracle MUX Lambda 函数：`oracle1`（默认值）和 `oracle2`。 **** | 属性 | 值 | | --- | --- | | default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename | | oracle\$1catalog1\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename | | oracle\$1catalog2\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle2\$1@//oracle2.hostname:port/servicename | ## 数据类型支持 下表显示了适用于 JDBC、Oracle 和 Arrow 的相应数据类型。 **** | JDBC | Oracle | Arrow | | --- | --- | --- | | 布尔值 | 布尔值 | Bit | | 整数 | 不适用 | Tiny | | 短型 | smallint | Smallint | | 整数 | 整数 | Int | | 长整型 | bigint | Bigint | | 浮点数 | float4 | Float4 | | 双精度 | float8 | Float8 | | 日期 | date | DateDay | | Timestamp | timestamp | DateMilli | | 字符串 | 文本 | Varchar | | 字节 | bytes | Varbinary | | BigDecimal | numeric(p,s) | 十进制 | | ARRAY | 不适用（见注释） | 列表 | ## 分区和拆分 分区用于确定如何为该连接器生成拆分。Athena 将构建一个 `varchar` 类型的合成列，它将展示表的分区方案，以帮助该连接器生成拆分。该连接器不会修改实际的表定义。 ## 性能 Oracle 支持本机分区。Athena Oracle 连接器可从这些分区并行检索数据。如果您想查询具有统一分区分布的超大型数据集，强烈建议使用本机分区。选择列的子集可以显著减少查询运行时及扫描的数据。Oracle 连接器能够灵活地应对并发造成的节流。但是，查询运行时往往很长。 Athena Oracle 连接器可执行谓词下推，以减少查询扫描的数据量。简单谓词和复杂表达式将下推到连接器，以减少扫描的数据量并缩短查询执行的运行时间。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Oracle 连接器可以组合这些表达式并将其直接推送到 Oracle，以增强功能并减少扫描的数据量。 以下 Athena Oracle 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 传递查询 Oracle 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Oracle 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Oracle 中的数据来源。该查询会选择 `customer` 表中的所有列。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参阅 GitHub.com 上适用于 Oracle 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-oracle)。 # Amazon Athena PostgreSQL 连接器 Amazon Athena PostgreSQL 连接器使 Athena 可以访问 PostgreSQL 数据库。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 与 PostgreSQL 一样，出于长度和比较的目的，Athena 将 PostgreSQL `CHAR` 类型中的尾随空格视为在语义上无关紧要。请注意，这仅适用于 `CHAR`，但不适用于 `VARCHAR` 类型。Athena 会忽略 `CHAR` 类型的尾随空格，但将其视为对 `VARCHAR` 类型很重要。 + 使用 [citext](https://www.postgresql.org/docs/current/citext.html) 不区分大小写的字符串数据类型时，PostgreSQL 会使用与 Athena 不同的不区分大小写的数据比较。这种差异在 SQL `JOIN` 操作过程中会产生数据差异。要解决此问题，请使用 PostgreSQL 连接器传递查询功能。有关更多信息，请参阅本文档后面的[传递查询](#connectors-postgres-passthrough-queries)部分。 ## 术语 以下术语和概念与 PostgreSQL 连接器有关。 + **数据库实例** - 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 PostgreSQL 连接器。 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 PostgreSQL 连接器。 要执行此操作，请将 PostgreSQL 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type POSTGRESQL ``` **Lambda 环境属性** **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 PostgreSQL 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 PostgreSQL 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` postgres://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | PostGreSqlMuxCompositeHandler | | 元数据处理程序 | PostGreSqlMuxMetadataHandler | | 记录处理程序 | PostGreSqlMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mypostgrescatalog，则环境变量名称是 mypostgrescatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。当目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 PostGreSql MUX Lambda 函数：`postgres1`（默认）和 `postgres2`。 **** | 属性 | 值 | | --- | --- | | default | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 | | postgres\$1catalog1\$1connection\$1string | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 | | postgres\$1catalog2\$1connection\$1string | postgres://jdbc:postgresql://postgres2.host:5432/default?user=sample&password=sample | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/PostGres1}`。 ``` postgres://jdbc:postgresql://postgres1.host:5432/default?...&${Test/RDS/PostGres1}&... ``` 该连接器使用该密钥名称来检索秘密，并提供用户名和密码，如以下示例所示。 ``` postgres://jdbc:postgresql://postgres1.host:5432/default?...&user=sample2&password=sample2&... ``` 目前，PostgreSQL 连接器可以识别 `user` 和 `password` JDBC 属性。 ##### 启用 SSL 要在 PostgreSQL 连接中支持 SSL，请在连接字符串中附加以下内容： ``` &sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory ``` **示例** 以下示例连接字符串不使用 SSL。 ``` postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword ``` 要启用 SSL，如下所示修改字符串。 ``` postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory ``` #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 PostgreSQL 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | PostGreSqlCompositeHandler | | 元数据处理程序 | PostGreSqlMetadataHandler | | 记录处理程序 | PostGreSqlRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 PostgreSQL 实例。 **** | 属性 | 值 | | --- | --- | | default | postgres://jdbc:postgresql://postgres1.host:5432/default?secret=\$1\$1Test/RDS/PostgreSQL1\$1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC、PostGreSQL 和 Arrow 的相应数据类型。 **** | JDBC | PostGreSQL | Arrow | | --- | --- | --- | | 布尔值 | 布尔值 | Bit | | 整数 | 不适用 | Tiny | | 短型 | smallint | Smallint | | 整数 | 整数 | Int | | 长整型 | bigint | Bigint | | 浮点数 | float4 | Float4 | | 双精度 | float8 | Float8 | | 日期 | date | DateDay | | Timestamp | timestamp | DateMilli | | 字符串 | 文本 | Varchar | | 字节 | bytes | Varbinary | | BigDecimal | numeric(p,s) | 十进制 | | ARRAY | 不适用（见注释） | 列表 | **注意** PostgreSQL 连接器支持该 `ARRAY` 类型，但具有以下限制：不支持多维数组（`[][]` 或嵌套数组）。包含不受支持的 `ARRAY` 数据类型的列将被转换为字符串元素数组 (`array`)。 ## 分区和拆分 分区用于确定如何为该连接器生成拆分。Athena 将构建一个 `varchar` 类型的合成列，它将展示表的分区方案，以帮助该连接器生成拆分。该连接器不会修改实际的表定义。 ## 性能 PostgreSQL 支持本机分区。Athena PostgreSQL 连接器可从这些分区并行检索数据。如果您想查询具有统一分区分布的超大型数据集，强烈建议使用本机分区。 Athena PostgreSQL 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。但是，选择一部分列有时会导致查询执行的运行时间延长。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena PostgreSQL 连接器可以组合这些表达式并将其直接推送到 PostgreSQL，以增强功能并减少扫描的数据量。 以下 Athena PostgreSQL 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 传递查询 PostgreSQL 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 PostgreSQL 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 PostgreSQL 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参阅 GitHub.com 上适用于 PostgreSQL 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-postgresql/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-postgresql)。 # Amazon Athena Redis OSS 连接器 Amazon Redis OSS 连接器使 Amazon Athena 可以与 Redis OSS 实例通信，以便您可以使用 SQL 查询 Redis OSS 数据。您可以使用 AWS Glue Data Catalog 将 Redis OSS 键值对映射到虚拟表。 与传统的关系数据存储不同，Redis OSS 没有表或列的概念。相反，Redis OSS 提供了键值访问模式，其中，键本质上是一个 `string`，值是 `string`、`z-set` 或 `hmap`。 您可以使用 AWS Glue Data Catalog 创建架构和配置虚拟表。特殊的表属性告诉 Athena Redis OSS 连接器如何将 Redis OSS 键和值映射到表中。有关更多信息，请参阅本文后面的[在 AWS Glue 中设置数据库和表](#connectors-redis-setting-up-databases-and-tables-in-glue)。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 如果您在账户中启用了 Lake Formation，则您在 AWS Serverless Application Repository 中部署的 Athena 联合身份 Lambda 连接器的 IAM 角色必须在 Lake Formation 中具有 AWS Glue Data Catalog 的读取权限。 Amazon Athena Redis OSS 连接器支持 Amazon MemoryDB 和 Amazon ElastiCache（Redis OSS）。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 + 使用此连接器前，请先设置 VPC 和安全组。有关更多信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 ## 参数 使用本节中的参数来配置 Redis 连接器。 + **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)时。 + **glue\$1catalog** –（可选）使用此选项指定[跨账户 AWS Glue 目录](data-sources-glue-cross-account.md)。默认情况下，该连接器将尝试从其自己的 AWS Glue 账户中获取元数据。 ## 在 AWS Glue 中设置数据库和表 要将 AWS Glue 表与 Redis OSS 配合使用，可以在表上设置以下表属性：`redis-endpoint`、`redis-value-type`，以及 `redis-keys-zset` 或 `redis-key-prefix`。 此外，包含 Redis OSS 表的任何 AWS Glue 数据库必须在数据库的 URI 属性中有 `redis-db-flag`。要设置 `redis-db-flag` URI 属性，请使用 AWS Glue 控制台编辑数据库。 以下列表描述了表属性。 + **redis-endpoint**：（必选）包含此表数据的 Redis OSS 服务器的*主机名*`:`*端口*`:`*密码*（例如 `athena-federation-demo.cache.amazonaws.com:6379`)。或者，您可以通过将 \$1\$1*Secret\$1Name*\$1 用作表属性值，来将端点或部分端点存储在 AWS Secrets Manager。 **注意** 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 + **redis-keys-zset** —（必选，如果未使用 `redis-key-prefix`）以逗号分隔的密钥列表，值为 [zset](https://redis.com/ebook/part-2-core-concepts/chapter-3-commands-in-redis/3-5-sorted-sets/)（例如 `active-orders,pending-orders`)。zset 中的每个值都被视为密钥（表的一部分）。必须设置 `redis-keys-zset` 属性或 `redis-key-prefix` 属性。 + **redis-key-prefix** —（必选，如果未使用 `redis-keys-zset`）以逗号分隔的键前缀列表，用于扫描表中的值（例如 `accounts-*,acct-`)。必须设置 `redis-key-prefix` 属性或 `redis-keys-zset` 属性。 + **redis-value-type** —（必选）定义由 `redis-key-prefix` 或 `redis-keys-zset` 定义的键的值如何映射到您的表。文本映射到单个列。zset 也映射到单个列，但每个键可以存储许多行。哈希使每个键成为包含多个列的行（例如，哈希、文本或 zset）。 + **redis-ssl-flag** —（可选）`True` 时，创建一个使用 SSL/TLS 的 Redis 连接。默认值为 `False`。 + **redis-cluster-flag** —（可选）`True` 时，启用对集群 Redis 实例的支持。默认值为 `False`。 + **redis-db-number** —（可选）仅适用于独立的非集群实例。） 将此数字（例如 1、2 或 3）设置为从非默认 Redis 数据库读取。默认为 Redis 逻辑数据库 0。此数字不是指 Athena 或 AWS Glue 中的数据库，而是指 Redis 逻辑数据库。有关更多信息，请参阅 Redis 文档中的 [SELECT 索引](https://redis.io/commands/select)。 ## 数据类型 Redis OSS 连接器支持以下数据类型。不支持 Redis OSS 流。 + [String](https://redis.com/ebook/part-1-getting-started/chapter-1-getting-to-know-redis/1-2-what-redis-data-structures-look-like/1-2-1-strings-in-redis/) + [哈希](https://redis.com/ebook/part-1-getting-started/chapter-1-getting-to-know-redis/1-2-what-redis-data-structures-look-like/1-2-4-hashes-in-redis/) + 排序集（[ZSet](https://redis.com/ebook/part-2-core-concepts/chapter-3-commands-in-redis/3-5-sorted-sets/)） 所有 Redis OSS 值均作为 `string` 数据类型检索。然后，根据您的表在 AWS Glue Data Catalog 中的定义方式，将这些值转换为以下 Apache Arrow 数据类型之一。 **** | AWS Glue 数据类型 | Apache Arrow 数据类型 | | --- | --- | | int | INT | | 字符串 | VARCHAR | | bigint | BIGINT | | double | FLOAT8 | | 浮点数 | FLOAT4 | | smallint | SMALLINT | | tinyint | TINYINT | | 布尔值 | BIT | | binary | VARBINARY | ## 所需权限 有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-redis.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-redis/athena-redis.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **AWS Glue Data Catalog** — Redis 连接器需要针对 AWS Glue Data Catalog 的只读访问权限，以获取架构信息。 + **CloudWatch Logs** – 该连接器需要针对 CloudWatch Logs 的访问权限，以存储日志。 + **AWS Secrets Manager读取访问权限** — 如果您选择在 Secrets Manager 中存储 Redis 端点详细信息，则必须授予连接器访问这些密钥的权限。 + **VPC 访问** — 连接器需要能够连接和分离您 VPC 的接口，以便连接到 VPC 并与您的 Redis 实例通信。 ## 性能 Athena Redis OSS 连接器尝试根据您定义的表类型（例如，zset 密钥或前缀密钥）针对您的 Redis OSS 实例并行查询。 Athena Redis 连接器可执行谓词下推，以减少查询扫描的数据量。但是，包含谓词的主键结果查询会超时失败。`LIMIT` 子句会减少扫描的数据量，但如果未提供谓词，则预期要使用包含 `LIMIT` 子句的 `SELECT` 查询来扫描至少 16 MB 的数据。Redis 连接器能够灵活地应对并发造成的节流。 ## 传递查询 Redis 连接器支持[传递查询](federated-query-passthrough.md)。可以使用此功能在 Redis 数据库上运行使用 Lua 脚本的查询。 要使用 Redis 创建传递查询，请使用以下语法： ``` SELECT * FROM TABLE( system.script( script => 'return redis.[call|pcall](query_script)', keys => '[key_pattern]', argv => '[script_arguments]' )) ``` 以下示例运行 Lua 脚本来获取键 `l:a` 处的值。 ``` SELECT * FROM TABLE( system.script( script => 'return redis.call("GET", KEYS[1])', keys => '[l:a]', argv => '[]' )) ``` ## 许可证信息 Amazon Athena Redis 连接器项目已根据 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)获得许可。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redis)。 # Amazon Athena Redshift 连接器 Amazon Athena Redshift 连接器使 Amazon Athena 能够访问您的 Amazon Redshift 和 Amazon Redshift Serverless 数据库，包括 Redshift Serverless 视图。您可以使用本页所述的 JDBC 连接字符串配置设置连接到任一服务。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 由于 Redshift 不支持外部分区，因此每次都会检索查询指定的所有数据。 + 与 Redshift 一样，出于长度和比较的目的，Athena 将 Redshift `CHAR` 类型中的尾随空格视为在语义上无关紧要。请注意，这仅适用于 `CHAR`，但不适用于 `VARCHAR` 类型。Athena 会忽略 `CHAR` 类型的尾随空格，但将其视为对 `VARCHAR` 类型很重要。 ## 术语 以下术语与 Redshift 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Redshift 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Redshift 连接器。要执行此操作，请将 Amazon Redshift 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type REDSHIFT ``` **Lambda 环境属性** **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Redshift 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Redshift 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 **Lambda 环境属性** + **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 检索补充元数据。 + **glue\$1catalog** –（可选）使用此选项指定[跨账户 AWS Glue 目录](data-sources-glue-cross-account.md)。默认情况下，该连接器将尝试从其自己的 AWS Glue 账户中获取元数据。 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` redshift://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | RedshiftMuxCompositeHandler | | 元数据处理程序 | RedshiftMuxMetadataHandler | | 记录处理程序 | RedshiftMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myredshiftcatalog，则环境变量名称是 myredshiftcatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Redshift MUX Lambda 函数：`redshift1`（默认）和 `redshift2`。 **** | 属性 | 值 | | --- | --- | | default | redshift://jdbc:redshift://redshift1.host:5439/dev?user=sample2&password=sample2 | | redshift\$1catalog1\$1connection\$1string | redshift://jdbc:redshift://redshift1.host:3306/default?\$1\$1Test/RDS/Redshift1\$1 | | redshift\$1catalog2\$1connection\$1string | redshift://jdbc:redshift://redshift2.host:3333/default?user=sample2&password=sample2 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 \$1\$1Test/RDS/`Redshift1`\$1。 ``` redshift://jdbc:redshift://redshift1.host:3306/default?...&${Test/RDS/Redshift1}&... ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` redshift://jdbc:redshift://redshift1.host:3306/default?...&user=sample2&password=sample2&... ``` 目前，Redshift 连接器可以识别 `user` 和 `password` JDBC 属性。 ## 数据类型支持 下表显示了适用于 JDBC 和 Apache Arrow 的相应数据类型。 **** | JDBC | Arrow | | --- | --- | | 布尔值 | Bit | | 整数 | Tiny | | 短型 | Smallint | | 整数 | Int | | 长整型 | Bigint | | 浮点数 | Float4 | | 双精度 | Float8 | | 日期 | DateDay | | Timestamp | DateMilli | | 字符串 | Varchar | | 字节 | Varbinary | | BigDecimal | 十进制 | | ARRAY | 列表 | ## 分区和拆分 Redshift 不支持外部分区。有关性能相关问题的信息，请参阅 [性能](#connectors-redshift-performance)。 ## 性能 Athena Redshift 连接器执行谓词下推，以减少查询扫描的数据。`LIMIT` 子句、`ORDER BY` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。但是，选择一部分列有时会导致查询执行的运行时间延长。当您同时运行多个查询时，Amazon Redshift 特别容易受到查询执行速度减慢的影响。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### 前 N 个查询 前 `N` 个查询用于指定结果集的顺序以及返回的行数限值。您可以使用此类查询确定数据集的前 `N` 个最大值或前 `N` 个最小值。前 `N` 个查询下推时，连接器仅向 Athena 返回 `N` 个已排序行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Redshift 连接器可以组合这些表达式并将其直接推送到 Redshift，以增强功能并减少扫描的数据量。 以下 Athena Redshift 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') ORDER BY col_a DESC LIMIT 10; ``` 有关使用谓词下推来提高联合查询（包括 Amazon Redshift）性能的文章，请参阅 *AWS 大数据博客*中的[在 Amazon Athena 中使用谓词下推改善联合查询](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)。 ## 传递查询 Redshift 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Redshift 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Redshift 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 Redshift 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-redshift/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redshift)。 # Amazon Athena SAP HANA 连接器 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 在 SAP HANA 中，当对象名称存储在 SAP HANA 数据库中时，它们会转换为大写形式。但是，由于引号中的名称区分大小写，因此两个表能分别以小写和大写形式具有相同的名称（例如 `EMPLOYEE` 和 `employee`)。 在 Athena 联合查询中，架构表名称以小写形式提供给 Lambda 函数。要解决此问题，您可以提供 `@schemaCase` 查询提示，用于从名称区分大小写的表中检索数据。以下是两个带有查询提示的示例查询。 ``` SELECT * FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=upper" ``` ``` SELECT * FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=lower" ``` ## 术语 以下术语与 SAP HANA 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 SAP HANA 连接器。 **注意** 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 连接对象来配置 SAP HANA 连接器。要执行此操作，请将 SAP HANA 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type SAPHANA ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 SAP HANA 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 SAP HANA 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` saphana://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | SaphanaMuxCompositeHandler | | 元数据处理程序 | SaphanaMuxMetadataHandler | | 记录处理程序 | SaphanaMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mysaphanacatalog，则环境变量名称是 mysaphanacatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Saphana MUX Lambda 函数：`saphana1`（默认）和 `saphana2`。 **** | 属性 | 值 | | --- | --- | | default | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 | | saphana\$1catalog1\$1connection\$1string | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 | | saphana\$1catalog2\$1connection\$1string | saphana://jdbc:sap://saphana2.host:port/?user=sample2&password=sample2 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/Saphana1}`。 ``` saphana://jdbc:sap://saphana1.host:port/?${Test/RDS/Saphana1}&... ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` saphana://jdbc:sap://saphana1.host:port/?user=sample2&password=sample2&... ``` 目前，SAP HANA 连接器可以识别 `user` 和 `password` JDBC 属性。 #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 SAP HANA 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | SaphanaCompositeHandler | | 元数据处理程序 | SaphanaMetadataHandler | | 记录处理程序 | SaphanaRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 SAP HANA 实例。 **** | 属性 | 值 | | --- | --- | | default | saphana://jdbc:sap://saphana1.host:port/?secret=Test/RDS/Saphana1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC 和 Apache Arrow 的相应数据类型。 **** | JDBC | Arrow | | --- | --- | | 布尔值 | Bit | | 整数 | Tiny | | 短型 | Smallint | | 整数 | Int | | 长整型 | Bigint | | 浮点数 | Float4 | | 双精度 | Float8 | | 日期 | DateDay | | Timestamp | DateMilli | | 字符串 | Varchar | | 字节 | Varbinary | | BigDecimal | 十进制 | | ARRAY | 列表 | ## 数据类型转换 除了 JDBC 到 Arrow 的转换外，连接器还执行某些其他转换，以使 SAP HANA 源和 Athena 数据类型兼容。这些转换有助于确保成功执行查询。下表显示了这些转换。 **** | 源数据类型 (SAP HANA) | 转换后的数据类型 (Athena) | | --- | --- | | DECIMAL | BIGINT | | INTEGER | INT | | DATE | DATEDAY | | TIMESTAMP | DATEMILLI | 所有其他不支持的数据类型都转换为 `VARCHAR`。 ## 分区和拆分 分区由类型为 `Integer` 的单个分区列表示。该列包含在 SAP HANA 表上定义的分区的分区名称。对于没有分区名称的表，返回 \$1，相当于单个分区。分区等同于拆分。 **** | 名称 | Type | 说明 | | --- | --- | --- | | PART\$1ID | 整数 | SAP HANA 中的命名分区。 | ## 性能 SAP HANA 支持本机分区。Athena SAP HANA 连接器可从这些分区并行检索数据。如果您想查询具有统一分区分布的超大型数据集，强烈建议使用本机分区。选择列的子集可以显著减少查询运行时及扫描的数据。由于并发，连接器显示出严重的节流，有时还会出现查询失败。 Athena SAP HANA 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena SAP HANA 连接器可以组合这些表达式并将其直接推送到 SAP HANA，以增强功能并减少扫描的数据量。 以下 Athena SAP HANA 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` ## 传递查询 SAP HANA 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 SAP HANA 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 SAP HANA 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 SAP HANA 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-saphana)。 # Amazon Athena Snowflake 连接器 适用于 [Snowflake](https://www.snowflake.com/) 的 Amazon Athena 连接器使 Amazon Athena 能够使用 JDBC 对存储在 Snowflake SQL 数据库 中的数据或 RDS 实例运行 SQL 查询。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 可以使用 Athena 控制台或 `CreateDataCatalog` API 操作将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 只有传统连接支持多路复用器设置。 + 目前，不支持单个拆分的 Snowflake 视图。 + 在 Snowflake 中，对象名称区分大小写。Athena 在 DDL 和 DML 查询中接受混合大小写，但在执行查询时对象名称默认为[小写](https://docs.aws.amazon.com/athena/latest/ug/tables-databases-columns-names.html#table-names-and-table-column-names-in-ate-must-be-lowercase)。使用 Glue Catalog/Lake Formation 时，Snowflake 连接器仅支持小写。使用 Athena Catalog 时，客户可以使用 `casing_mode` Lambda 环境变量来控制大小写行为，该变量的可能值在[参数](#connectors-snowflake-parameters)部分中列出（例如，`key=casing_mode, value = CASE_INSENSITIVE_SEARCH`）。 ## 术语 以下术语与 Snowflake 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Snowflake 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Snowflake 连接器。要执行此操作，请将 Snowflake 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type SNOWFLAKE ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **NONE**：不更改给定架构和表名的大小写（如同在 Snowflake 上一样运行查询）。当未指定 **casing\$1mode** 时，此项为默认值。 + **UPPER**：查询中所有给定的架构和表名均转换为大写，然后再对 Snowflake 运行该查询。 + **LOWER**：查询中所有给定的架构和表名均转换为小写，然后再对 Snowflake 运行该查询。 + **CASE\$1INSENSITIVE\$1SEARCH**：对 Snowflake 中的架构和表名执行不区分大小写的搜索。例如，当您有类似 `SELECT * FROM EMPLOYEE` 的查询并且 Snowflake 包含一个名为 `Employee` 的表时，您可以使用此模式。不过，如果存在名称冲突，例如 Snowflake 中有一个表名为 `EMPLOYEE` 而另一个表名为 `Employee`，则查询将失败。 **注意** 使用 Glue 连接创建的 Snowflake 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Snowflake 连接器仅支持 `ConnectionSchemaVersion` 2。 **存储凭证** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。有关更多信息，请参阅 [通过 Snowflake 进行身份验证](connectors-snowflake-authentication.md)。 ### 旧连接 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 **Lambda 环境属性** + **默认** — 用于连接至 Snowflake 数据库实例的 JDBC 连接字符串。例如，`snowflake://${jdbc_connection_string}` + **catalog\$1connection\$1string** — 供多路复用处理程序使用（使用 Glue 连接时不支持）。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mysnowflakecatalog，则环境变量名称是 mysnowflakecatalog\$1connection\$1string。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **NONE**：不更改给定架构和表名的大小写（如同在 Snowflake 上一样运行查询）。当未指定 **casing\$1mode** 时，此项为默认值。 + **UPPER**：查询中所有给定的架构和表名均转换为大写，然后再对 Snowflake 运行该查询。 + **LOWER**：查询中所有给定的架构和表名均转换为小写，然后再对 Snowflake 运行该查询。 + **CASE\$1INSENSITIVE\$1SEARCH**：对 Snowflake 中的架构和表名执行不区分大小写的搜索。例如，当您有类似 `SELECT * FROM EMPLOYEE` 的查询并且 Snowflake 包含一个名为 `Employee` 的表时，您可以使用此模式。不过，如果存在名称冲突，例如 Snowflake 中有一个表名为 `EMPLOYEE` 而另一个表名为 `Employee`，则查询将失败。 + **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)时。 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` snowflake://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | SnowflakeMuxCompositeHandler | | 元数据处理程序 | SnowflakeMuxMetadataHandler | | 记录处理程序 | SnowflakeMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mysnowflakecatalog，则环境变量名称是 mysnowflakecatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Snowflake MUX Lambda 函数：`snowflake1`（默认）和 `snowflake2`。 **** | 属性 | 值 | | --- | --- | | default | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1&\$1\$1Test/RDS/Snowflake1\$1 | | snowflake\$1catalog1\$1connection\$1string | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1\$1\$1Test/RDS/Snowflake1\$1 | | snowflake\$1catalog2\$1connection\$1string | snowflake://jdbc:snowflake://snowflake2.host:port/?warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/Snowflake1}`。 ``` snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}&... ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` snowflake://jdbc:snowflake://snowflake1.host:port/warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2&... ``` 目前，Snowflake 可以识别 `user` 和 `password` JDBC 属性。还接受以下格式的用户名和密码：*用户名*`/`*密码*（不含密钥 `user` 或 `password`）。 #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Snowflake 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | SnowflakeCompositeHandler | | 元数据处理程序 | SnowflakeMetadataHandler | | 记录处理程序 | SnowflakeRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 Snowflake 实例。 **** | 属性 | 值 | | --- | --- | | default | snowflake://jdbc:snowflake://snowflake1.host:port/?secret=Test/RDS/Snowflake1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC 和 Apache Arrow 的相应数据类型。 **** | JDBC | Arrow | | --- | --- | | 布尔值 | Bit | | 整数 | Tiny | | 短型 | Smallint | | 整数 | Int | | 长整型 | Bigint | | 浮点数 | Float4 | | 双精度 | Float8 | | 日期 | DateDay | | Timestamp | DateMilli | | 字符串 | Varchar | | 字节 | Varbinary | | BigDecimal | 十进制 | | ARRAY | 列表 | ## 数据类型转换 除了 JDBC 到 Arrow 的转换外，连接器还执行某些其他转换，以使 Snowflake 源和 Athena 数据类型兼容。这些转换有助于确保成功执行查询。下表显示了这些转换。 **** | 源数据类型 (Snowflake) | 转换后的数据类型 (Athena) | | --- | --- | | TIMESTAMP | TIMESTAMPMILLI | | DATE | TIMESTAMPMILLI | | INTEGER | INT | | DECIMAL | BIGINT | | TIMESTAMP\$1NTZ | TIMESTAMPMILLI | 所有其他不支持的数据类型都转换为 `VARCHAR`。 ## 分区和拆分 分区用于确定如何为该连接器生成拆分。Athena 将构建一个 `varchar` 类型的合成列，它将展示表的分区方案，以帮助该连接器生成拆分。该连接器不会修改实际的表定义。 若要创建此合成列和分区，Athena 需要定义主键。但是，由于 Snowflake 不强制执行主键约束，您必须自己强制执行唯一性。不这样做会导致 Athena 默认为单次拆分。 ## 性能 为了获得最佳性能，请尽可能在查询中使用筛选条件。此外，我们强烈建议使用本机分区来检索具有均匀分区分布的大型数据集。选择列的子集可以显著减少查询运行时及扫描的数据。Snowflake 连接器能够灵活地应对并发造成的节流。 Athena Snowflake 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。 ### LIMIT 子句 `LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Snowflake 连接器可以组合这些表达式并将其直接推送到 Snowflake，以增强功能并减少扫描的数据量。 以下 Athena Snowflake 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` # 通过 Snowflake 进行身份验证 您可以将 Amazon Athena Snowflake 连接器配置为使用密钥对身份验证或 OAuth 身份验证方法，来连接 Snowflake 数据仓库。这两种方法都提供对 Snowflake 的安全访问，并且无需在连接字符串中存储密码。 + **密钥对身份验证**：此方法使用 RSA 公有或私有密钥对通过 Snowflake 进行身份验证。私有密钥会对身份验证请求进行数字签名，而相应的公有密钥则会在 Snowflake 中注册以供验证。此方法消除了存储密码的需要。 + **OAuth 身份验证**：此方法使用授权令牌和刷新令牌通过 Snowflake 进行身份验证。它支持自动令牌刷新，因此适用于长时间运行的应用程序。 有关更多信息，请参阅 Snowfla ke 用户指南中的 [Key-pair authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth) 和 [OAuth authentication](https://docs.snowflake.com/en/user-guide/oauth-custom)。 ## 先决条件 在开始之前，请满足以下先决条件： + 具有管理权限的 Snowflake 账户访问权限。 + 专门用于 Athena 连接器的 Snowflake 用户账户。 + 用于密钥对身份验证的 OpenSSL 或等效密钥生成工具。 + AWS Secrets Manager 访问权限，用于创建和管理密钥。 + 用于完成 OAuth 身份验证的 OAuth 流程的 Web 浏览器。 ## 配置密钥对身份验证 此过程包括生成 RSA 密钥对、使用公有密钥配置您的 Snowflake 账户，以及将私有密钥安全地存储在 AWS Secrets Manager 中。以下步骤将指导您创建加密密钥、设置必要的 Snowflake 权限以及配置 AWS 凭证以实现流畅的身份验证。 1. **生成 RSA 密钥对** 使用 OpenSSL 生成私有和公有密钥对。 + 要生成未加密的版本，请在本地命令行应用程序中使用以下命令。 ``` openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt ``` + 要生成加密版本，请使用以下命令，该命令省略了 `-nocrypt`。 ``` openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8 ``` + 使用私有密钥生成公有密钥。 ``` openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub # Set appropriate permissions (Unix/Linux) chmod 600 rsa_key.p8 chmod 644 rsa_key.pub ``` **注意** 请勿与他人共享您的私有密钥。只有需要通过 Snowflake 进行身份验证的应用程序才能访问私有密钥。 1. **为 Snowflake 提取不带分隔符的公有密钥内容** ``` # Extract public key content (remove BEGIN/END lines and newlines) cat rsa_key.pub | grep -v "BEGIN\|END" | tr -d '\n' ``` 请记下这些信息，因为需要在下一步中用到。 1. **配置 Snowflake 用户** 按照以下步骤配置 Snowflake 用户： 1. 为 Athena 连接器创建专属用户（如果还没有执行此操作）。 ``` -- Create user for Athena connector CREATE USER athena_connector_user; -- Grant necessary privileges GRANT USAGE ON WAREHOUSE your_warehouse TO ROLE athena_connector_role; GRANT USAGE ON DATABASE your_database TO ROLE athena_connector_role; GRANT SELECT ON ALL TABLES IN DATABASE your_database TO ROLE athena_connector_role; ``` 1. 授予身份验证权限。要向用户分配公有密钥，您必须具有以下角色或权限之一： + 用户的 `MODIFY PROGRAMMATIC AUTHENTICATION METHODS` 或 `OWNERSHIP` 权限。 + `SECURITYADMIN` 角色或更高层级角色。 使用以下命令授予必要权限以分配公有密钥。 ``` GRANT MODIFY PROGRAMMATIC AUTHENTICATION METHODS ON USER athena_connector_user TO ROLE your_admin_role; ``` 1. 使用以下命令将公有密钥分配给 Snowflake 用户。 ``` ALTER USER athena_connector_user SET RSA_PUBLIC_KEY='RSAkey'; ``` 使用以下命令验证公有密钥是否已成功分配给该用户。 ``` DESC USER athena_connector_user; ``` 1. **将私有密钥存储在 AWS Secrets Manager 中** 1. 将私有密钥转换为连接器要求的格式。 ``` # Read private key content cat rsa_key.p8 ``` 1. 在 AWS Secrets Manager 中，创建一个使用以下结构的密钥。 ``` { "sfUser": "your_snowflake_user", "pem_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----", "pem_private_key_passphrase": "passphrase_in_case_of_encrypted_private_key(optional)" } ``` **注意** 页眉和页脚为选填。 私有密钥必须使用 `\n` 分隔。 ## 配置 OAuth 身份验证 此身份验证方法具备自动刷新凭证的功能，可以实现对 Snowflake 进行基于令牌的安全访问。配置过程包括在 Snowflake 中创建安全集成、检索 OAuth 客户端凭证、完成授权流程以获取访问代码，以及将 OAuth 凭据存储在 AWS Secrets Manager 中以供连接器使用。 1. **在 Snowflake 创建安全集成** 在 Snowflake 中执行以下 SQL 命令创建 Snowflake OAuth 安全集成。 ``` CREATE SECURITY INTEGRATION my_snowflake_oauth_integration_a TYPE = OAUTH ENABLED = TRUE OAUTH_CLIENT = CUSTOM OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' OAUTH_REDIRECT_URI = 'https://localhost:8080/oauth/callback' OAUTH_ISSUE_REFRESH_TOKENS = TRUE OAUTH_REFRESH_TOKEN_VALIDITY = 7776000; ``` **配置参数** + `TYPE = OAUTH`：指定 OAuth 身份验证类型。 + `ENABLED = TRUE`：启用安全集成。 + `OAUTH_CLIENT = CUSTOM`：使用自定义 OAuth 客户端配置。 + `OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'`：为安全应用程序设置客户端类型。 + `OAUTH_REDIRECT_URI`：OAuth 流程的回调 URL。它可以是用于测试的本地主机。 + `OAUTH_ISSUE_REFRESH_TOKENS = TRUE`：启用刷新令牌生成。 + `OAUTH_REFRESH_TOKEN_VALIDITY = 7776000`：设置刷新令牌的有效期（以秒为单位，最长 90 天）。 1. **检索 OAuth 客户端密钥** 1. 运行以下 SQL 命令来获取客户端凭证。 ``` DESC SECURITY INTEGRATION 'MY_SNOWFLAKE_OAUTH_INTEGRATION_A'; ``` 1. 检索 OAuth 客户端密钥。 ``` SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('MY_SNOWFLAKE_OAUTH_INTEGRATION_A'); ``` **响应示例** ``` { "OAUTH_CLIENT_SECRET_2": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "OAUTH_CLIENT_SECRET": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY, "OAUTH_CLIENT_ID": "AIDACKCEVSQ6C2EXAMPLE" } ``` **注意** 请妥善保管这些凭证，不要与他人共享。这些凭证将用于配置 OAuth 客户端。 1. **授权用户并检索授权码** 1. 在浏览器中打开以下 URL。 ``` https://.snowflakecomputing.com/oauth/authorize?client_id=&response_type=code&redirect_uri=https://localhost:8080/oauth/callback ``` 1. 完成授权流程。 1. 使用 Snowflake 凭证登录。 1. 授予所需的权限。您将被重定向到带有授权码的回调 URI。 1. 从重定向 URL 中复制代码参数来提取授权码。 ``` https://localhost:8080/oauth/callback?code= ``` **注意** 该授权码仅在有限时间内有效，而且只能使用一次。 1. **将 OAuth 凭证存储在 AWS Secrets Manager 中** 在 AWS Secrets Manager 中，创建一个使用以下结构的密钥。 ``` { "redirect_uri": "https://localhost:8080/oauth/callback", "client_secret": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY", "token_url": "https://.snowflakecomputing.com/oauth/token-request", "client_id": "AIDACKCEVSQ6C2EXAMPLE, "username": "your_snowflake_username", "auth_code": "authorizationcode" } ``` **必填字段** + `redirect_uri`：您在步骤 1 中获得的 OAuth 重定向 URI。 + `client_secret`：您在步骤 2 中获得的 OAuth 客户端密钥。 + `token_url`：Snowflake OAuth 令牌端点。 + `client_id`：步骤 2 中的 OAuth 客户端 ID。 + `username`：连接器的 Snowflake 用户名。 + `auth_code`：您在步骤 3 中获得的授权码。 创建密钥后，您将获得一个密钥 ARN，您可以在[创建数据来源连接](connect-to-a-data-source.md)时在 Glue 连接中使用该密钥 ARN。 ## 传递查询 Snowflake 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Snowflake 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Snowflake 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 Snowflake 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-snowflake)。 # Amazon Athena Microsoft SQL Server 连接器 适用于 [Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/?view=sql-server-ver15) 的 Amazon Athena 连接器使 Amazon Athena 能够使用 JDBC 对存储在 Microsoft SQL Server 中的数据运行 SQL 查询。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 在筛选条件中，必须将 `Date` 和 `Timestamp` 数据类型转换为适当的数据类型。 + 要搜索类型 `Real` 和 `Float` 的负值，请使用 `<=` 或 `>=` 运算符。 + 不支持 `binary`、`varbinary`、`image` 和 `rowversion` 数据类型。 ## 术语 以下术语与 SQL Server 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 SQL Server 连接器。 **注意** 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 连接对象来配置 SQL Server 连接器。要执行此操作，请将 SQL Server 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type SQLSERVER ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 SQL Server 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 SQL Server 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` sqlserver://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | SqlServerMuxCompositeHandler | | 元数据处理程序 | SqlServerMuxMetadataHandler | | 记录处理程序 | SqlServerMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mysqlservercatalog，则环境变量名称是 mysqlservercatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 SQLServer MUX Lambda 函数：`sqlserver1`（默认）和 `sqlserver2`。 **** | 属性 | 值 | | --- | --- | | default | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 | | sqlserver\$1catalog1\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 | | sqlserver\$1catalog2\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver2.hostname:port;databaseName=;\$1\$1secret2\$1name\$1 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${secret_name}`。 ``` sqlserver://jdbc:sqlserver://hostname:port;databaseName=;${secret_name} ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` sqlserver://jdbc:sqlserver://hostname:port;databaseName=;user=;password= ``` #### 使用单个连接处理程序 您可以使用以下单连接元数据和记录处理程序连接到单个 SQL Server 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | SqlServerCompositeHandler | | 元数据处理程序 | SqlServerMetadataHandler | | 记录处理程序 | SqlServerRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 SQL Server 实例。 **** | 属性 | 值 | | --- | --- | | default | sqlserver://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 SQL Server 和 Apache Arrow 的相应数据类型。 **** | SQL Server | Arrow | | --- | --- | | bit | TINYINT | | tinyint | SMALLINT | | smallint | SMALLINT | | int | INT | | bigint | BIGINT | | decimal | DECIMAL | | numeric | FLOAT8 | | smallmoney | FLOAT8 | | money | DECIMAL | | float[24] | FLOAT4 | | float[53] | FLOAT8 | | real | FLOAT4 | | datetime | Date(MILLISECOND) | | datetime2 | Date(MILLISECOND) | | smalldatetime | Date(MILLISECOND) | | date | Date(DAY) | | 时间 | VARCHAR | | datetimeoffset | Date(MILLISECOND) | | char[n] | VARCHAR | | varchar[n/max] | VARCHAR | | nchar[n] | VARCHAR | | nvarchar[n/max] | VARCHAR | | 文本 | VARCHAR | | ntext | VARCHAR | ## 分区和拆分 分区由类型为 `varchar` 的单个分区列表示。如果是 SQL Server 连接器，则分区函数决定如何在表上应用分区。分区函数和列名称信息可以从 SQL Server 元数据表中检索。然后，自定义查询会获取分区。拆分是根据收到的不同分区的数量而创建。 ## 性能 选择列的子集可以显著减少查询运行时及扫描的数据。SQL Server 连接器能够灵活地应对并发造成的节流。 Athena SQL Server 连接器可执行谓词下推，以减少查询扫描的数据量。简单谓词和复杂表达式将下推到连接器，以减少扫描的数据量并缩短查询执行的运行时间。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena SQL Server 连接器可以组合这些表达式并将其直接推送到 SQL Server，以增强功能并减少扫描的数据量。 以下 Athena SQL Server 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 传递查询 SQL Server 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 SQL Server 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 SQL Server 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 SQL Server 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-sqlserver)。 # Amazon Athena Teradata 连接器 适用于 Teradata 的 Amazon Athena 连接器使 Athena 能够对存储在 Teradata 数据库中的数据运行 SQL 查询。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 ## 术语 以下术语与 Teradata 连接器有关。 + **数据库实例** — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Teradata 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Teradata 连接器。要执行此操作，请将 Teradata 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type TERADATA ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Teradata 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Teradata 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` teradata://${jdbc_connection_string} ``` #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | TeradataMuxCompositeHandler | | 元数据处理程序 | TeradataMuxMetadataHandler | | 记录处理程序 | TeradataMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myteradatacatalog，则环境变量名称是 myteradatacatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Teradata MUX Lambda 函数：`teradata1`（默认）和 `teradata2`。 **** | 属性 | 值 | | --- | --- | | default | teradata://jdbc:teradata://teradata2.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,user=sample2&password=sample2 | | teradata\$1catalog1\$1connection\$1string | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,\$1\$1Test/RDS/Teradata1\$1 | | teradata\$1catalog2\$1connection\$1string | teradata://jdbc:teradata://teradata2.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,user=sample2&password=sample2 | ##### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/Teradata1}`。 ``` teradata://jdbc:teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,${Test/RDS/Teradata1}&... ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,...&user=sample2&password=sample2&... ``` 目前，Teradata 可以识别 `user` 和 `password` JDBC 属性。还接受以下格式的用户名和密码：*用户名*`/`*密码*（不含密钥 `user` 或 `password`）。 #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Teradata 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | TeradataCompositeHandler | | 元数据处理程序 | TeradataMetadataHandler | | 记录处理程序 | TeradataRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 以下示例属性适用于 Lambda 函数支持的单个 Teradata 实例。 **** | 属性 | 值 | | --- | --- | | default | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,secret=Test/RDS/Teradata1 | #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了适用于 JDBC 和 Apache Arrow 的相应数据类型。 **** | JDBC | Arrow | | --- | --- | | 布尔值 | Bit | | 整数 | Tiny | | 短型 | Smallint | | 整数 | Int | | 长整型 | Bigint | | 浮点数 | Float4 | | 双精度 | Float8 | | 日期 | DateDay | | Timestamp | DateMilli | | 字符串 | Varchar | | 字节 | Varbinary | | BigDecimal | 十进制 | | ARRAY | 列表 | ## 分区和拆分 分区由类型为 `Integer` 的单个分区列表示。该列包含在 Teradata 表中定义的分区的分区名称。对于没有分区名称的表，返回 \$1，相当于单个分区。分区等同于拆分。 **** | 名称 | Type | 说明 | | --- | --- | --- | | 分区 | 整数 | Teradata 中的命名分区。 | ## 性能 Teradata 支持本机分区。Athena Teradata 连接器可从这些分区并行检索数据。如果您想查询具有统一分区分布的超大型数据集，强烈建议使用本机分区。选择列的子集会显著减少查询运行时。由于并发，连接器显示出一定的节流。 Athena Teradata 连接器可执行谓词下推，以减少查询扫描的数据量。简单谓词和复杂表达式将下推到连接器，以减少扫描的数据量并缩短查询执行的运行时间。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Teradata 连接器可以组合这些表达式并将其直接推送到 Teradata，以增强功能并减少扫描的数据量。 以下 Athena Teradata 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 传递查询 Teradata 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Teradata 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Teradata 中的数据来源。该查询会选择 `customer` 表中的所有列。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 Teradata 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/pom.xml)文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-teradata)。 # Amazon Athena Timestream 连接器 Amazon Athena Timestream 连接器使 Amazon Athena 能够与 [Amazon Timestream](https://aws.amazon.com/timestream/) 进行通信，从而使您的时间序列数据可以通过 Amazon Athena 访问。您可以选择使用 AWS Glue Data Catalog 作为元数据的补充来源。 Amazon Timestream 是一个快速、可扩展、完全托管式、专门构建的时间序列数据库，每天可轻松存储和分析数万亿个时间序列数据点。Timestream 通过根据用户定义的策略将最新数据保存在内存中，并将历史数据移动到成本优化的存储层，从而节省您在管理时间序列数据生命周期方面的时间和成本。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 如果您在账户中启用了 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)。 ## 参数 使用本节中的参数来配置 Timestream 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Timestream 连接器。要执行此操作，请将 Timestream 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type TIMESTREAM ``` **Lambda 环境属性** **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Timestream 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Timestream 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 **Lambda 环境属性** + **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)时。 + **glue\$1catalog** –（可选）使用此选项指定[跨账户 AWS Glue 目录](data-sources-glue-cross-account.md)。默认情况下，该连接器将尝试从其自己的 AWS Glue 账户中获取元数据。 ## 在 AWS Glue 中设置数据库和表 您可以选择使用 AWS Glue Data Catalog 作为元数据的补充来源。要使 AWS Glue 表与 Timestream 配合使用，必须具备 AWS Glue 数据库和表，且它们的名称应与要提供补充元数据的 Timestream 数据库和表相匹配。 **注意** 为了获得最佳性能，数据库名称和表名称仅限使用小写。使用混合大小写会使连接器执行不区分大小写的搜索，这种搜索的计算密集度更高。 要配置 AWS Glue 表与 Timestream 配合使用，您必须在 AWS Glue 中设置其表属性。 **将 AWS Glue 表用于补充元数据** 1. 在 AWS Glue 控制台中编辑表，添加以下表属性： + **timestream-metadata-flag** — 此属性向 Timestream 连接器指明该连接器可将该表用于补充元数据。只要表属性的列表中存在 `timestream-metadata-flag` 属性，您就可以为 `timestream-metadata-flag` 提供任何值。 + **\$1view\$1template** — 使用 AWS Glue 作为补充元数据时，您可以使用此表属性并指定任何 Timestream SQL 作为视图。Athena Timestream 连接器使用来自视图的 SQL 和来自 Athena 的 SQL 来运行查询。如果您想使用 Athena 中不具备的 Timestream SQL 功能，这将非常有用。 1. 请确保使用适合 AWS Glue 的数据类型，如本文档中所列。 ### 数据类型 目前，Timestream 连接器仅支持 Timestream 中可用数据类型的子集，尤其是：标量值 `varchar`、`double` 和 `timestamp`。 要查询 `timeseries` 数据类型，您必须在使用 Timestream `CREATE_TIME_SERIES` 函数的 AWS Glue 表属性中配置视图。您还需要为使用语法 `ARRAY>` 作为任何时间序列列的类型的视图提供架构。务必将 `double` 替换为适合您表的标量类型。 下图显示了为设置时间序列视图而配置的 AWS Glue 表属性的示例。 ![\[在 AWS Glue 中配置表属性，以设置时间序列视图。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-timestream-1.png) ## 所需权限 要获取有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-timestream.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-timestream/athena-timestream.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 + **AWS Glue Data Catalog** — Timestream 连接器需要针对 AWS Glue Data Catalog 的只读访问权限，以获取架构信息。 + **CloudWatch Logs** – 该连接器需要针对 CloudWatch Logs 的访问权限，以存储日志。 + **Timestream 访问权限** — 用于运行 Timestream 查询。 ## 性能 建议您使用 `LIMIT` 子句将返回的数据（非扫描的数据）限制在 256 MB 以内，以确保交互式查询性能良好。 Athena Timestream 连接器执行谓词下推，以减少查询扫描的数据。`LIMIT` 子句可减少扫描的数据量，但如果未提供谓词，则预期要使用包含 `LIMIT` 子句的 `SELECT` 查询来扫描至少 16 MB 的数据。选择列的子集可以显著减少查询运行时及扫描的数据。Timestream 连接器能够灵活地应对并发造成的节流。 ## 传递查询 Timestream 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Timestream 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Timestream 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 Amazon Athena Timestream 连接器项目已根据 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)获得许可。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-timestream)。 # Amazon Athena TPC 基准 DS（TPC-DS）连接器 Amazon Athena TPC-DS 连接器使 Amazon Athena 可以与随机生成的 TPC 基准 DS 数据源通信，用于 Athena Federation 的基准测试和功能测试。Athena TPC-DS 连接器以四种比例因子之一生成符合 TPC-DS 标准的数据库。我们不建议将此连接器用作基于 Amazon S3 的数据湖性能测试的替代方法。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 参数 使用本节中的参数来配置 TPC-DS 连接器。 **注意** 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 连接对象来配置 TPC-DS 连接器。要执行此操作，请将 TPC-DS 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type TPCDS ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 TPC-DS 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 TPC-DS 连接器仅支持 `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)时。 ## 测试数据库和表 Athena TPC-DS 连接器以四种比例因子之一（`tpcds1`、`tpcds10`、`tpcds100`、`tpcds250` 或 `tpcds1000`）生成符合 TPC-DS 标准的数据库。 ### 表格摘要 有关测试数据表和列的完整列表，请运行 `SHOW TABLES` 或 `DESCRIBE TABLE` 查询。为方便起见，提供以下表格摘要。 1. call\$1center 1. catalog\$1page 1. catalog\$1returns 1. catalog\$1sales 1. customer 1. customer\$1address 1. customer\$1demographics 1. date\$1dim 1. dbgen\$1version 1. household\$1demographics 1. income\$1band 1. 清单 1. item 1. promotion 1. reason 1. ship\$1mode 1. 存储 1. store\$1returns 1. store\$1sales 1. time\$1dim 1. warehouse 1. web\$1page 1. web\$1return 1. web\$1sales 1. web\$1site 有关与此生成的架构和数据兼容的 TPC-DS 查询，请参阅 GitHub 上的 [athena-tpcds/src/main/resources/queries/](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds/src/main/resources/queries) 目录。 ### 示例查询 以下 `SELECT` 查询示例查询特定县的客户人口统计数据的 `tpcds` 目录。 ``` SELECT cd_gender, cd_marital_status, cd_education_status, count(*) cnt1, cd_purchase_estimate, count(*) cnt2, cd_credit_rating, count(*) cnt3, cd_dep_count, count(*) cnt4, cd_dep_employed_count, count(*) cnt5, cd_dep_college_count, count(*) cnt6 FROM "lambda:tpcds".tpcds1.customer c, "lambda:tpcds".tpcds1.customer_address ca, "lambda:tpcds".tpcds1.customer_demographics WHERE c.c_current_addr_sk = ca.ca_address_sk AND ca_county IN ('Rush County', 'Toole County', 'Jefferson County', 'Dona Ana County', 'La Porte County') AND cd_demo_sk = c.c_current_cdemo_sk AND exists(SELECT * FROM "lambda:tpcds".tpcds1.store_sales, "lambda:tpcds".tpcds1.date_dim WHERE c.c_customer_sk = ss_customer_sk AND ss_sold_date_sk = d_date_sk AND d_year = 2002 AND d_moy BETWEEN 1 AND 1 + 3) AND (exists(SELECT * FROM "lambda:tpcds".tpcds1.web_sales, "lambda:tpcds".tpcds1.date_dim WHERE c.c_customer_sk = ws_bill_customer_sk AND ws_sold_date_sk = d_date_sk AND d_year = 2002 AND d_moy BETWEEN 1 AND 1 + 3) OR exists(SELECT * FROM "lambda:tpcds".tpcds1.catalog_sales, "lambda:tpcds".tpcds1.date_dim WHERE c.c_customer_sk = cs_ship_customer_sk AND cs_sold_date_sk = d_date_sk AND d_year = 2002 AND d_moy BETWEEN 1 AND 1 + 3)) GROUP BY cd_gender, cd_marital_status, cd_education_status, cd_purchase_estimate, cd_credit_rating, cd_dep_count, cd_dep_employed_count, cd_dep_college_count ORDER BY cd_gender, cd_marital_status, cd_education_status, cd_purchase_estimate, cd_credit_rating, cd_dep_count, cd_dep_employed_count, cd_dep_college_count LIMIT 100 ``` ## 所需权限 有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-tpcds..yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-tpcds/athena-tpcds.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。 + **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。 + **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。 ## 性能 Athena TPC-DS 连接器尝试根据您选择的比例因子对查询并行化处理。谓词下推在 Lambda 函数中执行。 ## 许可证信息 Amazon Athena TPC-DS 连接器项目已根据 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)获得许可。 ## 其他资源 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds)。 # Amazon Athena Vertica 连接器 Vertica 是一个列存数据库平台，可以部署在云中或在支持 EB 级数据仓库的本地部署。您可以在联合查询中使用 Amazon Athena Vertica 连接器来查询来自 Athena 的 Vertica 数据来源。例如，您可以通过 Vertica 上的数据仓库和 Amazon S3 中的数据湖运行分析查询。 此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 + 使用此连接器前，请先设置 VPC 和安全组。有关更多信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 ## 限制 + 由于 Athena Vertica 连接器从 Amazon S3 读取导出的 Parquet 文件，因此连接器的性能可能很慢。查询大型表时，我们建议您使用[创建表为（选择...）](ctas.md)查询和 SQL 谓词。 + 目前，由于 Athena 联合查询中存在一个已知问题，连接器会让 Vertica 将查询表的所有列导出到 Amazon S3，但在 Athena 控制台的结果中只能看到被查询的列。 + 不支持写入 DDL 操作。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 ## 工作流 以下图表显示了使用 Vertica 连接器运行查询的工作流程。 ![\[Amazon Athena 的 Vertica 查询的工作流程\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-vertica-1.png) 1. 针对 Vertica 中的一个或多个表发出 SQL 查询。 1. 连接器解析 SQL 查询，以通过 JDBC 连接将相关部分发送到 Vertica。 1. 连接字符串使用存储在 AWS Secrets Manager 中的用户名和密码，以获得 Vertica 的访问权限。 1. 连接器使用 Vertica `EXPORT` 命令包装 SQL 查询，如以下示例所示。 ``` EXPORT TO PARQUET (directory = 's3://amzn-s3-demo-bucket/folder_name, Compression='Snappy', fileSizeMB=64) OVER() as SELECT PATH_ID, ... SOURCE_ITEMIZED, SOURCE_OVERRIDE FROM DELETED_OBJECT_SCHEMA.FORM_USAGE_DATA WHERE PATH_ID <= 5; ``` 1. Vertica 处理 SQL 查询并将结果集发送到 Amazon S3 存储桶。为了提高吞吐量，Vertica 使用 `EXPORT` 选项并行处理多个 Parquet 文件的写入操作。 1. Athena 扫描 Amazon S3 存储桶，以确定要为结果集读取的文件数。 1. Athena 对 Lambda 函数进行多次调用，并使用 Apache `ArrowReader` 从结果数据集中读取 Parquet 文件。多次调用使 Athena 能够并行读取 Amazon S3 文件，实现高达每秒 100GB 的吞吐量。 1. Athena 使用数据湖扫描的数据处理从 Vertica 返回的数据并返回结果。 ## 术语 以下术语与 Vertica 连接器有关。 + **数据库实例** — 部署在 Amazon EC2 上的 Vertica 数据库的任何实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 ## 参数 使用本节中的参数来配置 Vertica 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Vertica 连接器。要执行此操作，请将 Vertica 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type VERTICA ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。 + **小写** – 所有给定的架构和表名全部小写。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Vertica 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Vertica 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 Amazon Athena Vertica 连接器通过 Lambda 环境变量显示了配置选项。您可以使用以下 Lambda 环境变量来配置连接器。 + **AthenaCatalogName** — Lambda 函数名称 + **ExportBucket** — 将 Vertica 查询结果导出到的 Amazon S3 存储桶。 + **SpillBucket** — 此函数可以溢出数据的 Amazon S3 存储桶的名称。 + **SpillPrefix** — 此函数可以溢出数据的 `SpillBucket` 位置的前缀。 + **SecurityGroupIds** — 与应该应用于 Lambda 函数的安全组对应的一个或多个 ID（例如 `sg1`、`sg2` 或 `sg3`)。 + **SubnetIds** — 与 Lambda 函数可用于访问您数据来源的子网对应的一个或多个子网 ID（例如 `subnet1` 或 `subnet2`)。 + **SecretNameOrPrefix** — 此函数有权访问的 Secrets Manager 中一组密钥的名称或前缀（例如 `vertica-*`) + **VerticaConnectionString** — 如果未定义特定于目录的连接，则默认使用的 Vertica 连接详细信息。该字符串可以选择使用 AWS Secrets Manager 语法（例如 `${secret_name}`)。 + **VPC ID** — 要附加到 Lambda 函数的 VPC ID。 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` vertica://jdbc:vertica://host_name: port/database?user=vertica-username&password= vertica-password ``` #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Vertica 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | VerticaCompositeHandler | | 元数据处理程序 | VerticaMetadataHandler | | 记录处理程序 | VerticaRecordHandler | #### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 #### 提供凭证 要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。 + **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。 **重要** 作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《*AWS Secrets Manager 用户指南*》中的[将硬编码密钥移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)。 + **AWS Secrets Manager** - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。 您可以将 AWS Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。 对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 AWS Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 \$1\$1`vertica-username`\$1 和 `${vertica-password}`。 ``` vertica://jdbc:vertica:// host_name:port/database?user=${vertica-username}&password=${vertica-password} ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` vertica://jdbc:vertica:// host_name:port/database?user=sample-user&password=sample-password ``` 目前，Vertica 连接器可以识别 `vertica-username` 和 `vertica-password` JDBC 属性。 #### 溢出参数 Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。 **** | 参数 | 说明 | | --- | --- | | spill\$1bucket | 必需。溢出桶名称。 | | spill\$1prefix | 必需。溢出桶密钥前缀。 | | spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | ## 数据类型支持 下表显示了 Vertica 连接器支持的数据类型。 **** | 布尔值 | | --- | | BigInt | | 短型 | | 整数 | | 长整型 | | 浮点型 | | 双精度 | | 日期 | | Varchar | | 字节 | | BigDecimal | | 作为 Varchar 的时间戳 | ## 性能 Lambda 函数执行投影下推，以减少查询扫描的数据。`LIMIT` 子句会减少扫描的数据量，但如果未提供谓词，则预期要使用包含 `LIMIT` 子句的 `SELECT` 查询来扫描至少 16 MB 的数据。Vertica 连接器能够灵活地应对并发造成的节流。 ## 传递查询 Vertica 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Vertica 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Vertica 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 Vertica 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) 文件。 有关此连接器的更多信息，请参阅 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-vertica)，以及*AWS 大数据博客*中的文章“[使用 Athena 联合查询 SDK 在 Amazon Athena 中查询 Vertica 数据来源](https://aws.amazon.com/blogs/big-data/querying-a-vertica-data-source-in-amazon-athena-using-the-athena-federated-query-sdk/)”。 # 创建数据来源连接 要使用 Athena 数据来源连接器，您需要创建 AWS Glue 连接，用来存储有关该连接器和数据来源的连接信息。创建连接时，您需要为数据来源指定一个名称，以用于在 SQL 查询中引用您的数据来源。 您可以使用[控制台](connect-to-a-data-source-console-steps.md)或 [CreateDataCatalog API](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateDataCatalog.html) 操作在 Athena 中创建和配置数据来源连接。 **Topics** + [在 Athena 中创建和使用数据来源的权限](connect-to-a-data-source-permissions.md) + [使用 Athena 控制台连接数据来源](connect-to-a-data-source-console-steps.md) + [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md) + [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md) + [将 ECR 映像拉取到您的 AWS 账户](pull-ecr-customer-account.md) + [将连接注册为 Glue Data Catalog](register-connection-as-gdc.md) + [启用跨账户联合查询](xacct-fed-query-enable.md) + [更新数据来源连接器](connectors-updating.md) # 在 Athena 中创建和使用数据来源的权限 要创建和使用数据来源，您需要以下权限集。 + AmazonAthenaFullAccess，提供对 Amazon Athena 的完全访问权限，以及对启用查询、写入结果和数据管理所需依赖项的限定访问权限。有关更多信息，请参阅《AWS 托管式策略参考指南》中的 [AmazonAthenaFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html)。 + 调用 CreateDataCatalog API 的权限。只有在创建与 Glue 连接集成的数据来源时，才需要这些权限。有关示例策略的更多信息，请参阅[创建连接器和 Athena 目录所需的权限](athena-catalog-access.md)。 + 要使用 Lake Formation 精细访问控制，除上面列出的权限外，还需要以下权限。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "lakeformation:RegisterResource", "iam:ListRoles", "glue:CreateCatalog", "glue:GetCatalogs", "glue:GetCatalog" ], "Resource": "*" } ] } ``` ------ # 使用 Athena 控制台连接数据来源 您可以使用 Athena 控制台创建和配置数据来源连接。 **创建数据来源连接** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 在导航窗格中，选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择**创建数据来源**。 1. 对于**选择数据来源**，请选择想要 Athena 查询的数据来源，同时考虑以下准则： + 选择与数据来源对应的连接选项。Athena 具有预构建的数据来源连接器，您可以为 MySQL、Amazon DocumentDB 和 PostgreSQL 等源配置这些连接器。 + 如果您想查询 Amazon S3 中的数据，但您没有使用 Apache Hive 元存储或本页面上的其他联合查询数据来源选项之一，请选择 **S3 - AWS Glue Data Catalog**。Athena 使用 AWS Glue Data Catalog 在 Amazon S3 中存储数据来源的元数据和架构信息。这是默认的（非联合）选项。有关更多信息，请参阅 [使用 AWS Glue Data Catalog 连接数据](data-sources-glue.md)。有关使用此工作流的步骤，请参阅[在 Athena 中注册和使用数据目录](gdc-register.md)。 + 选择 **S3 - Apache Hive 元存储**，查询在 Amazon S3 中使用 Apache Hive 元存储的数据集。有关此选项的更多信息，请参阅 [将 Athena 连接到 Apache Hive 元存储](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md)。 + 如果您想创建自己的数据来源连接器，以便与 Athena 一起使用，请选择**自定义或共享连接器**。有关编写数据来源连接器的信息，请参阅 [使用 Athena Query Federation SDK 编写数据来源连接器](connect-data-source-federation-sdk.md)。 1. 选择**下一步**。 1. 在**输入数据来源详细信息**页面中，对于**数据来源名称**，请输入从 Athena 查询该数据来源时要在 SQL 语句中使用的名称。名称最多可以包括 127 个字符，并且在您的账户中必须是唯一的。它在创建后即无法更改。有效字符包括 a-z、A-Z、0-9、\$1（下划线）、@（at 符号）和 -（连字符）。名称 `awsdatacatalog`、`hive`、`jmx` 和 `system` 是 Athena 预留的名称，无法用于数据来源名称。 1. 如果您选择的数据来源与 AWS Glue 连接集成： 1. 对于 **AWS Glue 连接详细信息**，请输入所需的信息。连接包含连接到特定数据来源所需的属性。所需的属性因连接类型而异。有关与连接器相关的属性的更多信息，请参阅[可用数据来源连接器](connectors-available.md)。有关其他连接属性的信息，请参阅《AWS Glue 用户指南》中的 [AWS Glue 连接属性](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)**。 **注意** 更新 Glue 连接属性时，需要重新启动 Lambda 连接器才能获取更新后的属性。要执行此操作，请编辑环境属性，然后在实际上并未更改任何内容的情况下将其保存。 更新 Glue 连接时，以下属性不会在相应的 Lambda 函数中自动更新。您必须手动为 Lambda 函数更新这些属性。 Lambda VPC 配置 – `security_group_ids`、`subnet_ids` Lambda 执行角色 – `spill_bucket`、`secret_name`、`spill_kms_key_id` 1. 对于 **Lambda 执行 IAM 角色**，请选择下列选项中的一个： + **创建并使用新的执行角色** –（默认）Athena 会创建一个执行角色，然后使用该角色代表您访问 AWS Lambda 中的资源。Athena 需要此角色才能创建联合数据来源。 + **使用现有执行角色** – 使用此选项以选择一个现有的执行角色。对于此选项，请从**执行角色**下拉列表中选择要使用的执行角色。 1. 如果您选择的数据来源未与 AWS Glue 连接集成： 1. 对于 **Lambda function**（Lambda 函数），请选择 **Create Lambda function**（创建 Lambda 函数）。您选择的连接器的函数页将在 AWS Lambda 控制台中打开。该页面包括连接器的详细信息。 1. 在 **Application settings**（应用程序设置）项下，请仔细阅读每个应用程序设置的说明，然后输入符合您要求的值。 您看到的应用程序设置因数据来源的连接器而异。所需的最低设置包括： + **AthenaCatalogName**：指明其目标数据来源的小写 Lambda 函数名称，例如 `cloudwatchlogs`。 + **SpillBucket** – 您的账户中用于存储超出 Lambda 函数响应大小限制的数据的 Amazon S3 存储桶。 **注意** 溢出的数据不会在后续的执行中重复使用，并且可以安全地删除。Athena 不会为您删除这些数据。要管理这些对象，请考虑添加一个将从 Amazon S3 溢出存储桶中删除旧数据的对象生命周期策略。有关更多信息，请参阅《Amazon S3 用户指南》中的[管理对象的生命周期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)。 1. 选中 **I acknowledge that this app creates custom IAM roles and resource policies**（我确认此应用程序创建自定义 IAM 角色和资源策略）。有关更多信息，请选择 **Info (信息)** 链接。 1. 选择**部署**。部署完成后，Lambda 函数将显示在 Lambda 控制台中的 **Resource**（资源）部分。 将数据来源连接器部署到您的账户后，可以将 Athena 连接到此数据来源连接器。 1. 返回至 Athena 控制台中的**输入数据来源详细信息**页面。 1. 在 **Connection details**（连接详细信息）部分中，选择 **Select or enter a Lambda function**（选择或输入 Lambda 函数）搜索框旁的刷新图标。 1. 在 Lambda 控制台上选择刚创建的函数名称。将显示 Lambda 函数的 ARN。 1. （可选）对于**标签**，添加要与此数据来源关联的键值对。有关标签的更多信息，请参阅[标记 Athena 资源](tags.md)。 1. 选择**下一步**。 1. 在**检查并创建**页面上，检查数据来源的详细信息。要进行更改，请选择**编辑**。 1. 阅读 **Athena 将在您的账户中创建资源**中的信息。如果您同意，请选择**我确认 Athena 将代表我创建资源**。 1. 选择**创建数据来源**。**Athena** 将为您创建以下资源。 + Lambda 执行 IAM 角色 + AWS Glue 连接（仅限数据来源与 AWS Glue 连接兼容时） + Lambda 函数 数据来源此页面的**数据来源详细信息**部分显示了有关新连接器的信息。现在，您可以在 Athena 查询中使用连接器。 有关在查询中使用数据连接器的信息，请参阅 [运行联合查询](running-federated-queries.md)。 # 使用 AWS Serverless Application Repository 部署数据来源连接器 要部署数据来源连接器，您可以使用 [AWS Serverless Application Repository](https://aws.amazon.com/serverless/serverlessrepo/) 而不使用 AWS Glue 连接。 **注意** 我们建议您仅在使用自定义连接器或需要使用早期版本连接器时使用 SAR。对于其他情况，我们建议您使用 Athena 控制台。 您可以使用 AWS Serverless Application Repository 找到要使用的连接器，提供连接器所需的参数，然后将连接器部署到您的账户。部署连接器后，您可以使用 Athena 控制台向 Athena 提供数据来源。 ## 将连接器部署到您的账户 **使用 AWS Serverless Application Repository 将数据来源连接器部署到您的账户** 1. 登录 AWS 管理控制台并打开 **Serverless App Repository (无服务器应用程序存储库)**。 1. 在导航窗格中，选择 **Available applications (可用应用程序)**。 1. 选择 **Show apps that create custom IAM roles or resource policies**（显示创建自定义 IAM 角色或资源策略的应用程序）选项。 1. 在搜索框中，键入连接器的名称。有关预构建的 Athena 数据连接器的列表，请参阅 [可用数据来源连接器](connectors-available.md)。 1. 选择连接器的名称。选择连接器后会打开 AWS Lambda 控制台中 Lambda 函数的 **Application details**（应用程序详细信息）页面。 1. 在详细信息页面的右侧，为 **Application settings**（应用程序设置）填写必填信息。最少的必填设置包括以下项。有关适用于 Athena 所构建的数据连接器的其余可配置选项的信息，请参阅 GitHub 上相应的 [Available connectors](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors)（可用连接器）主题。 + **AthenaCatalogName**：指明其目标数据来源的小写 Lambda 函数名称，例如 `cloudwatchlogs`。 + **SpillBucket** – 在您的账户指定一个 Amazon S3 存储桶，用于接收来自超出 Lambda 函数响应大小限制的任何大型响应有效负载的数据。 1. 选中 **I acknowledge that this app creates custom IAM roles and resource policies**（我确认此应用程序创建自定义 IAM 角色和资源策略）。有关更多信息，请选择 **Info (信息)** 链接。 1. 在 **Application settings**（应用程序设置）部分的右下角，选择 **Deploy**（部署）。部署完成后，Lambda 函数将显示在 Lambda 控制台中的 **Resource**（资源）部分。 ## 使连接器在 Athena 中可用 现在您可以使用 Athena 控制台使数据来源连接器对 Athena 可用。 **使数据来源连接器对 Athena 可用** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 在导航窗格中，选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择**创建数据来源**。 1. 对于**选择数据来源**，选择您在 AWS Serverless Application Repository 中创建了连接器的数据来源。本教程使用 **Amazon CloudWatch Logs** 作为联合数据来源。 1. 选择**下一步**。 1. 在**输入数据来源详细信息**页面中，对于**数据来源名称**，请输入从 Athena 查询数据来源时要在 SQL 语句中使用的名称（例如 `CloudWatchLogs`）。名称最多可以包括 127 个字符，并且在您的账户中必须是唯一的。它在创建后即无法更改。有效字符包括 a-z、A-Z、0-9、\$1（下划线）、@（at 符号）和 -（连字符）。名称 `awsdatacatalog`、`hive`、`jmx` 和 `system` 是 Athena 预留的名称，无法用于数据来源名称。 1. 在 **Connection details**（连接详细信息）部分中，请使用 **Select or enter a Lambda function**（选择或输入 Lambda 函数）框以选择刚创建的函数名称。将显示 Lambda 函数的 ARN。 1. （可选）对于**标签**，添加要与此数据来源关联的键值对。有关标签的更多信息，请参阅[标记 Athena 资源](tags.md)。 1. 选择**下一步**。 1. 在**审核和创建**页面中，查看数据来源的详细信息，然后选择**创建数据来源**。 1. 数据来源此页面的**数据来源详细信息**部分显示了有关新连接器的信息。现在，您可以在 Athena 查询中使用连接器。 有关在查询中使用数据连接器的信息，请参阅 [运行联合查询](running-federated-queries.md)。 # 为数据来源连接器或 AWS Glue 连接创建 VPC 部分 Athena 数据来源连接器和 AWS Glue 连接需要使用 VPC 和安全组。本主题介绍如何创建具有子网的 VPC，以及如何为 VPC 创建安全组。在此过程中，您要检索自己创建的 VPC、子网和安全组的 ID。您需要这些 ID 来配置 AWS Glue 连接或数据来源连接器，以便与 Athena 搭配使用。 **为 Athena 数据来源连接器创建 VPC** 1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon VPC 控制台：[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)。 1. 选择**创建 VPC**。 1. 在**创建 VPC** 页面的 **VPC 设置**下，对于**要创建的资源**，选择 **VPC 等**。 1. 在**名称标签自动生成**下，对于**自动生成**，输入一个值，该值将用于为 VPC 中的所有资源生成名称标签。 1. 选择**创建 VPC**。 1. 过程完成后，选择**查看 VPC**。 1. 在 **Details**（详细信息）部分的 **VPC ID** 中，复制 VPC ID 供之后参考。 现在，您可以检索刚才创建的 VPC 的子网 ID。 **检索 VPC 子网 ID** 1. 在 VPC 控制台的导航窗格中，选择 **Subnets**（子网）。 1. 选择一个子网的名称，该子网的 **VPC** 列包含您记下的 VPC ID。 1. 在 **Details**（详细信息）部分的 **Subnet ID**（子网 ID）中，复制子网 ID 供之后参考。 接着为 VPC 创建安全组。 **为 VPC 创建安全组** 1. 在 VPC 控制台的导航窗格中，依次选择 **Security**（安全）、**Security Groups**（安全组）。 1. 选择**创建安全组**。 1. 在 **Create Security Group**（创建安全组）页面上，输入以下信息： + 在 **Security group name**（安全组名称）中，为安全组输入名称。 + 在 **Description**（描述）中，为安全组输入描述。必须提供说明。 + 对于 **VPC**，选择您为数据来源连接器创建的 VPC 的 VPC ID。 + 在 **Inbound rules**（入站规则）和 **Outbound rules**（出站规则）中，分别添加所需的入站和出站规则。 1. 选择**创建安全组**。 1. 在安全组的 **Details**（详细信息）页面中，复制 **Security group ID**（安全组 ID）供之后参考。 ## 将 VPC 与 Athena 连接器配合使用时的重要注意事项 以下说明适用于所有 Athena 连接器，因为所有连接器都可以使用 VPC。 **注意** 将 VPC 与 AWS Glue 连接配合使用时，您需要设置以下 PrivateLink 端点： Amazon S3 AWS Glue AWS Secrets Manager 或者，您也可以使用公共互联网访问，但出于安全原因，不建议这样做。 **警告** 使用公共互联网访问可能会使您的资源面临额外的安全风险。强烈建议在 VPC 配置中使用 PrivateLink 端点以增强安全性。 # 将 ECR 映像拉取到您的 AWS 账户 Athena Federation Connector 的 Lambda 函数使用存储在 Athena 托管的 Amazon ECR 存储库中的容器映像。要对这些容器映像执行安全扫描，您必须先将其复制到您账户中的 Amazon ECR 存储库。本节提供了有关如何将映像复制到您的存储库以及如何配置 Lambda 函数以使用该映像的分步说明。 ## 先决条件 + Athena Federation Connector：只要使用容器映像，就可以通过任何来源创建连接器。 **注意** 要验证映像部署，请查看 Athena Federation Connector Lambda 中的“映像”选项卡 + Docker 已安装且正在运行 + 已安装 AWS CLI + 具有适当拉取权限的账户凭证 ## 如何传输映像 1. 从 Athena Federation Connector Lambda 中找到映像 URI **Example** ``` account_id_1.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.15.1 ``` 1. 为 Athena 托管账户生成 Docker 身份验证令牌： ``` aws ecr get-login-password --region regionID | docker login --username AWS --password-stdin athena-managed-registry ``` 其中： + *regionID* 是您的部署区域（例如 us-east-1） + *athena-managed-registry* 是映像 URI 的注册表部分（例如 account\$1id\$11.dkr.ecr.us-east-1.amazonaws.com） 1. 从 Athena 托管账户中拉取映像： ``` docker pull athenaImageURI ``` 1. 向注册表进行 Docker 身份验证： ``` aws ecr get-login-password --region regionID | docker login --username AWS --password-stdin customer-registry ``` 其中 *customer-registry* 是您的 ECR 注册表（例如 account\$1id\$12.dkr.ecr.us-east-1.amazonaws.com） 1. 标记您的存储库拉取的映像： ``` docker tag athenaImageURI yourImageURI ``` 1. 将映像推送到存储库： ``` docker push yourImageURI ``` 1. 更新您的 Athena Federation Connector： 1. 导航至您的 Lambda 函数 1. 选择**部署新映像** 1. 输入新的映像 URI Athena 联合连接器映像现已位于您的账户中，您可以对该映像执行 CVE 扫描。 # 将连接注册为 Glue Data Catalog 创建数据来源后，您可以使用 Athena 控制台将该连接注册为 Glue Data Catalog。注册后，您可以使用 Lake Formation 来管理联合数据目录并启用精细访问控制。有关更多信息，请参阅 [Creating a federated catalog](https://docs.aws.amazon.com/lake-formation/latest/dg/create-fed-catalog-data-source.html)。 您可以注册以下连接器以便与 AWS Glue 集成，从而实现精细访问控制。 + Redshift + BigQuery + DynamoDB（预览版） + Snowflake（预览版） + MySQL + PostgreSQL + AWS CMDB + Timestream + Azure Data Lake 存储 + Azure Synapse + IBM Db2 + IBM Db2 AS/400（Db2 iSeries） + DocumentDB + Google Cloud Storage + HBase + OpenSearch + Oracle + SAP HANA + SQL Server + TPC-DS + Cloudera Hive + CloudWatch + Cloudwatch Metrics + Teradata + Vertica ## 先决条件 在开始之前，您必须完成以下前提条件： + 确保您拥有注册相关位置所需的角色和权限。有关更多信息，请参阅《AWS Lake Formation 开发人员指南》中的 [Requirements for roles](https://docs.aws.amazon.com/lake-formation/latest/dg/registration-role.html)。 + 确保您拥有所需的 Lake Formation 角色。有关更多信息，请参阅《AWS Lake Formation 开发人员指南》中的[将 Data Catalog 连接到外部数据来源的先决条件](https://docs.aws.amazon.com/lake-formation/latest/dg/federated-catalog-data-connection.html)。 + 您在 Glue 中注册的角色必须具有以下示例中列出的权限。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/spill-prefix/*", "arn:aws:s3:::amzn-s3-demo-bucket/spill-prefix" ] }, { "Sid": "lambdainvoke", "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-1:111122223333:function:lambda_function_name" }, { "Sid": "gluepolicy", "Effect": "Allow", "Action": "glue:*", "Resource": [ "arn:aws:glue:us-east-1:111122223333:connection/", "arn:aws:glue:us-east-1:111122223333:catalog" ] } ] } ``` ------ + 您负责确定和管理适当的数据访问权限。在为联合查询使用精细访问控制时，建议您使用 [AmazonAthenaFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html) 托管式策略。如果要使用您自己的策略，则必须确保执行联合查询的用户无权访问以下资源。 + 在 Glue 连接中指定的 Lambda 连接器上的 `lambda:InvokeFunction` + IAM 中的溢写存储桶位置访问权限 + 与联合目录关联的 Glue 连接的访问权限 + IAM 中的 Lake Formation 角色 ## 使用控制台注册连接 **将连接注册为 Glue Data Catalog** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 在导航窗格中，选择**数据来源和目录**。 1. 从**数据来源**列表中，选择您创建的数据来源以打开**数据来源详细信息**页面。 1. 选择 **Get started with AWS Lake Formation (Amazon SES 入门)**。 **注意** 选择此选项后，您必须自行管理您的 Lambda 函数。Athena 将不会删除您的 Lambda 函数。 1. 对于**数据目录名称**，请为您的目录提供一个唯一的名称。 1. 选择向 Lake Formation 授予调用该 Lambda 函数的权限的 **Lake Formation IAM 角色**。确保该角色具有[示例](#register-connection-as-gdc-pre)中显示的权限。 1. 在文本框中，键入**确认**以删除 Athena 数据来源，并将其替换为 Glue Data Catalog 注册。 **注意** 此操作将删除您的 Athena 数据来源，并创建一个新的 Glue Data Catalog 来代替该数据来源。完成此过程后，您可能需要更新访问该数据来源的查询，以改为引用新创建的 Glue Data Catalog。 1. 选择**创建目录并前往 Lake Formation**。这时将打开 Lake Formation 控制台，您可以在其中管理目录并向用户授予对目录、数据库和表的权限。 # 启用跨账户联合查询 联合查询允许您使用部署在 AWS Lambda 上的数据来源连接器查询 Amazon S3 以外的数据来源。跨账户联合查询功能允许 Lambda 函数和要查询的数据来源位于不同的账户中。 **注意** 仅在您尚未将联合数据来源注册到 AWS Glue Data Catalog 时才使用此方法。如果您已将数据来源注册到 AWS Glue Data Catalog，请使用 AWS Glue Data Catalog 跨账户功能和权限模型。有关更多信息，请参阅《AWS Glue 用户指南》中的[授予跨账户访问权限](https://docs.aws.amazon.com/glue/latest/dg/cross-account-access.html)**。 作为数据管理员，您可以通过与数据分析人员的账户共享数据连接器来启用跨账户联合查询。或者作为数据分析人员，可以通过将数据管理员提供的共享 Lambda ARN 添加到您的账户中来启用跨账户联合查询。对原始账户中的连接器进行配置更改时，更新的配置将自动应用于其他用户账户中该连接器的共享实例。 ## 注意事项和限制 + 跨账户联合查询功能适用于非 Hive 元存储数据连接器，该连接器使用基于 Lambda 的数据来源。 + 此功能不适用于 AWS Glue Data Catalog 数据来源类型。有关跨账户访问 AWS Glue Data Catalog 的信息，请参阅 [配置 AWS Glue 数据目录的跨账户存取](security-iam-cross-account-glue-catalog-access.md)。 + 如果来自连接器的 Lambda 函数的响应超过 6MB 的 Lambda 响应大小限制，Athena 会自动对响应进行加密、批处理并溢出到您配置的 Amazon S3 存储桶。运行 Athena 查询的实体必须有权访问溢出位置，Athena 才能读取溢出的数据。我们建议您设置 Amazon S3 生命周期策略，以从溢出位置删除对象，因为查询完成后不需要数据。 + 不支持跨 AWS 区域 使用联合查询。 ## 所需的权限 要设置所需的权限，必须同时在账户 A（*444455556666*）和账户 B（*111122223333*）中执行操作。 ### 账户 A 的操作 若要让数据管理员账户 A 与数据分析人员账户 B 共享 Lambda 函数，账户 B 需要 Lambda 调用函数和溢出存储桶访问权限。因此，账户 A 应该将[基于资源的策略](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)添加到 Lambda 函数并添加[主体](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html)访问 Amazon S3 中其溢出存储桶的权限。 1. 以下策略向账户 A 中的 Lambda 函数授予账户 B 调用 Lambda 函数的权限。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "CrossAccountInvocationStatement", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:user/username" ] }, "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-1:444455556666:function:lambda-function-name" } ] } ``` ------ 1. 以下策略允许溢出存储桶访问账户 B 中的主体。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": ["arn:aws:iam::111122223333:user/username"] }, "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::spill-bucket", "arn:aws:s3:::spill-bucket/*" ] } ] } ``` ------ 1. 如果 Lambda 函数使用 AWS KMS 密钥而不是联合开发工具包提供的默认加密来加密溢出存储桶，则账户 A 中的 AWS KMS 密钥策略必须向账户 B 中的用户授予访问权限，如以下示例所示。 ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": { "AWS": ["arn:aws:iam::account-B-id:user/username"] }, "Action": [ "kms:Decrypt" ], "Resource": "*" // Resource policy that gets placed on the KMS key. } ``` ### 账户 B 的操作 若要让账户 A 与账户 B 共享其连接器，账户 B 必须创建一个名为 `AthenaCrossAccountCreate-account-A-id` 的角色，账户 A 通过调用 AWS Security Token Service [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API 操作担任该角色。 1. 使用 IAM 控制台或 AWS CLI 将 `AthenaCrossAccountCreate-account-A-id` 角色创建为自定义信任策略角色。自定义信任策略可委托访问权限并允许其他人在您的 AWS 账户中执行操作。有关具体步骤，请参阅 *IAM 用户指南*中的[使用自定义信任策略创建角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)。 该信任关系应有一个主体，其中的密钥是是 `AWS`，而值是账户 A 的 ARN，如下例所示。 ``` ... "Principal": { "AWS": ["arn:aws:iam::account-A-id:user/username"] }, ... ``` 1. 同样在账户 B 中，创建允许 `CreateDataCatalog` 操作的如下策略。 ``` { "Effect": "Allow", "Action": "athena:CreateDataCatalog", "Resource": "arn:aws:athena:*:account-B-id:datacatalog/*" } ``` 1. 将允许 `CreateDataCatalog` 操作的策略添加到您使用账户 B 创建的 `AthenaCrossAccountCreate-account-A-id` 角色中。 ## 与账户 B 共享账户 A 中的数据来源 获得相应权限后，您可以使用 Athena 控制台中的**数据来源和目录**页面，与其他账户（账户 B）共享您账户（账户 A）中的数据连接器。账户 A 保留对连接器的完全控制权和所有权。账户 A 对连接器进行配置更改时，已更新的配置将应用于账户 B 中的共享连接器。 **注意** 只能共享 Lambda 类型的数据来源，不能共享使用 AWS Glue 连接的数据来源。有关更多信息，请参阅 [可用数据来源连接器](connectors-available.md)。 **与账户 B 共享账户 A 中的 Lambda 数据来源** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择要共享的连接器的链接。 1. 在 Lambda 数据来源的详细信息页面上，选择右上角的**操作**菜单，然后选择**共享**。 1. 在 **与其他账户共享 *Lambda-name*** 对话框中，输入所需信息。 + 在**数据来源名称**中，输入您要在另一个账户中显示的复制数据来源名称。 + 在**账户 ID** 中，输入要与其共享数据来源的账户 ID（在本例中为账户 B）。 1. 选择**共享**。您指定的共享数据连接器在账户 B 中创建。账户 A 中连接器的配置更改将应用于账户 B 中的连接器。 ## 将共享数据来源从账户 A 添加到账户 B 作为数据分析人员，您可能会从数据管理员那里获得连接器的 ARN 以添加到您的账户中。您可以使用 Athena 控制台的**数据来源和目录**页面，将管理员提供的 Lambda ARN 添加到您的账户中。 **将共享数据连接器的 Lambda ARN 添加到您的账户** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果导航窗格不可见，请选择左侧的扩展菜单。 1. 选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择**创建数据来源**。 1. 在**选择数据来源**页面上，选择**自定义或共享连接器**。 1. 选择**下一步**。 1. 在**输入数据来源详细信息**页面上的**连接详细信息**部分中，对于**选择或输入 Lambda 函数**，输入账户 A 的 Lambda ARN。 1. 选择**下一步**。 1. 在**审核和创建**页面上，选择**创建数据来源**。 ## 问题排查 如果您收到一条错误消息，指出账户 A 没有在账户 B 中担任角色的权限，请确保正确拼写在账户 B 中创建的角色名称，并且附加了适当的策略。 # 更新数据来源连接器 Athena 建议您定期将所用的数据来源连接器更新为最新版本，以利用新功能和增强功能。更新数据来源连接器包括以下步骤： # Glue 连接（推荐） ## 查找 Athena Query Federation 最新版本 Athena 数据来源连接器的最新版本号对应于 Athena Query Federation 最新版本。在某些情况下，GitHub 版本可能比 AWS Serverless Application Repository（SAR）上提供的版本稍微更新一些。 **查找 Athena Query Federation 最新版本号** 1. 访问 GitHub URL [https://github.com/awslabs/aws-athena-query-federation/releases/latest](https://github.com/awslabs/aws-athena-query-federation/releases/latest)。 1. 请注意，主页标题中的版本号格式如下： **Athena Query Federation ****版本 v** *year*.*week\$1of\$1year*.*iteration\$1of\$1week* 例如，**Athena Query Federation 版本 v2023.8.3** 的版本号为 2023.8.3。 ## 查找连接器版本 按照以下步骤确定您当前使用的连接器版本。 **查找连接器版本** 1. 在 Lambda 应用程序的 Lambda 控制台页面中，选择**映像**选项卡。 1. 在“映像”选项卡下，找到“映像 URI”。URI 遵循以下格式： ``` Image_location_account.dkr.ecr.us-west-2.amazonaws.com/athena-federation-repository:Version ``` 1. 映像 URI 中的版本号遵循 `year.week_of_year.iteration_of_week` 格式（例如 `2021.42.1`）。此数字表示连接器版本。 ## 部署新的连接器版本 按照以下步骤部署连接器的新版本。 **部署新的连接器版本** 1. 按照以下步骤查找最新 Athena Query Federation 版本，找到所需的版本。 1. 在联合连接器 Lambda 函数中，找到 ImageURI 并将标签更新为所需的版本。例如： 从： ``` 509399631660.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.15.1 ``` 到： ``` 509399631660.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.26.1 ``` **注意** 如果您的当前版本早于 2025.15.1，请注意以下重要更改： 存储库名称已更新为 `athena-federation-repository` 对于此更新之前的版本，可能无法设置命令覆盖。您必须将其设置为复合处理程序。 # 旧连接 ## 查找 Athena Query Federation 最新版本 Athena 数据来源连接器的最新版本号对应于 Athena Query Federation 最新版本。在某些情况下，GitHub 版本可能比 AWS Serverless Application Repository（SAR）上提供的版本稍微更新一些。 **查找 Athena Query Federation 最新版本号** 1. 访问 GitHub URL [https://github.com/awslabs/aws-athena-query-federation/releases/latest](https://github.com/awslabs/aws-athena-query-federation/releases/latest)。 1. 请注意，主页标题中的版本号格式如下： **Athena Query Federation ****版本 v** *year*.*week\$1of\$1year*.*iteration\$1of\$1week* 例如，**Athena Query Federation 版本 v2023.8.3** 的版本号为 2023.8.3。 ## 查找并记下资源名称 在准备升级时，必须找到并记下以下信息： 1. 连接器的 Lambda 函数名称。 1. Lambda 函数环境变量。 1. Lambda 应用程序名称，用于管理连接器的 Lambda 函数。 **在 Athena 控制台中查找资源名称** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 在导航窗格中，选择**数据来源和目录**。 1. 在**数据来源名称**列中，选择指向连接器数据来源的链接。 1. 在**数据来源详细信息**部分的 **Lambda 函数**下，选择指向您的 Lambda 函数的链接。 ![\[选择指向 Lambda 函数的链接。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-updating-1.png) 1. 在**函数**页面的**函数名称**列中，记下连接器的函数名称。 ![\[记下函数名称。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-updating-2.png) 1. 选择函数名称链接。 1. 在**函数概述**部分下，选择**配置**选项卡。 1. 在左侧窗格中，选择**环境变量**。 1. 在**环境变量**部分中，记下键及其对应的值。 1. 滚动到页面顶部。 1. 在消息**此函数属于应用程序中。单击此处对其进行管理**，选择**单击此处**链接。 1. 在 **serverlessrepo-*your\$1application\$1name*** 页面中，记下不含 **serverlessrepo** 的应用程序名称。例如，如果应用程序名称为 **serverlessrepo-DynamoDbTestApp**，则您的应用程序名称为 **DynamoDbTestApp**。 1. 留在应用程序的 Lambda 控制台页面上，然后继续执行**查找您正在使用的连接器的版本**中的步骤。 ## 查找您正在使用的连接器的版本 按照以下步骤查找您正在使用的连接器的版本 **查找您正在使用的连接器的版本** 1. 在 Lambda 应用程序的 Lambda 控制台页面中，选择**部署**选项卡。 1. 在**部署**选项卡中，展开 **SAM 模板**。 1. 搜索 **CodeUri**。 1. 在 **CodeUri** 下的**键**字段中，查找以下字符串： ``` applications-connector_name-versions-year.week_of_year.iteration_of_week/hash_number ``` 以下示例显示了适用于 CloudWatch 连接器的字符串： ``` applications-AthenaCloudwatchConnector-versions-2021.42.1/15151159... ``` 1. 记录 *year*.*week\$1of\$1year*.*iteration\$1of\$1week* 的值（例如，**2021.42.1**）。这是您的连接器的版本。 ## 部署连接器的新版本 按照以下步骤部署连接器的新版本。 **部署连接器的新版本** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 在导航窗格中，选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择**创建数据来源**。 1. 选择要升级的数据来源，然后选择**下一步**。 1. 在**连接详细信息**部分中，选择**创建 Lambda 函数**。这将打开 Lambda 控制台，可在其中部署更新后的应用程序。 ![\[AWS Lambda 控制台中的“连接器”页面。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-updating-3.png) 1. 由于您实际上并不是在新建数据来源，因此可以关闭 Athena 控制台选项卡。 1. 在连接器的 Lambda 控制台页面中，执行以下步骤： 1. 确保已从应用程序名称中移除了 **serverlessrepo-** 前缀，然后将应用程序名称复制到**应用程序名称**字段。 1. 将您的 Lambda 函数名称复制到 **AthenaCatalogName** 字段。在某些连接器中，此字段名为 **LambdaFunctionName**。 1. 将您记录的环境变量复制到其相应的字段中。 1. 选择选项**我确认此应用程序创建自定义 IAM 角色和资源策略**，然后选择**部署**。 1. 要验证您的应用程序是否已更新，选择**部署**选项卡。 **部署历史记录**部分显示您的更新已完成。 ![\[连接器更新已完成。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connectors-updating-4.png) 1. 要确认新版本号，您可以像以前一样展开 **SAM 模板**，找到 **CodeUri**，然后在**键**字段中检查连接器版本号。 现在，您可以使用更新后的连接器创建 Athena 联合查询。 # 编辑或删除数据来源连接 您可以使用 Athena 控制台更新现有连接的描述、主机、端口、数据库和其他属性。您还可以通过 Athena 控制台删除数据来源。 ## 编辑数据来源连接 **编辑数据来源连接** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 在导航窗格中，选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择要编辑的数据来源连接。 1. 对于 **AWS Glue 连接详细信息**，请选择**编辑**。 1. 选择**下一步**。 1. 在**编辑 ** 页面上，根据需要更新信息。可用属性取决于连接类型。 **注意** 在更新密钥、溢写位置或 AWS KMS 密钥 ID 等的连接属性后，请确保 Lambda 执行角色仍然有权访问更新后的资源。有关更多信息，请参阅《AWS Lambda 开发人员指南》中的[查看和更新​​执行角色中的权限](https://docs.aws.amazon.com/lambda/latest/dg/permissions-executionrole-update.html)。 + **描述** – 编辑连接的描述。 + **主机** – 编辑数据库的主机名。 + **端口** – 编辑数据库的端口号。 + **数据库** – 编辑数据库的名称。 + **JDBC 参数** – 编辑连接所必需的任何其他 JDBC 参数。 + **密钥** – 选择或从 AWS Secrets Manager 中创建一个密钥。使用 AWS 密钥可避免将敏感信息硬编入 JDBC 连接字符串中。有关更多信息，请参阅[什么是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 有关在 Secrets Manager 中创建密钥的信息，请参阅在《AWS Secrets Manager 用户指南》中的 [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)**。 要将 Athena 联合查询功能与 AWS Secrets Manager 结合使用，您必须为 Secrets Manager 配置一个 Amazon VPC 私有端点。有关更多信息，请参阅《AWS Secrets Manager 用户指南**》中的 [创建 Secrets Manager VPC 私有端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)。 + **Amazon S3 中的溢写位置** – 选择或在您的账户中创建一个 Amazon S3 存储桶位置，以用于存储超出 Lambda 函数响应大小限制的数据。 **注意** 溢出的数据不会在后续的执行中重复使用，并且可以在 12 小时后安全地删除。Athena 不会为您删除这些数据。要管理这些对象，请考虑添加一个将从 Amazon S3 溢出存储桶中删除旧数据的对象生命周期策略。有关更多信息，请参阅《Amazon S3 用户指南》**中的[对象生命周期管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)。 + **在 S3 中对查询结果进行加密** – 选择以下选项之一： + （默认）**使用随机生成的密钥** – 溢写到 Amazon S3 的数据将使用经过 AES-GCM 身份验证的加密模式和随机生成的密钥进行加密。 + **使用 AWS KMS 密钥** – 选择或创建一个更强的由 AWS KMS 生成的加密密钥。有关更多信息，请参阅 *AWS Key Management Service 开发人员指南*中的[创建密钥](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。 + **关闭** – 不要加密溢写数据。 + **联网设置** – 某些连接需要使用虚拟私有云（VPC）。选择或创建包含您要访问的数据存储、一个子网和一个或多个安全组的 VPC。有关更多信息，请参阅 [为数据来源连接器或 AWS Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。 **注意** 在更新密钥、溢写位置或 AWS KMS 密钥 ID 等资源的连接属性后，请确保 Lambda 执行角色继续有权访问更新后的资源。 更新连接的网络设置后，请务必使用相同的设置更新 Lambda 函数，以确保您的连接与数据来源兼容。 有关其他连接属性的信息，请参阅《AWS Glue 用户指南》中的 [AWS Glue 连接属性](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)**或《Amazon Athena 用户指南》中的[可用数据来源连接器](connectors-available.md)**。 1. 选择**保存**。 在数据来源的此页面中，**AWS Glue 连接详细信息**部分显示了更新后的连接器信息。 ## 删除数据来源 删除某个数据来源时，系统只会删除 Athena 数据来源，而不会删除 Glue 连接、IAM 执行角色和 Lambda 函数等资源。 **删除数据来源** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 在导航窗格中，选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择要删除的数据来源。 1. 选择**删除**。 1. 在**删除数据来源**页面上，键入*确认*以确认删除，然后选择**删除**。数据来源的删除可能需要一段时间才能完成。删除数据来源后，您将收到操作成功的提醒。 # 运行联合查询 配置一个或多个数据连接器并将其部署到您的账户之后，您可以在 Athena 查询中进行使用。 ## 查询单个数据来源 本节中的示例假定您已配置 [Amazon Athena CloudWatch 连接器](connectors-cloudwatch.md) 并将其部署到您的账户。使用其他连接器时，使用相同的方法进行查询。 **创建使用 CloudWatch 连接器的 Athena 查询** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 在 Athena 查询编辑器中，创建在 `FROM` 子句中使用以下语法的 SQL 查询。 ``` MyCloudwatchCatalog.database_name.table_name ``` ### 示例 以下示例使用 Athena CloudWatch 连接器连接到 `/var/ecommerce-engine/order-processor` CloudWatch Logs [日志组](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)中的 `all_log_streams` 视图。`all_log_streams` 视图是日志组中所有日志流的视图。示例查询将返回的行数限制为 100。 ``` SELECT * FROM "MyCloudwatchCatalog"."/var/ecommerce-engine/order-processor".all_log_streams LIMIT 100; ``` 以下示例解析与上一示例相同的视图中的信息。该示例提取顺序 ID 和日志级别，并筛选出所有 `INFO` 级别的消息。 ``` SELECT log_stream as ec2_instance, Regexp_extract(message '.*orderId=(\d+) .*', 1) AS orderId, message AS order_processor_log, Regexp_extract(message, '(.*):.*', 1) AS log_level FROM MyCloudwatchCatalog."/var/ecommerce-engine/order-processor".all_log_streams WHERE Regexp_extract(message, '(.*):.*', 1) != 'INFO' ``` ## 查询多个数据来源 举一个更复杂的例子，假设一家电子商务公司使用以下数据来源存储与客户购买相关的数据： + [Amazon RDS for MySQL](https://aws.amazon.com/rds/mysql/)，用于存储产品目录数据 + [Amazon DocumentDB](https://aws.amazon.com/documentdb/)，用于存储客户账户数据，例如电子邮件和配送地址 + [Amazon DynamoDB](https://aws.amazon.com/dynamodb/)，用于存储订单发货和追踪数据 假设该电子商务应用程序的数据分析师了解到，某些地区的送货时间受到当地天气状况的影响。分析师希望了解延迟送货的订单数量、受影响客户所在位置以及受影响最大的产品。分析师没有单独调查信息来源，而是使用 Athena 将数据联接到单个联合查询中。 **Example** ``` SELECT t2.product_name AS product, t2.product_category AS category, t3.customer_region AS region, count(t1.order_id) AS impacted_orders FROM my_dynamodb.default.orders t1 JOIN my_mysql.products.catalog t2 ON t1.product_id = t2.product_id JOIN my_documentdb.default.customers t3 ON t1.customer_id = t3.customer_id WHERE t1.order_status = 'PENDING' AND t1.order_date between '2022-01-01' AND '2022-01-05' GROUP BY 1, 2, 3 ORDER BY 4 DESC ``` ## 查询联合视图 查询联合源时，可以使用视图对底层数据来源进行模糊处理，或者隐藏来自查询数据的其他分析师的复杂联接。 ### 注意事项和限制 + 联合视图需要 Athena 引擎版本 3。 + 联合视图存储在 AWS Glue 中，而不是底层数据来源中。 + [注册为 Glue 数据目录](register-connection-as-gdc.md)的数据来源不支持联合视图。 + 使用联合目录创建的视图必须使用完全限定名称语法，如以下示例所示： ``` "ddbcatalog"."default"."customers" ``` + 在联合源上运行查询的用户必须有权查询联合源。 + 联合视图需要 `athena:GetDataCatalog` 权限。有关更多信息，请参阅 [允许访问 Athena 联合查询：示例策略](federated-query-iam-access.md)。 ### 示例 以下示例针对存储在联合数据来源中的数据创建了一个名为 `customers` 的视图。 **Example** ``` CREATE VIEW customers AS SELECT * FROM my_federated_source.default.table ``` 以下示例查询显示了一个引用 `customers` 视图而不是底层联合数据来源的查询。 **Example** ``` SELECT id, SUM(order_amount) FROM customers GROUP by 1 ORDER by 2 DESC LIMIT 50 ``` 以下示例创建了一个名为 `order_summary` 的视图，该视图合并了来自联合数据来源和 Amazon S3 数据来源的数据。在已在 Athena 中创建的联合源中，视图使用 `person` 和 `profile` 表。在 Amazon S3 中，视图使用 `purchase` 和 `payment` 表。为了引用 Amazon S3，语句使用了关键字 `awsdatacatalog`。请注意，联合数据来源使用完全限定名称语法 *federated\$1source\$1name*.*federated\$1source\$1database*.*federated\$1source\$1table*。 **Example** ``` CREATE VIEW default.order_summary AS SELECT * FROM federated_source_name.federated_source_database."person" p JOIN federated_source_name.federated_source_database."profile" pr ON pr.id = p.id JOIN awsdatacatalog.default.purchase i ON p.id = i.id JOIN awsdatacatalog.default.payment pay ON pay.id = p.id ``` ### 其他资源 + 有关与其原始源分离且适用于多用户模型中的按需分析的联合视图示例，请参阅 *AWS 大数据博客*中的[使用 Amazon Athena 和联合视图扩展数据网格](https://aws.amazon.com/blogs/big-data/extend-your-data-mesh-with-amazon-athena-and-federated-views/)。 + 有关在 Athena 中使用视图的更多信息，请参阅 [使用视图](views.md)。 # 使用联合传递查询 在 Athena 中，可以使用数据来源本身的查询语言对联合数据来源运行查询，并将完整查询下推到数据来源来执行查询。这些查询称为传递查询。要运行传递查询，可以在 Athena 查询中使用表函数。您可以将要在数据来源上运行的传递查询包含在表函数的其中一个参数中。传递查询会返回一个表，该表可以使用 Athena SQL 进行分析。 ## 支持的连接器 以下 Athena 数据来源连接器支持传递查询。 + [Azure Data Lake 存储](connectors-adls-gen2.md) + [Azure Synapse](connectors-azure-synapse.md) + [Cloudera Hive](connectors-cloudera-hive.md) + [Cloudera Impala](connectors-cloudera-impala.md) + [CloudWatch](connectors-cloudwatch.md) + [Db2](connectors-ibm-db2.md) + [Db2 iSeries](connectors-ibm-db2-as400.md) + [DocumentDB](connectors-docdb.md) + [DynamoDB](connectors-dynamodb.md) + [HBase](connectors-hbase.md) + [Google BigQuery](connectors-bigquery.md) + [Hortonworks](connectors-hortonworks.md) + [MySQL](connectors-mysql.md) + [Neptune](connectors-neptune.md) + [OpenSearch](connectors-opensearch.md) + [Oracle](connectors-oracle.md) + [PostgreSQL](connectors-postgresql.md) + [Redshift](connectors-redshift.md) + [SAP HANA](connectors-sap-hana.md) + [Snowflake](connectors-snowflake.md) + [SQL Server](connectors-microsoft-sql-server.md) + [Teradata](connectors-teradata.md) + [Timestream](connectors-timestream.md) + [Vertica](connectors-vertica.md) ## 注意事项和限制 在 Athena 中使用传递查询时，请注意以下几点： + 只有 Athena `SELECT` 语句或读取操作才支持查询传递。 + 查询性能可能因数据来源的配置而异。 + 查询传递功能不支持 Lake Formation 精细访问控制。 + [注册为 Glue 数据目录](register-connection-as-gdc.md)的数据来源不支持传递查询。 ## 语法 常规 Athena 查询传递语法如下所示： ``` SELECT * FROM TABLE(catalog.system.function_name(arg1 => 'arg1Value'[, arg2 => 'arg2Value', ...])) ``` 请注意以下几点： + **目录**：目标 Athena 联合连接器名称或数据目录名称。 + **系统**：包含函数的命名空间。所有 Athena 连接器实施均使用此命名空间。 + **function\$1name**：将传递查询向下推送到数据来源的函数名称。这通常称为 `query`。`catalog.system.function_name` 组合是该函数的完整解析路径。 + **arg1 和 arg2 等参数**：函数参数。用户必须将这些参数传递到函数。在大多数情况下，这是向下传递到数据来源的查询字符串。 对于大多数数据来源，第一个也是唯一的参数为 `query`，后跟箭头运算符 `=>` 和查询字符串。 ``` SELECT * FROM TABLE(catalog.system.query(query => 'query string')) ``` 为简单起见，可选的命名参数 `query` 和箭头运算符 `=>` 均可省略。 ``` SELECT * FROM TABLE(catalog.system.query('query string')) ``` 如果查询在目标目录的上下文中运行，则可以通过删除 `catalog` 名称来进一步简化查询。 ``` SELECT * FROM TABLE(system.query('query string')) ``` 如果数据来源需要的不仅仅是查询字符串，请按照数据来源所需的顺序使用命名参数。例如，表达式 `arg1 => 'arg1Value'` 包含第一个参数及其值。*arg1* 名称与数据来源相关，可能因连接器而异。 ``` SELECT * FROM TABLE( system.query( arg1 => 'arg1Value', arg2 => 'arg2Value', arg3 => 'arg3Value' )); ``` 也可以通过省略参数名称来简化上述步骤。但是，您必须遵循方法签名的顺序。有关函数签名的更多信息，请参阅每个连接器的文档。 ``` SELECT * FROM TABLE(catalog.system.query('arg1Value', 'arg2Value', 'arg3Value')) ``` 如下例所示，您可以使用完整的函数解析路径，跨不同 Athena 连接器运行多个传递查询。 ``` SELECT c_customer_sk FROM TABLE (postgresql.system.query('select * from customer limit 10')) UNION SELECT c_customer_sk FROM TABLE(dynamodb.system.query('select * from customer')) LIMIT 10 ``` 您可以将传递查询作为联合视图的一部分使用。相同限制适用。有关更多信息，请参阅[查询联合视图](https://docs.aws.amazon.com/athena/latest/ug/running-federated-queries.html#running-federated-queries-federated-views)。 ``` CREATE VIEW catalog.database.ViewName AS SELECT * FROM TABLE ( catalog.system.query('query') ) ``` 有关用于特定连接器的确切语法的信息，请参阅相应连接器的文档。 ### 引号用法 必须用单引号将参数值（包含传递的查询字符串）括起来，如下例所示： ``` SELECT * FROM TABLE(system.query(query => 'SELECT * FROM testdb.persons LIMIT 10')) ``` 如果使用双引号将查询字符串括起来，查询会失败。以下查询失败，显示错误消息：COLUMN\$1NOT\$1FOUND: line 1:43: Column 'select \$1 from testdb.persons limit 10' cannot be resolved。 ``` SELECT * FROM TABLE(system.query(query => "SELECT * FROM testdb.persons LIMIT 10")) ``` 要转义单引号，请在原始单引号中添加单引号（例如由 `terry's_group` 变为 `terry''s_group`）。 ## 示例 以下示例查询将查询下推到数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。 ``` SELECT * FROM TABLE( catalog.system.query( query => 'SELECT * FROM customer LIMIT 10;' )) ``` 以下语句运行相同的查询，但删除了可选的命名参数 `query` 和箭头运算符 `=>`。 ``` SELECT * FROM TABLE( catalog.system.query( 'SELECT * FROM customer LIMIT 10;' )) ``` 为了便于重复使用，也可以将其封装在联合视图中。当与视图结合使用时，必须使用完整的函数解析路径。 ``` CREATE VIEW AwsDataCatalog.default.example_view AS SELECT * FROM TABLE ( catalog.system.query('SELECT * FROM customer LIMIT 10;') ) ``` ## 选择退出查询传递 要禁用传递查询，请添加名为 `enable_query_passthrough` 的 Lambda 环境变量并将其设置为 `false`。 # 了解联合表名限定词 Athena 使用以下术语来指代数据对象的层次结构： + **数据来源** - 一组数据库 + **数据库** - 一组表 + **表** - 按一组行或列组织的数据 有时，这些对象也会用替代但等效的名称来指代，如下所示： + 数据来源有时也称为目录。 + 数据库有时也称为架构。 ## 联合数据来源中的术语 在查询联合数据来源时，请注意，底层数据来源使用的术语可能与 Athena 不同。在编写联合查询时，请记住这一区别。以下各节介绍了 Athena 中的数据对象术语与联合数据来源中的数据对象术语的对应关系。 ### Amazon Redshift Amazon Redshift *数据库*是一组 Redshift *架构*，其中包含一组 Redshift *表*。 **** | Athena | Redshift | | --- | --- | | Redshift 数据来源 | 配置为指向 Redshift database 的 Redshift 连接器 Lambda 函数。 | | data\$1source.database.table | database.schema.table | 示例查询 ``` SELECT * FROM Athena_Redshift_connector_data_source.Redshift_schema_name.Redshift_table_name ``` 有关此连接器的更多信息，请参阅 [Amazon Athena Redshift 连接器](connectors-redshift.md)。 ### Cloudera Hive Cloudera Hive *服务器*或*集群*是一组 Cloudera Hive *数据库*，其中包含一组 Cloudera Hive *表*。 **** | Athena | Hive | | --- | --- | | Cloudera Hive 数据来源 | Cloudera Hive 连接器 Lambda 函数配置为指向 Cloudera Hive server。 | | data\$1source.database.table | server.database.table | 示例查询 ``` SELECT * FROM Athena_Cloudera_Hive_connector_data_source.Cloudera_Hive_database_name.Cloudera_Hive_table_name ``` 有关此连接器的更多信息，请参阅 [Amazon Athena Cloudera Hive 连接器](connectors-cloudera-hive.md)。 ### Cloudera Impala Impala *服务器*或*集群*是一组 Impala *数据库*，其中包含一组 Impala *表*。 **** | Athena | Impala | | --- | --- | | Impala 数据来源 | Impala 连接器 Lambda 函数配置为指向 Impala server。 | | data\$1source.database.table | server.database.table | 示例查询 ``` SELECT * FROM Athena_Impala_connector_data_source.Impala_database_name.Impala_table_name ``` 有关此连接器的更多信息，请参阅 [Amazon Athena Cloudera Impala 连接器](connectors-cloudera-impala.md)。 ### MySQL MySQL *服务器*是一组 MySQL *数据库*，其中包含一组 MySQL *表*。 **** | Athena | MySQL | | --- | --- | | MySQL 数据来源 | MySQL 连接器 Lambda 函数配置为指向 MySQL server。 | | data\$1source.database.table | server.database.table | 示例查询 ``` SELECT * FROM Athena_MySQL_connector_data source.MySQL_database_name.MySQL_table_name ``` 有关此连接器的更多信息，请参阅 [Amazon Athena MySQL 连接器](connectors-mysql.md)。 ### Oracle Oracle *服务器*（或*数据库*）是一组 Oracle *架构，*其中包含一组 Oracle *表*。 **** | Athena | Oracle | | --- | --- | | Oracle 数据来源 | Oracle 连接器 Lambda 函数配置为指向 Oracle server。 | | data\$1source.database.table | server.schema.table | 示例查询 ``` SELECT * FROM Athena_Oracle_connector_data_source.Oracle_schema_name.Oracle_table_name ``` 有关此连接器的更多信息，请参阅 [Amazon Athena Oracle 连接器](connectors-oracle.md)。 ### Postgres Postgres *服务器*（或*集群*）是一组 Postgres *数据库*。Postgres *数据库*是一组 Postgres *架构*，其中包含一组 Postgres *表*。 **** | Athena | Postgres | | --- | --- | | Postgres 数据来源 | Postgres 连接器 Lambda 函数配置为指向 Postgres server 和 database。 | | data\$1source.database.table | server.database.schema.table | 示例查询 ``` SELECT * FROM Athena_Postgres_connector_data_source.Postgres_schema_name.Postgres_table_name ``` 有关此连接器的更多信息，请参阅 [Amazon Athena PostgreSQL 连接器](connectors-postgresql.md)。 # 使用 Athena Query Federation SDK 编写数据来源连接器 要编写自己的数据来源连接器，您可以使用 [Athena Query Federation SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk)。Athena Query Federation SDK 定义了一组接口和网络协议，使用它们让 Athena 可以将其查询执行计划的一部分委派给您编写和部署的代码。SDK 包括一个连接器套件和一个示例连接器。 自定义连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。 您还可以自定义 Amazon Athena 的[预构建连接器](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors)供您自己使用。您可以修改来自 GitHub 的源代码的副本，然后使用[连接器发布工具](https://github.com/awslabs/aws-athena-query-federation/wiki/Connector_Publish_Tool)创建您自己的 AWS Serverless Application Repository 软件包。以这种方式部署连接器后，您可以在 Athena 查询中使用它。 有关如何下载软件开发工具包的信息和编写自己的连接器的详细说明，请参阅 GitHub 上的 [Example Athena connector](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-example)。 # 使用适用于 Apache Spark 的数据来源连接器 某些 Athena 数据来源连接器可用作 Spark DSV2 连接器。Spark DSV2 连接器名称带有 `-dsv2` 后缀（例如 `athena-dynamodb-dsv2`）。 下面是当前可用的 DSV2 连接器、其 Spark `.format()` 类名称以及指向其相应的 Amazon Athena 联合查询文档的链接： | DSV2 连接器 | Spark .format() 类名称 | 文档 | | --- | --- | --- | | athena-cloudwatch-dsv2 | com.amazonaws.athena.connectors.dsv2.cloudwatch.CloudwatchTableProvider | [CloudWatch](connectors-cloudwatch.md) | | athena-cloudwatch-metrics-dsv2 | com.amazonaws.athena.connectors.dsv2.cloudwatch.metrics.CloudwatchMetricsTableProvider | [CloudWatch 指标](connectors-cwmetrics.md) | | athena-aws-cmdb-dsv2 | com.amazonaws.athena.connectors.dsv2.aws.cmdb.AwsCmdbTableProvider | [CMDB](connectors-cmdb.md) | | athena-dynamodb-dsv2 | com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider | [DynamoDB](connectors-dynamodb.md) | 要下载 DSV2 连接器的 `.jar` 文件，请访问 [Amazon Athena Query Federation DSV2](https://github.com/awslabs/aws-athena-query-federation-dsv2) GitHub 页面并查看**发布版本**、**发布版本* ***、**资产**部分。 ## 为 Spark 指定 jar 要将 Athena DSV2 连接器与 Spark 配合使用，将连接器的 `.jar` 文件提交到您正在使用的 Spark 环境。以下几节介绍了具体的情况。 ### Athena for Spark 有关向 Amazon Athena for Apache Spark 添加自定义 `.jar` 文件和自定义配置的信息，请参阅 [使用 Spark 属性指定自定义配置](notebooks-spark-custom-jar-cfg.md)。 ### 常规 Spark 要将连接器 `.jar` 文件传递给 Spark，使用 `spark-submit` 命令并在 `--jars` 选项中指定 `.jar` 文件，如以下示例所示： ``` spark-submit \ --deploy-mode cluster \ --jars https://github.com/awslabs/aws-athena-query-federation-dsv2/releases/download/some_version/athena-dynamodb-dsv2-some_version.jar ``` ### Amazon EMR Spark 要在 Amazon EMR 上运行包含 `--jars` 参数的 `spark-submit` 命令，必须向 Amazon EMR Spark 集群添加一个步骤。有关如何在 Amazon EMR 上使用 `spark-submit` 的详细信息，请参阅《*Amazon EMR 版本指南*》中的[添加 Spark 步骤](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-spark-submit-step.html)。 ### AWS Glue ETL Spark 对于 AWS Glue ETL，可以将 `.jar` 文件的 GitHub.com URL 传递到 `aws glue start-job-run` 命令的 `--extra-jars` 参数。AWS Glue 文档将 `--extra-jars` 参数描述为采用 Amazon S3 路径，但该参数也可以采用 HTTPS URL。有关更多信息，请参阅《*AWS Glue 开发人员指南*》中的[作业参数参考](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html#w5aac32c13c11)。 ## 在 Spark 上查询连接器 要在 Apache Spark 上提交现有 Athena 联合查询的等效项，使用 `spark.sql()` 函数。例如，假设您拥有以下要在 Apache Spark 上使用的 Athena 查询。 ``` SELECT somecola, somecolb, somecolc FROM ddb_datasource.some_schema_or_glue_database.some_ddb_or_glue_table WHERE somecola > 1 ``` 要使用 Amazon Athena DynamoDB DSV2 连接器在 Spark 上执行相同的查询，使用以下代码： ``` dynamoDf = (spark.read .option("athena.connectors.schema", "some_schema_or_glue_database") .option("athena.connectors.table", "some_ddb_or_glue_table") .format("com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider") .load()) dynamoDf.createOrReplaceTempView("ddb_spark_table") spark.sql(''' SELECT somecola, somecolb, somecolc FROM ddb_spark_table WHERE somecola > 1 ''') ``` ## 指定 参数 Athena 数据来源连接器的 DSV2 版本使用与相应的 Athena 数据来源连接器相同的参数。有关参数信息，请参阅相应的 Athena 数据来源连接器的文档。 在 Pyspark 代码中，使用以下语法配置参数。 ``` spark.read.option("athena.connectors.conf.parameter", "value") ``` 例如，以下代码将 Amazon Athena DynamoDB 连接器 `disable_projection_and_casing` 参数设置为 `always`。 ``` dynamoDf = (spark.read .option("athena.connectors.schema", "some_schema_or_glue_database") .option("athena.connectors.table", "some_ddb_or_glue_table") .option("athena.connectors.conf.disable_projection_and_casing", "always") .format("com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider") .load()) ``` # 在 Athena 中使用 Amazon DataZone 您可以使用 [Amazon DataZone](https://aws.amazon.com/datazone) 跨组织边界大规模共享、搜索和发现数据。DataZone 简化了您在 Athena、AWS Glue 和 AWS Lake Formation 等 AWS 分析服务中的体验。例如，如果您在不同的数据来源中有 PB 级数据，则可使用 Amazon DataZone 根据人员、数据和工具分组构建业务用例。有关更多信息，请参阅 [What is Amazon DataZone？](https://docs.aws.amazon.com/datazone/latest/userguide/what-is-datazone.html)。 在 Athena 中，您可以使用查询编辑器来访问和查询 DataZone 环境。DataZone 环境指定了 DataZone 项目和域的组合。从 Athena 控制台使用 DataZone 环境时，您将代入 DataZone 环境的 IAM 角色，并且只能看到属于该环境的数据库和表。权限由您在 DataZone 中指定的角色决定。 在 Athena 中，您可以使用查询编辑器页面上的 **DataZone 环境**选择器来选择 DataZone 环境。 **在 Athena 中打开 DataZone 环境** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 在 Athena 控制台右上角的**工作组**旁边，选择 **DataZone 环境**。 **注意** 只有 DataZone 中有一个或多个可用域时，才会出现 **DataZone 环境**选项。 ![\[选择 DataZone 环境。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/datazone-using-1.png) 1. 使用 **DataZone 环境**选择器选择一个 DataZone 环境。 ![\[选择一个 DataZone 环境\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/datazone-using-2.png) 1. 在**切换到 DataZone 环境**对话框中，确认该环境是您想要的环境，然后选择**切换到 DataZone 环境**。 ![\[确认对 DataZone 环境所作的更改。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/datazone-using-3.png) 有关开始使用 DataZone 和 Athena 的更多信息，请参阅《Amazon DataZone User Guide》**中的 [Getting started](https://docs.aws.amazon.com/datazone/latest/userguide/getting-started.html) 教程。 # 使用外部 Hive 元存储 您可以使用外部 Hive 元存储的 Amazon Athena 数据连接器来查询 Amazon S3 中使用 Apache Hive 元存储的数据集。无需将元数据迁移到 AWS Glue Data Catalog。在 Athena 管理控制台中，配置 Lambda 函数以与私有 VPC 中的 Hive 元存储进行通信，然后将它连接到元存储。从 Lambda 到 Hive 元存储的连接由私有 Amazon VPC 通道提供保护，并且不使用公共 Internet。您可以提供您自己的 Lambda 函数代码，也可以使用外部 Hive 元存储的 Athena 数据连接器的默认实施。 **Topics** + [功能概览](#connect-to-a-data-source-hive-features) + [工作流](#connect-to-data-source-hive-workflow) + [注意事项和限制](#connect-to-a-data-source-hive-considerations) + [将 Athena 连接到 Apache Hive 元存储](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md) + [使用 AWS Serverless Application Repository 部署 Hive 数据来源连接器](connect-data-source-sar-hive.md) + [使用现有 IAM 执行角色将 Athena 连接到 Hive 元存储](connect-data-source-hive-existing-iam-role.md) + [配置 Athena 使用部署的 Hive 元存储连接器](connect-data-source-hive-existing-lambda.md) + [省略外部 Hive 元存储查询中的目录名称](datastores-hive-default-catalog.md) + [使用 Hive 视图](hive-views.md) + [将 AWS CLI 与 Hive 元存储结合使用](datastores-hive-cli.md) + [修改 Athena 外部 Hive 元存储连接器](datastores-hive-reference-implementation.md) ## 功能概览 利用外部 Hive 元存储的 Athena 数据连接器，您可以执行以下任务： + 使用 Athena 控制台注册自定义目录并使用这些目录运行查询。 + 为不同的外部 Hive 元存储定义 Lambda 函数，并在 Athena 查询中联接它们。 + 在同一 Athena 查询中使用 AWS Glue Data Catalog 和您的外部 Hive 元数据仓。 + 在查询执行上下文中指定目录作为当前默认目录。这样一来，便无需在查询中将目录名称置于数据库名称的前面。您可以使用 `database.table`，而不是使用语法 `catalog.database.table`。 + 使用各种工具运行引用外部 Hive 元存储的查询。您可以使用 Athena 控制台、AWS CLI、AWS 软件开发工具包以及更新的 Athena JDBC 和 ODBC 驱动程序。更新后的驱动程序支持自定义目录。 ### API 支持 适用于外部 Hive 元数据仓的 Athena 数据连接器包含对目录注册 API 操作和元数据 API 操作的支持。 + **目录注册** – 为外部 Hive 元数据仓和[联合数据源](federated-queries.md)注册自定义目录。 + **元数据** – 使用元数据 API 为 AWS Glue 和任何注册到 Athena 目录提供数据库和表信息。 + **Athena JAVA 软件开发工具包客户端** – 在更新后的 Athena JAVA 软件开发工具包客户端上的 `StartQueryExecution` 操作中使用目录注册 API、元数据 API 并支持目录。 ### 参考实现 Athena 提供连接到外部 Hive 元存储的 Lambda 函数的参考实施。参考实现在 GitHub 上作为 [Athena Hive 元存储](https://github.com/awslabs/aws-athena-hive-metastore)的开源项目提供。 参考实施在 AWS Serverless Application Repository (SAR) 中作为以下两种 AWS SAM 应用程序提供。您可以在 SAR 中使用这两种应用程序之一来创建您自己的 Lambda 函数。 + `AthenaHiveMetastoreFunction` – Uber Lambda 函数 `.jar` 文件。“uber”JAR（也称为 fat JAR 或具有依赖关系的 JAR）是 `.jar` 文件，该文件在单个文件中同时包含 Java 程序及其依赖关系。 + `AthenaHiveMetastoreFunctionWithLayer` – Lambda 层和 thin Lambda 函数 `.jar` 文件。 ## 工作流 下图说明了 Athena 如何与外部 Hive 元数据仓进行交互。 ![\[Athena 如何与外部 Hive 元数据仓进行交互。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connect-to-data-source-hive-workflow.png) 在此工作流程中，您的数据库连接的 Hive 元存储位于您的 VPC 中。您使用 Hive Server2 通过 Hive CLI 管理 Hive 元存储。 使用来自 Athena 的外部 Hive 元数据仓的工作流程包括以下步骤。 1. 创建一个 Lambda 函数以将 Athena 连接到 VPC 中的 Hive 元数据仓。 1. 为 Hive 元存储注册唯一目录名称，并在账户中注册相应的函数名称。 1. 当您运行使用目录名称的 Athena DML 或 DDL 查询时，Athena 查询引擎将调用与目录名称关联的 Lambda 函数名称。 1. 使用 AWS PrivateLink，Lambda 函数与 VPC 中的外部 Hive 元数据仓进行通信，并接收对元数据请求的响应。Athena 使用外部 Hive 元数据仓中的元数据，就像使用默认 AWS Glue Data Catalog 中的元数据一样。 ## 注意事项和限制 在为外部 Hive 元数据仓使用 Athena 数据连接器时，请考虑以下几点： + 您可以使用 CTAS 在外部 Hive 元存储上创建表。 + 您可以使用 INSERT INTO 将数据插入到外部 Hive 元存储中。 + 对外部 Hive 元数据仓的 DDL 支持仅限于以下语句。 + ALTER DATABASE SET DBPROPERTIES + ALTER TABLE ADD COLUMNS + ALTER TABLE ADD PARTITION + ALTER TABLE DROP PARTITION + ALTER TABLE RENAME PARTITION + ALTER TABLE REPLACE COLUMNS + ALTER TABLE SET LOCATION + ALTER TABLE SET TBLPROPERTIES + CREATE DATABASE + CREATE TABLE + CREATE TABLE AS + DESCRIBE TABLE + DROP DATABASE + DROP TABLE + SHOW COLUMNS + SHOW CREATE TABLE + SHOW PARTITIONS + SHOW SCHEMAS + SHOW TABLES + SHOW TBLPROPERTIES + 您可以拥有的已注册目录的最大数量为 1000。 + 无法对 Hive 元存储进行 Kerberos 身份验证。 + 若要将 JDBC 驱动程序与外部 Hive 元数据仓或[联合查询](federated-queries.md)结合使用，请在 JDBC 连接字符串中包含 `MetadataRetrievalMethod=ProxyAPI`。有关 JDBC 驱动程序的信息，请参阅 [通过 JDBC 连接到 Amazon Athena](connect-with-jdbc.md)。 + Hive 隐藏列 `$path`、`$bucket`、`$file_size`、`$file_modified_time`、`$partition`、`$row_id` 不能用于精细访问控制筛选。 + Hive 的隐藏系统表，例如 `example_table$partitions` 或 `example_table$properties`，不支持精细访问控制。 ### 权限 预构建和自定义数据连接器可能需要访问以下资源才能正常工作。检查您使用的连接器的信息，以确保您已正确配置 VPC。有关在 Athena 中运行查询和创建数据源连接器所需的 IAM 权限的信息，请参阅 [允许访问适用于外部配置 Hive 元存储的 Athena 数据连接器](hive-metastore-iam-access.md) 和 [允许 Lambda 函数访问外部 Hive 元存储](hive-metastore-iam-access-lambda.md)。 + **Amazon S3** – 除了将查询结果写入 Amazon S3 中的 Athena 查询结果位置之外，数据连接器还会写入到 Amazon S3 中的溢出存储桶。此 Amazon S3 位置的连接和权限是必需的。有关更多信息，请参阅本主题后面的[Amazon S3 中的溢出位置](#connect-to-data-source-hive-spill-location)。 + **Athena** – 需要访问权限才能检查查询状态并防止过度扫描。 + **AWS Glue** – 如果您的连接器将 AWS Glue 用于补充元数据或主元数据，则需要访问权限。 + **AWS Key Management Service** + **策略** – 除了 [AWS 托管策略：AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy)，Hive 元数据仓、Athena Query Federation 和 UDF 需要策略。有关更多信息，请参阅 [Athena 中的 Identity and Access Management](security-iam-athena.md)。 ### Amazon S3 中的溢出位置 由于对 Lambda 函数响应大小的[限制](https://docs.aws.amazon.com/lambda/latest/dg/limits.html)，则大于阈值的响应会溢出到您在创建 Lambda 函数时指定的 Amazon S3 位置。Athena 直接从 Amazon S3 读取这些响应。 **注意** Athena 不会删除 Amazon S3 上的响应文件。我们建议您设置保留策略以自动删除响应文件。 # 将 Athena 连接到 Apache Hive 元存储 要将 Athena 连接到 Apache Hive 元数据仓，您必须创建和配置 Lambda 函数。对于基本实现，您可以从 Athena 管理控制台执行所有必需步骤。 **注意** 以下过程要求您具有为 Lambda 函数创建自定义 IAM 角色的权限。如果您没有权限创建自定义角色，则可以使用 Athena [参考实现](connect-to-data-source-hive.md#connect-to-a-data-source-hive-features-reference-implementation)以单独创建 Lambda 函数，然后使用 AWS Lambda 控制台，为函数选择现有 IAM 角色。有关更多信息，请参阅 [使用现有 IAM 执行角色将 Athena 连接到 Hive 元存储](connect-data-source-hive-existing-iam-role.md)。 **要将 Athena 连接到 Hive 元数据仓** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 选择**数据来源和目录**。 1. 在控制台右上角，选择 **Connect data source**（连接数据源）。 1. 在 **Choose a data sources**（选择数据源）页面中，对于 **Data source**（数据源），请选择 **S3 - Apache Hive metastore**（S3 - Apache Hive 元数据仓）。 1. 选择**下一步**。 1. 在 **Data source details**（数据源详细信息）部分，对于 **Data source name**（数据源名称），输入从 Athena 查询数据源时想要在 SQL 语句中使用的名称。名称最多可以包括 127 个字符，并且在您的账户中必须是唯一的。它在创建后即无法更改。有效字符包括 a-z、A-Z、0-9、\$1（下划线）、@（at 符号）和 -（连字符）。名称 `awsdatacatalog`、`hive`、`jmx` 和 `system` 是 Athena 预留的名称，无法用于数据源名称。 1. 对于 **Lambda function**（Lambda 函数），选择 **Create Lambda function**（创建 Lambda 函数），然后选择 **Create a new Lambda function in AWS Lambda**（在 中新建 Lambda 函数） **AthenaHiveMetastoreFunction** 页面将会在 AWS Lambda 控制台中打开。该页面包括连接器的详细信息。 ![\[AWS Lambda 控制台中的 AthenaHiveMetastoreFunction 页面。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connect-to-data-source-hive-4.png) 1. 在 **Application settings**（应用程序设置）中，输入 Lambda 函数的参数。 + **LambdaFuncName** – 提供函数的名称。例如，**myHiveMetastore**。 + **SpillLocation** – 在此账户中指定 Amazon S3 位置，以便在 Lambda 函数响应大小超过 4 MB 时保存溢出元数据。 + **HMSUris** – 输入您的 Hive 元数据仓主机的名称，该主机在端口 9083 使用 Thrift 协议。使用语法 `thrift://:9083`。 + **LambdaMemory** – 指定从 128 MB 到 3008 MB 的值。Lambda 函数分配与您配置的内存量成比例的 CPU 周期。默认值为 1024。 + **LambdaTimeout** – 指定允许的最大 Lambda 调用运行时（以秒为单位），从 1 到 900（900 秒为 15 分钟）。默认值为 300 秒（5 分钟）。 + **VpcSecurityGroupIds** – 为 Hive 元数据仓输入一个逗号分隔的 VPC 安全组 ID 列表。 + **VpcSubneIds** – 为 Hive 元数据仓输入一个逗号分隔的 VPC 子网 ID 列表。 1. 选择 **I acknowledge that this app creates custom IAM roles**（我确认此应用程序创建自定义 IAM 角色），然后选择 **Deploy**（部署）。 ![\[从 AWS Lambda 控制台部署 Lambda 函数应用程序。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connect-to-data-source-hive-4a.png) 部署完成后，函数将显示在 Lambda 应用程序列表中。现在 Hive 元数据仓功能已部署到您的账户，您可以配置 Athena 配置以使用此功能。 1. 返回至 Athena 控制台中的 **Enter data source details**（输入数据源详细信息）页面。 1. 在 **Lambda function**（Lambda 函数）部分，选择 Lambda 函数搜索框旁的刷新图标。刷新可用函数列表会导致新创建的函数出现在列表中。 1. 在 Lambda 控制台上选择刚创建的函数名称。将显示 Lambda 函数的 ARN。 1. （可选）对于 **Tags**（标签），添加要与此数据源关联的键值对。有关标签的更多信息，请参阅[标记 Athena 资源](tags.md)。 1. 选择**下一步**。 1. 在 **Review and create**（审核和创建）页面中，查看数据源的详细信息，然后选择 **Create data source**（创建数据源）。 1. 数据源此页面的 **Data source details**（数据源详细信息）部分显示了有关新连接器的信息。 您现在可以使用指定的 **Data source name**（数据源名称）以在 Athena 的 SQL 查询中引用 Hive 元数据仓。在 SQL 查询中，使用以下示例语法，并将 `hms-catalog-1` 替换为您之前指定的目录名称。 ``` SELECT * FROM hms-catalog-1.CustomerData.customers ``` 1. 有关查看、编辑或删除您创建的数据源的信息，请参阅 [管理您的数据来源](data-sources-managing.md)。 # 使用 AWS Serverless Application Repository 部署 Hive 数据来源连接器 要部署适用于 Hive 的 Athena 数据来源连接器，您可以使用 [AWS Serverless Application Repository](https://aws.amazon.com/serverless/serverlessrepo/)，而不是从 Athena 控制台开始。使用 AWS Serverless Application Repository 找到要使用的连接器，提供连接器所需的参数，然后将连接器部署到您的账户。部署连接器后，您可以使用 Athena 控制台向 Athena 提供数据来源。 **使用 AWS Serverless Application Repository 将适用于 Hive 的数据来源连接器部署到您的账户** 1. 登录 AWS 管理控制台并打开 **Serverless App Repository (无服务器应用程序存储库)**。 1. 在导航窗格中，选择 **Available applications (可用应用程序)**。 1. 选择 **Show apps that create custom IAM roles or resource policies**（显示创建自定义 IAM 角色或资源策略的应用程序）选项。 1. 在搜索框中，输入 **Hive**。显示的连接器包括以下两个： + **AthenaHiveMetastoreFunction** – Uber Lambda 函数 `.jar` 文件。 + **AthenaHiveMetastoreFunctionWithLayer** – Lambda 层和 thin Lambda 函数 `.jar` 文件。 这两个应用程序具有相同的功能，仅在实施方面存在差异。您可以使用二者之一创建将 Athena 连接到 Hive 元数据仓的 Lambda 函数。 1. 选择要使用的连接器名称。本教程使用 **AthenaHiveMetastoreFunction**。 ![\[选择适用于 Hive 的 Athena 数据来源连接器的名称。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connect-data-source-sar-hive-1.png) 1. 在 **Application settings**（应用程序设置）中，输入 Lambda 函数的参数。 + **LambdaFuncName** – 提供函数的名称。例如，**myHiveMetastore**。 + **SpillLocation** – 在此账户中指定 Amazon S3 位置，以便在 Lambda 函数响应大小超过 4 MB 时保存溢出元数据。 + **HMSUris** – 输入您的 Hive 元数据仓主机的名称，该主机在端口 9083 使用 Thrift 协议。使用语法 `thrift://:9083`。 + **LambdaMemory** – 指定从 128 MB 到 3008 MB 的值。Lambda 函数分配与您配置的内存量成比例的 CPU 周期。默认值为 1024。 + **LambdaTimeout** – 指定允许的最大 Lambda 调用运行时（以秒为单位），从 1 到 900（900 秒为 15 分钟）。默认值为 300 秒（5 分钟）。 + **VpcSecurityGroupIds** – 为 Hive 元数据仓输入一个逗号分隔的 VPC 安全组 ID 列表。 + **VpcSubneIds** – 为 Hive 元数据仓输入一个逗号分隔的 VPC 子网 ID 列表。 1. 在 **Application details**（应用程序详细信息）页面的右下角，选择 **I acknowledge that this app creates custom IAM roles**（我确认此应用程序创建自定义 IAM 角色），然后选择 **Deploy**（部署）。 此时，您可以将 Athena 配置为使用 Lambda 函数连接到 Hive 元数据仓。要查看步骤，请参阅[配置 Athena 使用部署的 Hive 元存储连接器](connect-data-source-hive-existing-lambda.md)。 # 使用现有 IAM 执行角色将 Athena 连接到 Hive 元存储 要借助使用现有 IAM 角色的 Lambda 函数将外部 Hive 元数据仓连接到 Athena，您可以将 Athena 的 Athena 连接器引用实现用于外部 Hive 元数据仓。 这三个主要步骤如下所示： 1. **[克隆和构建](#connect-data-source-hive-existing-iam-role-clone-and-build-the-lambda-function)**：克隆 Athena 引用实现并构建包含 Lambda 函数代码的 JAR 文件。 1. **[AWS Lambda 控制台](#connect-data-source-hive-existing-iam-role-aws-lambda-console)** – 在 AWS Lambda 控制台，创建 Lambda 函数，为其分配现有 IAM 执行角色，然后上载您生成的函数代码。 1. **[Amazon Athena 控制台](connect-data-source-hive-existing-lambda.md)** – 在 Amazon Athena 控制台中，创建一个数据来源名称，您可以使用该名称在 Athena 查询中引用外部 Hive 元存储。 如果您已拥有创建自定义 IAM 角色的权限，则可以使用更简单的工作流程，该工作流程使用 Athena 控制台和 AWS Serverless Application Repository 创建和配置 Lambda 函数。有关更多信息，请参阅 [将 Athena 连接到 Apache Hive 元存储](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md)。 ## 先决条件 + Git 必须安装在您的系统上。 + 您必须先行安装 [Apache Maven](https://maven.apache.org/)。 + 您有一个 IAM 执行角色，可以将其分配给 Lambda 函数。有关更多信息，请参阅 [允许 Lambda 函数访问外部 Hive 元存储](hive-metastore-iam-access-lambda.md)。 ## 克隆并构建 Lambda 函数 Athena 参考实现的函数代码是一个位于 GitHub 上的 Maven 项目，具体地址为 [awslabs/aws-athena-hive-metastore](https://github.com/awslabs/aws-athena-hive-metastore)。有关项目的详细信息，请参阅 GitHub 上相应的自述文件或本文档中的 [修改 Athena 外部 Hive 元存储连接器](datastores-hive-reference-implementation.md) 主题。 **克隆和构建 Lambda 函数代码** 1. 输入以下命令以克隆 Athena 引用实现： ``` git clone https://github.com/awslabs/aws-athena-hive-metastore ``` 1. 运行以下命令为 Lambda 函数构建 `.jar` 文件： ``` mvn clean install ``` 项目构建成功后，以下 `.jar` 文件将在项目的目标文件夹中创建： `hms-lambda-func-1.0-SNAPSHOT-withdep.jar` 在下一部分中，您将使用 AWS Lambda 控制台将此文件上载到 Amazon Web Services 账户。 ## 在 AWS Lambda 控制台中创建和配置 Lambda 函数 在本节中，您将使用 AWS Lambda 控制台创建一个使用现有 IAM 执行角色的函数。为函数配置 VPC 后，您可以上载函数代码并配置该函数的环境变量。 ### 创建 Lambda 函数 在此步骤中，您将在 AWS Lambda 控制台中创建一个使用现有 IAM 角色的函数。 **要创建使用现有 IAM 角色的 Lambda 函数** 1. 登录到 AWS 管理控制台，然后通过以下网址打开 AWS Lambda 控制台：[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/)。 1. 在导航窗格中，选择**函数**。 1. 选择**创建函数**。 1. 选择**从头开始创作**。 1. 在 **Function name**（函数名称）中，输入 Lambda 函数的名称（例如 **EHMSBasedLambda**）。 1. 对于 **Runtime**（运行时），请选择 **Java 8**。 1. 在 **Permissions**（权限）下，展开 **Change default execution role**（更改默认执行角色）。 1. 对于 **Execution role (执行角色)**，选择 **Use an existing role (使用现有角色)**。 1. 对于 **Existing role**（现有角色），请选择 Lambda 函数将用于 Athena 的 IAM 执行角色（此示例使用名为 `AthenaLambdaExecutionRole` 的角色)。 1. 展开 **Advanced settings**（高级设置）。 1. 选择 **Enable Network**（启用网络）。 1. 对于 **VPC**，请选择您的函数将有权访问的 VPC。 1. 对于 **Subnets**（子网），选择 Lambda 要使用的 VPC 子网。 1. 对于 **Security groups**（安全组），选择 Lambda 要使用的 VPC 安全组。 1. 选择**创建函数**。AWS Lambda 控制台，然后打开函数的配置页面并开始创建函数。 ### 上载代码并配置 Lambda 函数 当控制台通知您已成功创建函数时，您就可以上载函数代码并配置其环境变量。 **上载 Lambda 函数代码并配置其环境变量** 1. 在 Lambda 控制台中，确保您位于指定函数页面的 **Code**（代码）选项卡上。 1. 对于 **Code source**（代码源），选择 **Upload from**（上传格式），然后选择 **.zip or .jar file**（.zip 或 .jar 文件）。 1. 上载您之前生成的 `hms-lambda-func-1.0-SNAPSHOT-withdep.jar` 文件。 1. 在 Lambda 函数页面上，选择**配置**选项卡。 1. 从左侧窗格中选择 **Environment variables**（环境变量）。 1. 在 **Environment variables (环境变量)** 部分中，选择 **Edit (编辑)**。 ![\[选择 Edit（编辑）为 Lambda 函数编辑环境变量。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connect-data-source-hive-existing-iam-role-5.png) 1. 在 **Edit environment variables**（编辑环境变量）页面上，使用 **Add environment variable**（添加环境变量）选项，添加以下环境变量键和值： + **HMS\$1URIS** – 使用以下语法，输入 Hive 元数据仓主机的 URI，该主机在端口 9083 使用 Thrift 协议。 ``` thrift://:9083 ``` + **SPILL\$1LOCATION** – 在 Amazon Web Services 账户中指定 Amazon S3 位置，以便在 Lambda 函数响应大小超过 4MB 时保存溢出元数据。 ![\[为 Lambda 函数环境变量指定值。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connect-data-source-hive-existing-iam-role-6.png) 1. 选择**保存**。 此时，您已准备好将 Athena 配置为使用 Lambda 函数连接到 Hive 元数据仓。要查看步骤，请参阅[配置 Athena 使用部署的 Hive 元存储连接器](connect-data-source-hive-existing-lambda.md)。 # 配置 Athena 使用部署的 Hive 元存储连接器 将 `AthenaHiveMetastoreFunction` 等 Lambda 数据源连接器部署到账户后，您可以配置 Athena 以进行使用。为此，请创建数据源名称，该名称会引用外部 Hive 元数据仓以在 Athena 查询中使用。 **使用现有 Lambda 函数将 Athena 连接到 Hive 元数据仓** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 选择**数据来源和目录**。 1. 在**数据来源和目录**页面上，选择**创建数据来源**。 1. 在 **Choose a data sources**（选择数据源）页面中，对于 **Data source**（数据源），请选择 **S3 - Apache Hive metastore**（S3 - Apache Hive 元数据仓）。 1. 选择**下一步**。 1. 在 **Data source details**（数据源详细信息）部分中，对于 **Data source name**（数据源名称），请输入从 Athena 查询数据源时要在 SQL 语句中使用的名称（例如 `MyHiveMetastore`）。名称最多可以包括 127 个字符，并且在您的账户中必须是唯一的。它在创建后即无法更改。有效字符包括 a-z、A-Z、0-9、\$1（下划线）、@（at 符号）和 -（连字符）。名称 `awsdatacatalog`、`hive`、`jmx` 和 `system` 是 Athena 预留的名称，无法用于数据源名称。 1. 在 **Connection details**（连接详细信息）部分中，请使用 **Select or enter a Lambda function**（选择或输入 Lambda 函数）框以选择刚创建的函数名称。将显示 Lambda 函数的 ARN。 1. （可选）对于 **Tags**（标签），添加要与此数据源关联的键值对。有关标签的更多信息，请参阅[标记 Athena 资源](tags.md)。 1. 选择**下一步**。 1. 在 **Review and create**（审核和创建）页面中，查看数据源的详细信息，然后选择 **Create data source**（创建数据源）。 1. 数据源此页面的 **Data source details**（数据源详细信息）部分显示了有关新连接器的信息。 您现在可以使用指定的 **Data source name**（数据源名称）以在 Athena 的 SQL 查询中引用 Hive 元数据仓。 在 SQL 查询中，使用以下示例语法，并将 `ehms-catalog` 替换为您之前指定的数据源名称。 ``` SELECT * FROM ehms-catalog.CustomerData.customers ``` 1. 要查看、编辑或删除您创建的数据源，请参阅[管理您的数据来源](data-sources-managing.md)。 # 省略外部 Hive 元存储查询中的目录名称 在外部 Hive 元存储上运行 DML 和 DDL 查询时，如果在查询编辑器中选择了目录名称，则可以通过省略该名称来简化查询语法。此功能将受到一些限制。 ## DML 语句 **使用已注册目录运行查询** 1. 您可以使用语法 `[[data_source_name].database_name].table_name` 将数据源名称置于数据库之前，如以下示例所示。 ``` select * from "hms-catalog-1".hms_tpch.customer limit 10; ``` 1. 如果已在查询编辑器中选定要使用的数据源，您可以在查询中省略数据源名称，如以下示例所示。 ``` select * from hms_tpch.customer limit 10: ``` ![\[使用默认数据源的 DML 查询。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/datastores-hive-default-catalog-2.png) 1. 在查询中使用多个数据源时，只能省略默认数据源名称，并且必须为任何非默认数据源指定全名。 例如，假设在查询编辑器中将 `AwsDataCatalog` 选作默认数据源。以下查询摘录中的 `FROM` 语句完全限定了前两个数据源名称，但省略了第三个数据源的名称，因为它位于 AWS Glue 数据目录中。 ``` ... FROM ehms01.hms_tpch.customer, "hms-catalog-1".hms_tpch.orders, hms_tpch.lineitem ... ``` ## DDL 语句 以下 Athena DDL 语句支持目录名称前缀。其他 DDL 语句中的目录名称前缀会导致语法错误。 ``` SHOW TABLES [IN [catalog_name.]database_name] ['regular_expression'] SHOW TBLPROPERTIES [[catalog_name.]database_name.]table_name [('property_name')] SHOW COLUMNS IN [[catalog_name.]database_name.]table_name SHOW PARTITIONS [[catalog_name.]database_name.]table_name SHOW CREATE TABLE [[catalog_name.][database_name.]table_name DESCRIBE [EXTENDED | FORMATTED] [[catalog_name.][database_name.]table_name [PARTITION partition_spec] [col_name ( [.field_name] | [.'$elem$'] | [.'$key$'] | [.'$value$'] )] ``` 与 DML 语句一样，在查询编辑器中选择了数据源和数据库时，可以省略查询中的数据源和数据库前缀。 在以下示例中，在查询编辑器中选择了 `hms-catalog-1` 数据源和 `hms_tpch` 数据库。即使查询本身中忽略 `hms-catalog-1` 前缀和 `hms_tpch` 数据库名称，`show create table customer` 语句也会成功。 ![\[使用默认目录的 DDL 语句。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/datastores-hive-default-catalog-4.png) ## 在 JDBC 连接字符串中指定默认数据源 当您使用 Athena JDBC 驱动程序将 Athena 连接到外部 Hive 元存储时，可以使用 `Catalog` 参数在 SQL 编辑器（如 [SQL Workbench](https://www.sql-workbench.eu/index.html)）中的连接字符串中指定默认数据源名称。 **注意** 要下载最新版本的 Athena JDBC 驱动程序，请参阅[将 Athena 与 JDBC 驱动程序一起使用](https://docs.aws.amazon.com/athena/latest/ug/connect-with-jdbc.html)。 以下连接字符串指定默认数据源 *hms-catalog-name*。 ``` jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://amzn-s3-demo-bucket/lambda/results/;Workgroup=AmazonAthenaPreviewFunctionality;Catalog=hms-catalog-name; ``` 下图显示了 SQL Workbench 中配置的示例 JDBC 连接 URL。 ![\[在 SQL Workbench 中配置 JDBC 连接 URL。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/datastores-hive-default-catalog-jdbc-1.jpg) # 使用 Hive 视图 您可以使用 Athena 查询外部 Apache Hive 元存储中的现有视图。Athena 会在运行时实时转换视图，无需更改原始视图或存储翻译。 例如，假设您的 Hive 视图使用了 Athena 中不支持的语法，比如 `LATERAL VIEW explode()`： ``` CREATE VIEW team_view AS SELECT team, score FROM matches LATERAL VIEW explode(scores) m AS score ``` Athena 将 Hive 视图查询字符串转换为 Athena 可以运行的语句，如下所示： ``` SELECT team, score FROM matches CROSS JOIN UNNEST(scores) AS m (score) ``` 有关将外部 Hive 元存储连接到 Athena 的信息，请参阅 [使用外部 Hive 元存储](connect-to-data-source-hive.md)。 ## 注意事项和限制 在从 Athena 查询 Hive 视图时，请考虑以下几点： + Athena 不支持创建 Hive 视图。您可以在外部 Hive 元存储中创建 Hive 视图，之后可以从 Athena 查询该视图。 + Athena Hive 视图不支持自定义 UDF。 + 由于 Athena 控制台中的已知问题，Hive 视图显示在表列表下而不是视图列表下。 + 尽管转换过程会自动执行，但 Hive 视图不支持某些 Hive 函数或需要特殊处理。有关更多信息，请参阅下文。 ## Hive 函数支持限制 此部分重点介绍了 Athena Hive 视图不支持的或需要特殊处理的 Hive 函数。目前，Athena 主要支持 Hive 2.2.0 的函数，因此不支持只在更高版本（例如 Hive 4.0.0）中可用的函数。有关 Hive 函数的完整列表，请参阅 [Hive 语言手册 UDF](https://cwiki.apache.org/confluence/display/hive/languagemanual+udf)。 ### 聚合函数 #### 需要特殊处理的聚合函数 以下 Hive 视图的聚合函数需要特殊处理。 + **Avg** – 请使用 `avg(CAST(i AS DOUBLE))`，而非 `avg(INT i)`。 #### 不支持的聚合函数 Athena 的 Hive 视图不支持以下 Hive 聚合函数。 ``` covar_pop histogram_numeric ntile percentile percentile_approx ``` Athena 的 Hive 视图不支持 `regr_count`、`regr_r2` 和 `regr_sxx` 等回归函数。 ### 不支持的日期函数 Athena 的 Hive 视图不支持以下 Hive 日期函数。 ``` date_format(date/timestamp/string ts, string fmt) day(string date) dayofmonth(date) extract(field FROM source) hour(string date) minute(string date) month(string date) quarter(date/timestamp/string) second(string date) weekofyear(string date) year(string date) ``` ### 不支持的掩码函数 Athena 的 Hive 视图不支持 `mask()` 和 `mask_first_n()` 等 Hive 掩码函数。 ### 其他函数 #### 需要特殊处理的其他函数 Hive 视图的以下其他函数需要特殊处理。 + **md5** – Athena 支持 `md5(binary)`，但不支持 `md5(varchar)`。 + **Explode** – 在以下语法中使用时，Athena 支持 `explode`： ``` LATERAL VIEW [OUTER] EXPLODE() ``` + **Posplode**：在以下语法中使用时，Athena 支持 `posexplode`： ``` LATERAL VIEW [OUTER] POSEXPLODE() ``` 在 `(pos, val)` 输出中，Athena 将 `pos` 视为 `BIGINT`。因此，您可能需要将 `pos` 转换为 `BIGINT`，防止提供过时视图。以下示例对此方法进行了说明。 ``` SELECT CAST(c AS BIGINT) AS c_bigint, d FROM table LATERAL VIEW POSEXPLODE() t AS c, d ``` #### 不支持的其他函数 Athena 的 Hive 视图不支持以下 Hive 函数。 ``` aes_decrypt aes_encrypt current_database current_user inline java_method logged_in_user reflect sha/sha1/sha2 stack version ``` ### 运算符 #### 需要特殊处理的运算符 Hive 视图的以下运算符需要特殊处理。 + **Mod 运算符 (%)**：因为 `DOUBLE` 类型隐式转换为 `DECIMAL(x,y)`，以下语法可能导致出现 View is stale（视图已过时）错误消息： ``` a_double % 1.0 AS column ``` 使用 `CAST` 可解决此问题，如以下示例所示。 ``` CAST(a_double % 1.0 as DOUBLE) AS column ``` + **除法运算符 (/)**：在 Hive 中，`int` 除以 `int` 会生成 `double`。在 Athena 中，同样的操作会产生截断 `int`。 #### 不支持的运算符 Athena 的 Hive 视图不支持以下运算符。 **\$1A** – 按位 `NOT` **A ^ b** – 按位 `XOR` **A & b** – 按位 `AND` **A \$1 b** – 按位 `OR` **A <=> b** – 返回与非空操作数的等于 (`=`) 运算符相同的结果。如果两者都为 `NULL`，则返回 `TRUE`；如果其中一个为 `NULL`，则返回 `FALSE`。 ### 字符串函数 #### 需要特殊处理的字符串函数 Hive 视图的以下 Hive 字符串函数需要特殊处理。 + **chr(bigint\$1double a)** – Hive 允许负参数，但 Athena 不允许。 + **instr(string str, string substr)** – 因为 `instr` 函数的 Athena 映射返回 `BIGINT` 而非 `INT`，所以使用以下语法： ``` CAST(instr(string str, string substr) as INT) ``` 如果不执行此步骤，视图将被视作过时。 + **length(string a)** – 因为 `length` 函数的 Athena 映射返回 `BIGINT` 而非 `INT`，所以使用以下函数，避免视图被视作过时： ``` CAST(length(string str) as INT) ``` #### 不支持的字符串函数 Athena 的 Hive 视图不支持以下 Hive 字符串函数。 ``` ascii(string str) character_length(string str) decode(binary bin, string charset) encode(string src, string charset) elt(N int,str1 string,str2 string,str3 string,...) field(val T,val1 T,val2 T,val3 T,...) find_in_set(string str, string strList) initcap(string A) levenshtein(string A, string B) locate(string substr, string str[, int pos]) octet_length(string str) parse_url(string urlString, string partToExtract [, string keyToExtract]) printf(String format, Obj... args) quote(String text) regexp_extract(string subject, string pattern, int index) repeat(string str, int n) sentences(string str, string lang, string locale) soundex(string A) space(int n) str_to_map(text[, delimiter1, delimiter2]) substring_index(string A, string delim, int count) ``` ### 不支持的 xPath 函数 Athena 的 Hive 视图不支持 `xpath`、`xpath_short` 和 `xpath_int` 等 Hive XPath 函数。 ## 问题排查 在 Athena 中使用 Hive 视图时，可能遇到以下问题： + **视图 ** 已过时** – 此消息通常表示 Hive 视图与 Athena 视图存在类型不匹配问题。如果 [Hive LanguageManual UDF](https://cwiki.apache.org/confluence/display/hive/languagemanual+udf) 以及 [Presto 函数和运算符](https://prestodb.io/docs/current/functions.html)文档中的相同函数具有不同签名，请尝试强制转换不匹配的数据类型。 + **函数未注册**：Athena 目前不支持此函数。有关更多信息，请参阅本文档前面所述的信息。 # 将 AWS CLI 与 Hive 元存储结合使用 您可以使用 `aws athena` CLI 命令管理与 Athena 结合使用的 Hive 元数据仓数据目录。在定义一个或多个要与 Athena 结合使用的目录后，可以在 `aws athena` DDL 和 DML 命令中引用这些目录。 ## 使用 AWS CLI 管理 Hive 元存储目录 ### 注册目录：Create-data-catalog 要注册数据目录，请使用 `create-data-catalog` 命令。使用 `name` 参数指定要用于目录的名称。将 Lambda 函数的 ARN 传递到 `parameters` 参数的 `metadata-function` 选项。要为新目录创建标签，请将 `tags` 参数与一个或多个用空格分隔的 `Key=key,Value=value` 参数对结合使用。 以下示例注册名为 `hms-catalog-1` 的 Hive 元存储目录。该命令设置了格式以便于阅读。 ``` $ aws athena create-data-catalog --name "hms-catalog-1" --type "HIVE" --description "Hive Catalog 1" --parameters "metadata-function=arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3,sdk-version=1.0" --tags Key=MyKey,Value=MyValue --region us-east-1 ``` ### 显示目录详细信息：Get-data-catalog 要显示目录的详细信息，请将目录的名称传递到 `get-data-catalog` 命令，如以下示例所示。 ``` $ aws athena get-data-catalog --name "hms-catalog-1" --region us-east-1 ``` 以下示例结果采用 JSON 格式。 ``` { "DataCatalog": { "Name": "hms-catalog-1", "Description": "Hive Catalog 1", "Type": "HIVE", "Parameters": { "metadata-function": "arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3", "sdk-version": "1.0" } } } ``` ### 列出已注册的目录：List-data-catalogs 要列出已注册的目录，请使用 `list-data-catalogs` 命令并选择性地指定一个区域，如以下示例所示。列出的目录始终包含 AWS Glue。 ``` $ aws athena list-data-catalogs --region us-east-1 ``` 以下示例结果采用 JSON 格式。 ``` { "DataCatalogs": [ { "CatalogName": "AwsDataCatalog", "Type": "GLUE" }, { "CatalogName": "hms-catalog-1", "Type": "HIVE", "Parameters": { "metadata-function": "arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3", "sdk-version": "1.0" } } ] } ``` ### 更新目录：Update-data-catalog 要更新数据目录，请使用 `update-data-catalog` 命令，如以下示例所示。该命令设置了格式以便于阅读。 ``` $ aws athena update-data-catalog --name "hms-catalog-1" --type "HIVE" --description "My New Hive Catalog Description" --parameters "metadata-function=arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-new,sdk-version=1.0" --region us-east-1 ``` ### 删除目录：Delete-data-catalog 要删除数据目录，请使用 `delete-data-catalog` 命令，如以下示例所示。 ``` $ aws athena delete-data-catalog --name "hms-catalog-1" --region us-east-1 ``` ### 显示数据库详细信息：Get-database 要显示数据库的详细信息，请将目录名称和数据库名称传递到 `get-database` 命令，如以下示例所示。 ``` $ aws athena get-database --catalog-name hms-catalog-1 --database-name mydb ``` 以下示例结果采用 JSON 格式。 ``` { "Database": { "Name": "mydb", "Description": "My database", "Parameters": { "CreatedBy": "Athena", "EXTERNAL": "TRUE" } } } ``` ### 在目录中列出数据库：List-databases 要在目录中列出数据库，请使用 `list-databases` 命令并选择性地指定一个区域，如以下示例所示。 ``` $ aws athena list-databases --catalog-name AwsDataCatalog --region us-west-2 ``` 以下示例结果采用 JSON 格式。 ``` { "DatabaseList": [ { "Name": "default" }, { "Name": "mycrawlerdatabase" }, { "Name": "mydatabase" }, { "Name": "sampledb", "Description": "Sample database", "Parameters": { "CreatedBy": "Athena", "EXTERNAL": "TRUE" } }, { "Name": "tpch100" } ] } ``` ### 显示表详细信息：Get-table-metadata 要显示表的元数据（包括列名和数据类型），请将目录名称、数据库名称和表名称传递到 `get-table-metadata` 命令，如以下示例所示。 ``` $ aws athena get-table-metadata --catalog-name AwsDataCatalog --database-name mydb --table-name cityuseragent ``` 以下示例结果采用 JSON 格式。 ``` { "TableMetadata": { "Name": "cityuseragent", "CreateTime": 1586451276.0, "LastAccessTime": 0.0, "TableType": "EXTERNAL_TABLE", "Columns": [ { "Name": "city", "Type": "string" }, { "Name": "useragent1", "Type": "string" } ], "PartitionKeys": [], "Parameters": { "COLUMN_STATS_ACCURATE": "false", "EXTERNAL": "TRUE", "inputformat": "org.apache.hadoop.mapred.TextInputFormat", "last_modified_by": "hadoop", "last_modified_time": "1586454879", "location": "s3://amzn-s3-demo-bucket/", "numFiles": "1", "numRows": "-1", "outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat", "rawDataSize": "-1", "serde.param.serialization.format": "1", "serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe", "totalSize": "61" } } } ``` ### 显示数据库中所有表的元数据：List-table-metadata 要显示数据库中所有表的元数据，请将目录名称和数据库名称传递到 `list-table-metadata` 命令。`list-table-metadata` 命令与 `get-table-metadata` 命令类似，只是未指定表名。要限制结果的数量，您可以使用 `--max-results` 选项，如以下示例所示。 ``` $ aws athena list-table-metadata --catalog-name AwsDataCatalog --database-name sampledb --region us-east-1 --max-results 2 ``` 以下示例结果采用 JSON 格式。 ``` { "TableMetadataList": [ { "Name": "cityuseragent", "CreateTime": 1586451276.0, "LastAccessTime": 0.0, "TableType": "EXTERNAL_TABLE", "Columns": [ { "Name": "city", "Type": "string" }, { "Name": "useragent1", "Type": "string" } ], "PartitionKeys": [], "Parameters": { "COLUMN_STATS_ACCURATE": "false", "EXTERNAL": "TRUE", "inputformat": "org.apache.hadoop.mapred.TextInputFormat", "last_modified_by": "hadoop", "last_modified_time": "1586454879", "location": "s3://amzn-s3-demo-bucket/", "numFiles": "1", "numRows": "-1", "outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat", "rawDataSize": "-1", "serde.param.serialization.format": "1", "serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe", "totalSize": "61" } }, { "Name": "clearinghouse_data", "CreateTime": 1589255544.0, "LastAccessTime": 0.0, "TableType": "EXTERNAL_TABLE", "Columns": [ { "Name": "location", "Type": "string" }, { "Name": "stock_count", "Type": "int" }, { "Name": "quantity_shipped", "Type": "int" } ], "PartitionKeys": [], "Parameters": { "EXTERNAL": "TRUE", "inputformat": "org.apache.hadoop.mapred.TextInputFormat", "location": "s3://amzn-s3-demo-bucket/", "outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat", "serde.param.serialization.format": "1", "serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe", "transient_lastDdlTime": "1589255544" } } ], "NextToken": "eyJsYXN0RXZhbHVhdGVkS2V5Ijp7IkhBU0hfS0VZIjp7InMiOiJ0Ljk0YWZjYjk1MjJjNTQ1YmU4Y2I5OWE5NTg0MjFjYTYzIn0sIlJBTkdFX0tFWSI6eyJzIjoiY2xlYXJpbmdob3VzZV9kYXRhIn19LCJleHBpcmF0aW9uIjp7InNlY29uZHMiOjE1ODkzNDIwMjIsIm5hbm9zIjo2NTUwMDAwMDB9fQ==" } ``` ## 运行 DDL 和 DML 语句 在使用 AWS CLI 运行 DDL 和 DML 语句时，您可以通过两种方式之一传递 Hive 元存储目录的名称： + 直接传入支持它的语句。 + 传递到 `--query-execution-context` `Catalog` 参数。 ### DDL 语句 以下示例将目录名称作为 `show create table` DDL 语句的一部分直接传入。该命令设置了格式以便于阅读。 ``` $ aws athena start-query-execution --query-string "show create table hms-catalog-1.hms_tpch_partitioned.lineitem" --result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results" ``` 以下示例 DDL `show create table` 语句使用 `--query-execution-context` 的 `Catalog` 参数传递 Hive 元存储目录名称 `hms-catalog-1`。该命令设置了格式以便于阅读。 ``` $ aws athena start-query-execution --query-string "show create table lineitem" --query-execution-context "Catalog=hms-catalog-1,Database=hms_tpch_partitioned" --result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results" ``` ### DML 语句 以下示例 DML `select` 语句将目录名称直接传入查询。该命令设置了格式以便于阅读。 ``` $ aws athena start-query-execution --query-string "select * from hms-catalog-1.hms_tpch_partitioned.customer limit 100" --result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results" ``` 以下示例 DML `select` 语句使用 `--query-execution-context` 的 `Catalog` 参数传入 Hive 元存储目录名称 `hms-catalog-1`。该命令设置了格式以便于阅读。 ``` $ aws athena start-query-execution --query-string "select * from customer limit 100" --query-execution-context "Catalog=hms-catalog-1,Database=hms_tpch_partitioned" --result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results" ``` # 修改 Athena 外部 Hive 元存储连接器 如果您有特殊要求，则可以修改外部 Hive 元存储的 Athena 连接器以供自己使用。Athena 为 GitHub.com（网址为 [https://github.com/awslabs/aws-athena-hive-metastore](https://github.com/awslabs/aws-athena-hive-metastore)）上的连接器提供参考实现。在大多数使用案例中，无需修改参考实施。但是，如有必要，您可以修改源代码并自行构建构件。 参考实施是一个具有以下模块的 [Apache Maven](https://maven.apache.org/) 项目： + `hms-service-api` – 包含 Lambda 函数和 Athena 服务客户端之间的 API 操作。这些 API 操作是在 `HiveMetaStoreService` 接口中定义的。由于这是一个服务合同，因此，您不应更改此模块中的任何内容。 + `hms-lambda-handler` – 一组默认 Lambda 处理程序，用于处理所有 Hive 元数据仓 API 调用。类 `MetadataHandler` 是用于所有 API 调用的调度程序。您无需更改此程序包。 + `hms-lambda-func` – 一个具有以下组件的示例 Lambda 函数。 + `HiveMetaStoreLambdaFunc` – 一个扩展 `MetadataHandler` 的示例 Lambda 函数。 + `ThriftHiveMetaStoreClient` – 一个与 Hive 元存储进行通信的 Thrift 客户端。此客户端是针对 Hive 2.3.0 编写的。如果您使用其他 Hive 版本，则可能需要更新此类以确保响应对象可兼容。 + `ThriftHiveMetaStoreClientFactory` – 控制 Lambda 函数的行为。例如，您可以通过覆盖 `getHandlerProvider()` 方法来提供自己的一组处理程序提供程序。 + `hms.properties` – 配置 Lambda 函数。在大多数情况下，只需更新以下两个属性。 + `hive.metastore.uris` – 格式为 `thrift://:9083` 的 Hive 元存储 URI。 + `hive.metastore.response.spill.location`：当响应对象的大小超过给定阈值（例如 4 MB）时，用于存储响应对象的 Amazon S3 位置。阈值是在属性 `hive.metastore.response.spill.threshold` 中定义的。建议不要更改默认值。 **注意** 这两个属性可以由 [Lambda 环境变量](https://docs.aws.amazon.com/lambda/latest/dg/env_variables.html) `HMS_URIS` 和 `SPILL_LOCATION` 覆盖。当您希望将 Lambda 函数用于不同的 Hive 元数据仓或溢出位置时，请使用这些变量而不是重新编译该函数的源代码。 + `hms-lambda-layer` – 一个 Maven 程序集项目，用于将 `hms-service-api`、`hms-lambda-handler` 及其依赖关系放入一个 `.zip` 文件中。此 `.zip` 文件将注册为 Lambda 层以供多个 Lambda 函数使用。 + `hms-lambda-rnp` – 记录来自 Lambda 函数的响应，然后将其用于重播响应。您可以使用此模型来模拟 Lambda 响应以进行测试。 ## 自行构建构件 修改源代码后，您可以自行构建构件并将其上载到 Amazon S3 位置。 在构建构件之前，请更新 `hms-lambda-func` 模块中 `hms.properties` 文件中的属性 `hive.metastore.uris` 和 `hive.metastore.response.spill.location`。 要构建构件，您必须已安装 Apache Maven 并运行命令 `mvn install`。这将在模块 `hms-lambda-layer` 中的名为 `target` 的输出文件夹中生成层 `.zip` 文件，并在模块 `hms-lambd-func` 中生成 Lambda 函数 `.jar` 文件。 # 管理您的数据来源 您可以使用 Athena 控制台的**数据来源和目录**页面来管理您创建的数据来源。 **查看数据来源** 1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。 1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。 ![\[选择扩展菜单。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/nav-pane-expansion.png) 1. 在导航窗格中，选择**数据来源和目录**。 1. 从数据来源列表中，选择要查看的数据来源的名称。 **注意** **Data source name**（数据来源名称）列中的项目对应于 [ListDataCatalogs](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDataCatalogs.html) API 操作和 [list-data-catalogs](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/list-data-catalogs.html) CLI 命令的输出。 **编辑数据来源** 1. 在**数据来源和目录**页面上，执行以下操作之一： + 选择目录名称旁边的按钮，然后依次选择 **Actions**（操作）、**Edit**（编辑）。 + 选择数据来源的名称。然后在详细信息页面上，依次选择 **Actions**（操作）、**Edit**（编辑）。 1. 在 **Edit**（编辑）页面上，您可以为数据来源选择另一个 Lambda 函数，或添加自定义标签。有关标签的更多信息，请参阅 [标记 Athena 资源](tags.md)。 1. 选择**保存**。 1. 要编辑 **AwsDataCatalog** 数据来源，请选择 **AwsDataCatalog** 链接以打开其详细信息页面。然后，在详细信息页面上，选择指向您可以在其中编辑目录的 AWS Glue 控制台的链接。 **共享数据来源** 有关共享数据来源的信息，请访问以下链接。 + 有关非 Hive Lambda 的数据来源，请参阅 [启用跨账户联合查询](xacct-fed-query-enable.md)。 + 有关 AWS Glue Data Catalog，请参阅 [配置 AWS Glue 数据目录的跨账户存取](security-iam-cross-account-glue-catalog-access.md)。 **删除数据来源** 1. 在**数据来源和目录**页面上，执行以下操作之一： + 选择目录名称旁边的按钮，然后依次选择 **Actions**（操作）、**Delete**（删除）。 + 选择数据来源的名称，然后在详细信息页面上，依次选择 **Actions**（操作）、**Delete**（删除）。 **注意** **AwsDataCatalog** 是您账户中的默认数据来源，不能删除。 系统会发出警告，当您删除数据来源时，其相应的数据目录、表和视图将从查询编辑器中删除。使用数据来源的已保存查询不再在 Athena 中运行。 1. 要确认删除，请键入数据来源的名称，然后选择 **Delete**（删除）。