Amazon Athena Snowflake 连接器 - Amazon Athena
先决条件限制术语参数数据类型支持数据类型转换分区和拆分性能传递查询许可证信息其他资源
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

Amazon Athena Snowflake 连接器

适用于 Snowflake 的 Amazon Athena 连接器使 Amazon Athena 能够使用 JDBC 对存储在 Snowflake SQL 数据库 中的数据或 RDS 实例运行 SQL 查询。

此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。

先决条件

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

限制

  • 不支持写入 DDL 操作。

  • 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。

  • 任何相关的 Lambda 限制。有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的 Lambda 配额。

  • 目前，不支持单个拆分的 Snowflake 视图。

  • 在 Snowflake 中，由于对象名称区分大小写，因此两个表能分别以小写和大写形式具有相同的名称（例如 EMPLOYEE 和 employee)。在 Athena 联合查询中，架构表名称以小写形式提供给 Lambda 函数。要解决此问题，您可以提供 @schemaCase 查询提示，用于从名称区分大小写的表中检索数据。以下是两个带有查询提示的示例查询。

    SELECT * FROM "lambda:snowflakeconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=upper"     
    SELECT * FROM "lambda:snowflakeconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=lower"

  • 如果您将 Snowflake 连接迁移到 Glue Catalog 和 Lake Formation，则默认情况下 Athena 不会将所有请求转换为大写或支持注释。Glue 连接的默认行为不会调整大小写。

    Snowflake 支持以下选择大小写模式：

    • NONE（使用 Glue 连接的连接器的默认选择）

    • CASE_INSENSITIVE_SEARCH

    • ANNOTATION（不使用 Glue 连接的连接器的默认选择）

术语

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

  • 数据库实例 — 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。

  • 处理程序 — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。

  • 元数据处理程序 — 从您的数据库实例中检索元数据的 Lambda 处理程序。

  • 记录处理程序 — 从您的数据库实例中检索数据记录的 Lambda 处理程序。

  • 复合处理程序 — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。

  • 属性或参数 — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。

  • 连接字符串 — 用于建立数据库实例连接的文本字符串。

  • 目录 — 向 Athena 注册的非 Amazon Glue 目录，是 connection_string 属性的必要前缀。

  • 多路复用处理程序 — 可以接受和使用多个数据库连接的 Lambda 处理程序。

参数

使用本节中的参数来配置 Snowflake 连接器。

我们建议您使用 Glue 连接对象来配置 Snowflake 连接器。要执行此操作，请将 Snowflake 连接器 Lambda 的 glue_connection 环境变量设置为要使用的 Glue 连接的名称。

Glue 连接属性

使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。

aws glue describe-connection-type --connection-type SNOWFLAKE

Lambda 环境属性

  • glue_connection – 指定与联合连接器关联的 Glue 连接的名称。

  • 大小写模式 –（可选）指定如何处理架构和表名的大小写。casing_mode 参数使用以下值来指定大小写行为：

    • 无 – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。

    • 注释 – 如果存在注释，则调整表名。对于未关联 Glue 连接的连接器，这是默认设置。

    • 搜索不区分大小写 – 对 Snowflake 中的架构和表名执行不区分大小写的搜索。如果查询包含的架构或表名与连接器的默认大小写模式不一致，请使用此值。

    • 大写 – 所有给定的架构和表名全部大写。

    • 小写 – 所有给定的架构和表名全部小写。

注意

  • 使用 Glue 连接创建的 Snowflake 连接器不支持使用多路复用处理程序。

  • 使用 Glue 连接创建的 Snowflake 连接器仅支持 ConnectionSchemaVersion 2。

存储凭证

所有使用 Glue 连接的连接器都必须使用 Amazon Secrets Manager 来存储凭证。有关更多信息，请参阅 通过 Snowflake 进行身份验证。

注意

2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 Amazon Glue 连接。

下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在手动部署早期版本的 Athena 数据来源连接器或未指定 glue_connection 环境属性时才使用以下参数。

