在 Snowflake 上执行联合查询（使用 OAuth 访问令牌）

本页介绍如何设置 Lakehouse 联邦查询系统，以对未由 Azure Databricks 管理的 Snowflake 数据运行联邦查询。 若要详细了解 Lakehouse Federation，请参阅 连接到外部数据库和目录

若要使用 Lakehouse 联邦连接到 Snowflake 数据库，必须在 Azure Databricks Unity Catalog 元存储中创建以下内容（2023 年 11 月 9 日之后创建的工作区已自动预配 Unity Catalog 元存储）：

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

本页介绍如何使用 OAuth 访问令牌对 Snowflake 数据运行联合查询。 有关其他身份验证方法，请参阅以下页面：

可以使用查询联合或目录联合在 Snowflake 上运行联合查询。

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

在目录联合中，Unity 目录查询直接针对文件存储运行。 这种方法对于没有代码调整的增量迁移很有帮助，或者对于那些必须在 Unity Catalog 中注册数据的同时在 Snowflake 中维护一些数据的组织来说，这是一个长期的混合模型。 请参阅 启用 Snowflake 数据目录联邦。

在您开始之前

工作区要求：

  • 已为 Unity Catalog 启用工作区。 2023年11月9日之后创建的工作区会自动启用Unity Catalog，包括自动配置元存储。 若您的工作区在自动启用功能推出之前创建且尚未启用 Unity Catalog，则需要手动创建元存储。 请参阅 Unity 目录入门。

计算要求：

  • 计算资源与目标数据库系统之间的网络连接。 请参阅 Lakehouse Federation 网络建议。
  • Azure Databricks 计算必须使用 Databricks Runtime 13.3 LTS 或更高版本以及 标准 或 专用 访问模式。
  • SQL 仓库必须是专业或无服务器，并且必须使用 2023.40 或更高版本。

所需的权限：

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

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

请求 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. 在“设置连接”向导的“连接基本信息”页面上，输入用户友好的连接名称。

  5. 对于 连接类型，请选择 Snowflake。

  6. 对于 身份验证类型， OAuth Access Token 请从下拉菜单中进行选择。

  7. （可选）添加注释。

  8. 单击 “下一步” 。

  9. 在 “身份验证 ”页上输入以下身份验证和连接详细信息。

    • 主机：例如，snowflake-demo.east-us-2.azure.snowflakecomputing.com。
    • 端口：默认值为 443.
    • 用户：使用个人 Snowflake 用户名。
    • 访问令牌：从 请求 OAuth 访问令牌 中获取。
    • （可选） 过期时间（秒）：从请求 OAuth 访问令牌中获取的访问令牌的过期时间（以秒为单位expires_in）。

  10. 单击 “下一步” 。

  11. 在 “连接详细信息 ”页上，输入 Snowflake 仓库的名称。

  12. 如果要使用代理连接到 Snowflake，请选中 “使用代理 ”框并填写所需的详细信息。

  13. 单击“ 创建连接”。

  14. 在 “目录基本信息 ”页上，输入外国目录的名称。

  15. 对于 数据库，请在 Snowflake 中输入数据库名称。 外部目录镜像外部数据系统中的数据库，以便可以使用 Azure Databricks 和 Unity Catalog 查询和管理对该数据库中数据的访问。

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

  17. 单击“创建目录”。

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

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

  20. 授予对目录的“特权”。 单击“授权”：

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

  21. 单击 “下一步” 。

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

  23. （可选）添加注释。

  24. 单击“ 保存”。

SQL

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

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user '<user>',
  access_token '<access-token>',
  expires_in_secs '<expiration-time-in-seconds>'
);

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

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user secret ('<secret-scope>','<secret-key-user>'),
  access_token secret ('<secret-scope>','<secret-key-access-token>'),
  expires_in_secs '<expiration-time-in-seconds>'
)

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

高级连接选项

Snowflake 连接支持以下适用于受限出口或私有连接环境的高级选项：

  • disableOCSPChecks：设置为 true 在 Snowflake JDBC 驱动程序中禁用联机证书状态协议（OCSP）证书吊销检查。 禁用 OCSP 检查会跳过对证书吊销状态的检查。

Important

尽可能允许发往 Snowflake OCSP 响应服务器的出站流量。 请保留 disableOCSPChecks 未设置或将其设置为 false。 仅当您的受限出口或专用连接配置无法允许此流量时，才将其设置为 true。

目录资源管理器中未显示此选项。 可以使用 SQL 创建连接时对其进行设置：

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  <connection-options>,
  disableOCSPChecks 'true'
);

对于现有连接，请使用 ALTER CONNECTION。

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

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

例如：

  • database 转换为 DATABASE

  • "database" 转换为 database

  • "database""" 转换为 database"

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

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

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

支持的下推

支持以下下推：

  • 过滤 器
  • 预测
  • 限度
  • Offset
  • 加入
  • 聚合（Average、Corr、CovPopulation、CovSample、Count、Max、Min、StddevPop、StddevSamp、Sum、VariancePop、VarianceSamp）
  • 函数（字符串函数、数学函数、日期、时间和时间戳函数，以及其他杂项函数，如 Alias、Cast、SortOrder）
  • 窗口函数（DenseRank、Rank、RowNumber）
  • 排序
  • Top-N（将排序和限制合并为单个操作），Databricks Runtime 17.3 及更高版本支持

数据类型映射

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

Snowflake 类型 Spark 类型
decimal、number、numeric 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

局限性

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

其他资源

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

  • Last updated on