在 Snowflake 上运行联合查询

本文介绍如何设置 Azure Databricks Lakehouse Federation，以便对不受 Azure Databricks 管理的 Snowflake 数据运行联合查询。 若要详细了解 Lakehouse Federation，请参阅“什么是 Lakehouse Federation？”。

若要使用 Lakehouse Federation 连接到 Snowflake 数据库，必须在 Azure Databricks Unity Catalog 元存储中创建以下内容：

• 与 Snowflake 数据库的连接。
• 一个外部目录，它镜像 Unity Catalog 中的 Snowflake 数据库，以便你可使用 Unity Catalog 查询语法和数据治理工具来管理 Azure Databricks 用户对数据库的访问。

开始之前

工作区要求：

• 已为 Unity Catalog 启用工作区。

计算要求：

• 从计算资源到目标数据库系统的网络连接。 请参阅 Lakehouse Federation 网络建议。
• Azure Databricks 计算必须使用 Databricks Runtime 13.3 LTS（或更高版本）和共享或单用户访问模式。
• SQL 仓库必须是专业或无服务器，并且必须使用 2023.40 或更高版本。

所需的权限：

• 若要创建连接，你必须是元存储管理员或对附加到工作区的 Unity Catalog 元存储具有 CREATE CONNECTION 权限的用户。
• 若要创建外部目录，必须对元存储具有 CREATE CATALOG 权限，并且是连接的所有者或对连接具有 CREATE FOREIGN CATALOG 特权。

后面每个基于任务的部分都指定了其他权限要求。

• 如果你打算使用 OAuth 进行身份验证，请在 Snowflake 控制台中创建安全集成。
• 如果计划使用 OAuth 访问令牌进行身份验证，则还必须请求访问令牌。

（可选）在 Snowflake 控制台中创建安全集成

如果你要使用 OAuth 进行身份验证，请在创建 Snowflake 连接之前执行此步骤。 要改用用户名和密码进行身份验证，请跳过本部分。

注意

仅支持 Snowflake 的内置 OAuth 集成。 不支持外部 OAuth 集成，例如 Okta 或 Microsoft Entra ID。

在 Snowflake 控制台中，运行CREATE SECURITY INTEGRATION。 请替换以下值：

• <integration-name>：OAuth 集成的唯一名称。

• <workspace-url>：Azure Databricks 工作区 URL。 必须将OAUTH_REDIRECT_URI设置为https://<workspace-url>/login/oauth/snowflake.html，其中<workspace-url>是创建 Snowflake 连接的 Azure Databricks 工作区的唯一 URL。

• <duration-in-seconds>：刷新令牌的时间长度。

  重要

  OAUTH_REFRESH_TOKEN_VALIDITY是默认设置为 90 天的自定义字段。 刷新令牌过期后，必须重新对连接进行身份验证。 将字段设置为合理的时间长度。

CREATE SECURITY INTEGRATION <integration-name>
TYPE = oauth
ENABLED = true
OAUTH_CLIENT = custom
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://<workspace-url>/login/oauth/snowflake.html'
OAUTH_ISSUE_REFRESH_TOKENS = TRUE
OAUTH_REFRESH_TOKEN_VALIDITY = <duration-in-seconds>
OAUTH_ENFORCE_PKCE = TRUE;

（可选）请求 OAuth 访问令牌

按照 Snowflake 知识库中的操作方法：使用 Snowflake OAuth 为自定义客户端生成和使用 OAuth 令牌执行操作。

创建连接

连接指定用于访问外部数据库系统的路径和凭据。 若要创建连接，可以使用目录资源管理器，或者使用 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 CREATE CONNECTION SQL 命令。

注意

你还可以使用 Databricks REST API 或 Databricks CLI 来创建连接。 请参阅 POST /api/2.1/unity-catalog/connections 和 Unity Catalog 命令。

所需的权限：具有 CREATE CONNECTION 特权的元存储管理员或用户。

目录资源管理器

1. 在 Azure Databricks 工作区中，单击 “目录”。

2. 在“目录”窗格顶部，单击 “添加”图标，然后从菜单中选择“添加连接”。

   也可在“快速访问”页中单击“外部数据 >”按钮，转到“连接”选项卡，然后单击“创建连接”。

