适用于 Snowflake
此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。
先决条件
可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅创建数据来源连接或使用 AWS Serverless Application Repository 部署数据来源连接器。
限制
-
不支持写入 DDL 操作。
-
在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。
-
任何相关的 Lambda 限制。有关更多信息，请参阅《AWS 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 注册的非 AWS Glue 目录，是
connection_string属性的必要前缀。 -
多路复用处理程序 — 可以接受和使用多个数据库连接的 Lambda 处理程序。
参数
使用本节中的参数来配置 Snowflake 连接器。
注意
2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。
下面列出的参数名称和定义适用于在 2024 年 12 月 3 日之前创建的 Athena 数据来源连接器，可能与相应的 AWS Glue 连接属性不同。从 2024 年 12 月 3 日起，仅在手动部署早期版本的 Athena 数据来源连接器时才使用以下参数。
连接字符串
使用以下格式的 JDBC 连接字符串连接到数据库实例。
snowflake://${jdbc_connection_string}
使用多路复用处理程序
您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。
| 处理程序 | 类 |
|---|---|
| 复合处理程序 | SnowflakeMuxCompositeHandler |
| 元数据处理程序 | SnowflakeMuxMetadataHandler |
| 记录处理程序 | SnowflakeMuxRecordHandler |
多路复用处理程序参数
| 参数 | 描述 |
|---|---|
$ |
必需。数据库实例连接字符串。将 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 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 AWS Secrets Manager。
-
连接字符串 — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。
重要
作为安全最佳实践，请勿在您的环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 AWS Secrets Manager 的信息，请参阅《AWS Secrets Manager 用户指南》中的将硬编码密钥移至 AWS Secrets Manager。
-
AWS Secrets Manager - 要将 Athena 联合查询功能与 AWS Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有互联网访问权限
或者 VPC 端点，以连接到 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_bucket |
必需。溢出桶名称。 |
spill_prefix |
必需。溢出桶密钥前缀。 |
spill_put_request_headers |
（可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，{"x-amz-server-side-encryption" :
"AES256"})。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 PutObject。 |
大小写
您可以使用以下大小写参数来设置不同的大小写模式。无论是否使用 Glue 连接，都可以在 Lambda 环境变量中更改连接器的默认大小写模式。
-
大小写模式 –（可选）指定如何处理架构和表名的大小写。
casing_mode参数使用以下值来指定大小写行为：-
无 – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。
-
注释 – 如果存在注释，则调整表名。对于未关联 Glue 连接的连接器，这是默认设置。
-
搜索不区分大小写 – 对 Snowflake 中的架构和表名执行不区分大小写的搜索。如果查询包含的架构或表名与连接器的默认大小写模式不一致，请使用此值。
-
数据类型支持
下表显示了适用于 JDBC 和 Apache Arrow 的相应数据类型。
| JDBC | Arrow |
|---|---|
| 布尔值 | 位 |
| 整数 | Tiny |
| 短型 | Smallint |
| 整数 | Int |
| 长整型 | Bigint |
| float | 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
其他资源
有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 Snowflake 连接器的 pom.xml
有关此连接器的更多信息，请访问 GitHub.com 上的相应站点