Lambda 环境属性

  • 默认 — 用于连接至 Snowflake 数据库实例的 JDBC 连接字符串。例如，snowflake://${jdbc_connection_string}

  • catalog_connection_string — 供多路复用处理程序使用（使用 Glue 连接时不支持）。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mysnowflakecatalog，则环境变量名称是 mysnowflakecatalog_connection_string。

  • spill_bucket - 为超出 Lambda 函数限制的数据指定 Amazon S3 存储桶。

  • spill_prefix -（可选）默认为指定 spill_bucket（称为 athena-federation-spill）中的子文件夹。我们建议您在此位置配置 Amazon S3 存储生命周期，以删除早于预定天数或小时数的溢出内容。

  • spill_put_request_headers —（可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如 {"x-amz-server-side-encryption" : "AES256"})。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 PutObject。

  • kms_key_id -（可选）默认情况下，将使用经过 AES-GCM 身份验证的加密模式和随机生成的密钥对溢出到 Amazon S3 的任何数据进行加密。要让您的 Lambda 函数使用 KMS 生成的更强的加密密钥（如 a7e63k4b-8loc-40db-a2a1-4d0en2cd8331），您可以指定 KMS 密钥 ID。

  • disable_spill_encryption -（可选）当设置为 True 时，将禁用溢出加密。默认值为 False，此时将使用 AES-GCM 对溢出到 S3 的数据使用进行加密 - 使用随机生成的密钥，或者使用 KMS 生成密钥。禁用溢出加密可以提高性能，尤其是当您的溢出位置使用服务器端加密时。

连接字符串

使用以下格式的 JDBC 连接字符串连接到数据库实例。

snowflake://${jdbc_connection_string}

使用多路复用处理程序

您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。

处理程序 类
复合处理程序 SnowflakeMuxCompositeHandler
元数据处理程序 SnowflakeMuxMetadataHandler
记录处理程序 SnowflakeMuxRecordHandler
多路复用处理程序参数
参数 描述
$catalog_connection_string 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mysnowflakecatalog，则环境变量名称是 mysnowflakecatalog_connection_string。
default 必需。默认连接字符串。目录为 lambda:${AWS_LAMBDA_FUNCTION_NAME} 时使用此字符串。

以下示例属性适用于支持两个数据库实例的 Snowflake MUX Lambda 函数：snowflake1（默认）和 snowflake2。

属性 值
default snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1&${Test/RDS/Snowflake1}
snowflake_catalog1_connection_string snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}
snowflake_catalog2_connection_string snowflake://jdbc:snowflake://snowflake2.host:port/?warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2
提供凭证

要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 Amazon Secrets Manager。

  • 连接字符串 — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。

    重要

    作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 Amazon Secrets Manager 的信息，请参阅《Amazon Secrets Manager 用户指南》中的将硬编码密钥移至 Amazon Secrets Manager。

  • Amazon Secrets Manager - 要将 Athena 联合查询功能与 Amazon Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有互联网访问权限或者 VPC 端点，以连接到 Secrets Manager。

    您可以将 Amazon Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 username 和 password 值。

    对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 Amazon 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_bucket 必需。溢出桶名称。
spill_prefix 必需。溢出桶密钥前缀。
spill_put_request_headers （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，{"x-amz-server-side-encryption" : "AES256"})。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 PutObject。

数据类型支持

下表显示了适用于 JDBC 和 Apache Arrow 的相应数据类型。

JDBC Arrow
布尔值 位
整数 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_NTZ 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_EQUAL、LESS_THAN、LESS_THAN_OR_EQUAL、GREATER_THAN、GREATER_THAN_OR_EQUAL、IS_DISTINCT_FROM、NULL_IF、IS_NULL

  • 算术：ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE

  • 其他：LIKE_PATTERN、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 连接器支持传递查询。传递查询使用表函数将完整查询下推到数据来源来执行查询。

要在 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 文件中找到），并同意 GitHub.com 上的 LICENSE.txt 文件中提供的相应第三方许可证中的条款。

其他资源

有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 Snowflake 连接器的 pom.xml 文件。

有关此连接器的更多信息，请访问 GitHub.com 上的相应站点。