3. 在“设置连接”向导的“连接基本信息”页面上，输入用户友好的连接名称。

4. 选择 Snowflake 的“连接类型”。

5. 对于 身份验证类型，请从下拉菜单中选择 Username and password（基本身份验证）、OAuth access token、PEM Private Key或 OAuth。

6. （可选）添加注释。

7. 单击“下一步”。

8. 输入 Snowflake 仓库的以下身份验证和连接详细信息。 特定于所选身份验证方法的属性前面是括号中的 Auth type。

   • 主机：例如 snowflake-demo.east-us-2.azure.snowflakecomputing.com

   • 端口：例如 443

   • 用户：例如 snowflake-user

   • （基本身份验证）密码：例如，password123

   • （OAuth 访问令牌）访问令牌：来自 的访问令牌（可选）请求 OAuth 访问令牌。

   • （OAuth 访问令牌）过期时间（以秒为单位）：（可选）请求 OAuth 访问令牌 (expires_in) 中的访问令牌的过期时间（以秒为单位）。

   • （OAuth） 客户端 ID：在 Snowflake 控制台中，运行 SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') 以检索安全集成的客户端 ID。

   • （OAuth） 客户端密码：在 Snowflake 控制台中，运行 SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') 以检索安全集成的客户端密码。

   • （OAuth） OAuth 范围：refresh_token session:role:<role-name>。 指定要在<role-name>中使用的 Snowflake 角色。

   • （OAuth） 使用 Snowflake登录：使用 OAuth 凭据单击并登录到 Snowflake。

   • （PEM 私钥）PEM 私钥：以 HEX64 格式表示的 RSA 密钥对中的私钥。

   • （PEM 私钥）以秒为单位过期：与私钥建立的连接过期时间（以秒为单位）。

     成功登录后，将定向回“设置连接”向导。

9. 单击 创建连接。

10. （基本身份验证）在 连接详细信息 页上，指定以下内容：

    • Snowflake 仓库：例如 my-snowflake-warehouse
    • （可选）代理主机：用于连接到 Snowflake 的代理的主机。 还必须选择 使用代理 并指定 代理端口。
    • （可选）使用代理：是否使用代理服务器连接到 Snowflake。
    • （可选）代理端口：用于连接到 Snowflake 的代理的端口。 还必须选择 使用代理 并指定 代理主机。
    • （可选） Snowflake 角色：连接后用于会话的默认安全角色。

11. 单击“下一步”。

12. 在 目录基础 页上，输入外国目录的名称。 外部目录镜像外部数据系统中的数据库，以便可以使用 Azure Databricks 和 Unity Catalog 查询和管理对该数据库中数据的访问。

13. （可选）单击“测试连接”以确认它是否正常工作。

14. 单击 创建目录。

15. 在“访问权限”页上，选择用户可以在其中访问所创建的目录的工作区。 可以选择 让所有工作区都有访问权限，或单击 分配给工作区，选择工作区，然后单击 分配。

16. 更改 所有者，使其能够管理对目录中所有对象的访问。 开始在文本框中键入主体，然后单击返回的结果中的主体。

17. 授予对目录的“权限”。 单击“授权”：

    1. 指定 主体 谁有权访问目录中的对象。 开始在文本框中键入主体，然后单击返回的结果中的主体。
    2. 选择“特权预设”以对每个主体授权。 默认情况下，向所有帐户用户授予 BROWSE。
       • 从下拉菜单中选择 数据读取器，以授予对目录中对象的 read 特权。
       • 从下拉菜单中选择 数据编辑器，以授予对目录中对象的 read 和 modify 权限。
       • 手动选择要授予的权限。
    3. 单击“授权”。

18. 单击“下一步”。

19. 在“元数据”页上，指定标记键值对。 有关详细信息，请参阅 将标记应用于 Unity 目录安全对象。

20. （可选）添加注释。

21. 单击 保存。

SQL

在笔记本或 Databricks SQL 查询编辑器中运行以下命令。

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user '<user>',
  password '<password>'
);

建议对凭据等敏感值使用 Azure Databricks 机密而不是纯文本字符串。 例如：

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>')
)

有关设置机密的详细信息，请参阅机密管理。

创建外部目录

注意

