通过

在 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 用户对数据库的访问。

可以使用数据库联合或目录联合在 Snowflake 上运行联合查询。 请参阅 使用目录联邦在 Snowflake 上运行联合查询。

在数据库联合中，JDBC 将 Unity 目录查询向下推送到外部数据库。 这非常适合对您的 ETL 管道进行临时报告或概念验证工作。

在目录联合中，Unity 目录查询直接针对文件存储运行。 此方法有助于增量迁移，无需修改代码，或作为一种长期混合数据管理模型，适用于需要在 Snowflake 中与 Unity 目录中注册的数据一起维护数据的组织。

使用数据库联邦在 Snowflake 上运行联邦查询

准备工作

工作区要求：

  • 已为 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 类型
小数、数字、数值 十进制类型
bigint、byteint、int、integer、smallint、tinyint 整数类型
float、float4、float8 浮点类型
double、double precision、real DoubleType
char、character、string、text、time、varchar 字符串类型
二进制 二进制类型
布尔 BooleanType
日期 日期类型
datetime、timestamp、timestamp_ltz、timestamp_ntz、timestamp_tz 时间戳类型

OAuth 限制

以下是 OAuth 支持限制：

  • 必须可通过 Azure Databricks 的控制平面 IP 访问 Snowflake OAuth 终结点。 请参阅从 Azure Databricks 控制平面出站。 Snowflake 支持在安全集成级别配置网络策略，该策略允许使用单独的网络策略，以便从 Azure 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 上运行联合查询：

  • 满足与 Snowflake Horizon 目录进行联邦集成的要求。 请参阅 要求。
  • 使用 Databricks Runtime 16.4 LTS 或更高版本，或 Databricks SQL。

设置目录联合管理

设置目录联合的步骤类似于设置数据库联合。 但是，您还必须为在 Snowflake 中注册的 Apache Iceberg 表路径创建存储凭据和外部位置。

  1. 为 Iceberg 表创建外部存储位置。

    必须在 Unity Catalog 中配置一个外部位置，以管理对存储在 Snowflake 数据库中注册的 Iceberg 表的云存储位置的访问。 外部位置是 Unity Catalog 的安全对象，用于将存储凭据与云存储容器路径关联。 请参阅 存储凭据和外部位置。

    可以创建外部位置：

    此外部位置将在步骤 3 中被指定为授权路径，并作为外部目录配置的一部分。

  2. 与数据库联合类似，请创建与 Snowflake Horizon 目录的连接。

  3. 类似于数据库联盟，创建一个外部目录。 必须在云存储中指定一个位置，来存储此目录中的 Iceberg 表的元数据。

    在目录中配置存储位置后，可以通过对象存储在外部目录中读取 Iceberg 表。 通过 JDBC 协议读取或写入 Iceberg 表将不再可用（不会影响非冰山表）。

    还必须添加 授权路径，即可通过目录访问的云存储路径。 只有属于这些路径的表才能通过联合目录查询。 路径必须由外部位置覆盖。

确定外部 Snowflake 表是使用目录还是数据库联合

使用目录联邦读取的外部 Snowflake 表将在目录资源管理器中显示 Iceberg 源格式。 使用数据库联合读取的 Iceberg 表将在目录资源管理器中显示 Snowflake 源格式。

联合雪花目录可以包含 Snowflake 内置表和 Iceberg 表。 将通过使用 Snowflake 计算的数据库联邦来执行针对具有两种存储格式的表的查询。

已知的限制

使用目录联合在 Snowflake 上运行联合查询具有以下限制：

  • 某些冰山表只能使用数据库联合进行读取。
    • 具有 URI 不兼容位置（包含特殊字符）的表。
    • 表的元数据位置位于表位置之外。
    • 具有不受支持的方案的位置的表格（仅支持s3、s3a、s3n、abfs、abfss、gs、r2、wasb和wasbs）。
  • 名称相同（不区分大小写）的表发生冲突。 首先加载的是第一个出现的表。
  • 对于 Azure，Snowflake Iceberg 表不能位于容器的根位置。

有关 Iceberg 的相关限制，请参阅 Iceberg 表限制。

其他资源

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