在 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 启用工作区。

计算要求:

  • 从 Databricks Runtime 群集或 SQL 仓库到目标数据库系统的网络连接。 请参阅 Lakehouse Federation 网络建议
  • Azure Databricks 群集必须使用 Databricks Runtime 13.3 LTS(或更高版本)和共享或单用户访问模式。
  • SQL 仓库必须是专业版,并且必须使用 2023.40 或更高版本。

所需的权限:

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

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

  • 如果你打算使用 OAuth 进行身份验证,请在 Snowflake 控制台中创建安全集成。 有关详细信息,请参阅以下部分。

(可选)在 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;

创建连接

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

注意

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

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

目录资源管理器

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

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

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

  3. 输入用户友好的连接名称

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

  5. 为 Snowflake 仓库输入以下连接属性。

    • 身份验证类型OAuthUsername and password
    • 主机:例如 snowflake-demo.cn-north-2.azure.snowflakecomputing.com
    • 端口:例如 443
    • Snowflake 仓库:例如 my-snowflake-warehouse
    • 用户:例如 snowflake-user
    • (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) 客户端范围refresh_token session:role:<role-name>。 指定要在<role-name>中使用的 Snowflake 角色。
    • (用户名和密码)密码:例如,password123

    (OAuth) 系统会提示你使用 OAuth 凭据登录到 Snowflake。

  6. (可选)单击“测试连接”以确认它是否正常工作。

  7. (可选)添加注释。

  8. 单击“创建”。

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>')
)

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

创建外部目录

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

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

注意

你还可以使用 Databricks REST API 或 Databricks CLI 来创建目录。 请参阅 POST /api/2.1/unity-catalog/catalogsUnity 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 范围的一部分。

其他资源