如果使用 UI 创建与数据源的连接，则包含外部目录创建，你可以跳过此步骤。

外部目录镜像外部数据系统中的数据库，以便可以使用 Azure Databricks 和 Unity Catalog 查询和管理对该数据库中数据的访问。 若要创建外部目录，请使用与已定义的数据源的连接。

要创建外部目录，可以使用目录资源管理器，或在 Azure Databricks 笔记本或 SQL 查询编辑器中使用 CREATE FOREIGN CATALOG SQL 命令。

你还可以使用 Databricks REST API 或 Databricks CLI 来创建目录。 请参阅 POST /api/2.1/unity-catalog/catalogs 和 Unity Catalog 命令。

所需的权限：对元存储具有 CREATE CATALOG 权限，并且具有连接的所有权或对连接具有 CREATE FOREIGN CATALOG 权限。

目录资源管理器

1. 在 Azure Databricks 工作区中，单击 “目录”以打开目录资源管理器。

2. 在“目录”窗格顶部，单击 “添加”图标，然后从菜单中选择“添加目录”。

   也可在“快速访问”页中单击“目录”按钮，然后单击“创建目录”按钮。

3. 按照创建目录中的说明创建外部目录。

SQL

在笔记本或 SQL 查询编辑器中运行以下 SQL 命令。 括号中的项是可选的。 替换占位符值替：

• <catalog-name>：Azure Databricks 中目录的名称。
• <connection-name>：指定数据源、路径和访问凭据的连接对象。
• <database-name>：要在 Azure Databricks 中镜像为目录的数据库的名称。

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (database '<database-name>');

区分大小写的数据库标识符

外部目录的 database 字段映射到 Snowflake 数据库标识符。 如果 Snowflake 数据库标识符不区分大小写，则会保留在外部目录 <database-name> 中使用的大小写。 但是，如果 Snowflake 数据库标识符区分大小写，则必须用双引号将外部目录 <database-name> 括起来以保留大小写。

例如：

• database 转换为 DATABASE

• "database" 转换为 database

• "database""" 转换为 database"

  若要转义双引号，请使用另一个双引号。

• "database"" 会导致出错，因为双引号未正确进行转义。

有关详细信息，请参阅 Snowflake 文档中的标识符要求。

支持的下推

支持以下下推：

• 筛选器
• 投影
• 限制
• 联接
• 聚合（Average、Corr、CovPopulation、CovSample、Count、Max、Min、StddevPop、StddevSamp、Sum、VariancePop、VarianceSamp）
• 函数（字符串函数、数学函数、数据、时间和时间戳函数以及其他杂项函数，例如 Alias、Cast、SortOrder）
• Windows 函数（DenseRank、Rank、RowNumber）
• 排序

数据类型映射

从 Snowflake 读取到 Spark 时，数据类型映射如下：

Snowflake 类型	Spark 类型
小数、数字、数值	DecimalType
bigint、byteint、int、integer、smallint、tinyint	IntegerType
float、float4、float8	FloatType
double、double precision、real	DoubleType
char、character、string、text、time、varchar	StringType
binary	BinaryType
boolean	BooleanType
date	DateType
datetime、timestamp、timestamp_ltz、timestamp_ntz、timestamp_tz	TimestampType

OAuth 限制

以下是 OAuth 支持限制：

• 必须可从 Databricks 控制平面 IP 访问 Snowflake OAuth 终结点。 请参阅从 Azure Databricks 控制平面出站。 Snowflake 支持在安全集成级别配置网络策略，这允许使用单独的网络策略，该策略允许从 Databricks 控制平面直接连接到 OAuth 终结点以进行授权。
• 不支持使用代理、代理主机、代理端口和 Snowflake 角色配置选项。 指定Snowflake 角色作为 OAuth 范围的一部分。

PEM 私钥限制

以下是 PEM 私钥支持限制：

• Snowflake JDBC 驱动程序不支持使用加密私钥进行身份验证。 若要避免错误，请生成添加 -nocrypt 选项的密钥，如下所示：

  openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
  

其他资源

请参阅 Snowflake 文档中的以下文章：

• 为自定义客户端配置 Snowflake OAuth
• SQL 参考：创建安全集成 (Snowflake OAuth)
• Snowflake：密钥对身份验证和密钥对轮换