为外部 Hive 元存储启用 Hive 元存储联合

项目
01/10/2025

重要

此功能目前以公共预览版提供。

本文介绍如何联合外部 Hive 元存储，以便组织使用 Unity Catalog 处理 Hive 元存储表。

有关 Hive 元存储联合的概述，请参阅 Hive 元存储联合：启用 Unity Catalog 来管理 Hive 元存储中注册的表。

开始之前

查看 Hive 元存储联合支持的服务和功能列表：要求、支持的功能和限制。

下文列出了每个步骤的具体要求。

步骤 1：将 Unity Catalog 连接到外部 Hive 元存储

在此步骤中，你将创建作为 Unity Catalog 安全对象的一个连接，该对象指定用于访问数据库系统（本例中为 Hive 元存储）的路径和凭证。

要求

必须满足以下条件：

允许访问托管 Hive 元存储的数据库系统的用户名和密码。
数据库的 URL（主机和端口）。
数据库名称。
Unity Catalog 元存储上的 CREATE CONNECTION 特权。默认情况下，元存储管理员具有此权限。

创建连接

若要创建连接，可以使用目录资源管理器，或者使用 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 CREATE CONNECTION SQL 命令。

注意

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

目录资源管理器

在 Azure Databricks 工作区中，单击 “目录”。
在“快速访问”页面上，单击“添加数据 > 添加连接”。
输入用户友好的连接名称。
选择“Hive 元存储”的“连接类型”和“外部”的“元存储类型”。
输入主机数据库的以下“身份验证”属性。
- 主机：例如 mysql-demo.lb123.cn-north-2.rds.amazonaws.com
- 端口：例如 3306
- 用户：例如 mysql_user
- 密码：例如 password123
输入主机数据库的以下“连接详细信息”。
- 版本：支持的 Hive 元存储版本包括 0.13 和 2.3。
- 数据库：设置要连接到的数据库的名称。
- 数据库类型：例如 MySQL。
（可选）添加注释。

只有在不想使用默认位置时，才需要此项。
单击“创建”。

SQL

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

CREATE CONNECTION <connection-name> TYPE hive_metastore
OPTIONS (
  host '<hostname>',
  port '<port>',
  user '<user>',
  password '<password>',
  database '<database-name>',
  db_type 'MYSQL',
  version '2.3',
);

只有在不想为 Hive 元存储使用默认的 Hive 仓库目录位置时，才包含 warehouse_directory。

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

CREATE CONNECTION <connection-name> TYPE hive_metastore
OPTIONS (
  host '<hostname>',
  port '<port>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>'),
  database '<database-name>',
  db_type 'MYSQL',
  version '2.3'
)

如果必须在笔记本 SQL 命令中使用纯文本字符串，请避免通过使用 \ 将特殊字符（如 $）进行转义来截断字符串。例如：\$。

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

步骤 2：为 Hive 元存储中的数据创建外部位置

在此步骤中，在 Unity Catalog 中配置外部位置，以控制对保存外部 Hive 元存储中所注册数据的云存储位置的访问。

外部位置是将存储凭证与云存储容器路径相关联的 Unity Catalog 安全对象。请参阅外部位置和存储凭证。

要求

有关云存储和 Azure Databricks 权限要求，请参阅创建外部位置以将云存储连接到 Azure Databricks 中的“开始之前”。

用于创建外部位置的选项

Databricks 建议在 Unity Catalog 中创建外部位置的流程取决于你的情况：

如果要联合 Hive 元存储，用于将数据存储在 DBFS 装载中，请使用目录资源管理器创建外部位置，并使用“从 DBFS 装载复制”选项。请参阅使用目录资源管理器手动创建外部位置或在 DBFS 根中为数据创建外部位置。
否则，可使用目录资源管理器或 SQL 命令。请参阅使用目录资源管理器手动创建外部位置或使用 SQL 创建外部位置。

在外部位置启用回退模式

在 Unity Catalog 中创建外部位置后，在启用 Unity Catalog 的计算（单用户、共享或 SQL 仓库）上运行查询时，Unity Catalog 权限将强制访问由该外部位置表示的路径。这会中断没有访问路径正确 Unity Catalog 权限的现有工作负载。

当外部位置处于回退模式时，系统会首先检查查询主体对位置的 Unity Catalog 权限，如果该权限不成功，请回退到使用现有群集或笔记本范围的凭证（例如实例配置文件或 Apache Spark 配置属性），以便现有工作负载继续不间断地运行。

在迁移旧工作负载的过程中，回退模式非常方便。更新工作负载，使其成功使用 Unity Catalog 权限运行后，应禁用回退模式，以防止旧群集范围的凭证被用于绕过 Unity Catalog 数据管理。

可使用目录资源管理器或 Unity Catalog 外部位置 REST API 启用回退模式。

所需权限：外部位置的所有者。

目录资源管理器

在 Azure Databricks 工作区中，单击 “目录”。
在“快速访问”页面上，单击“外部数据 >”。
选择要更新的外部位置。
打开“回退模式”切换，然后单击“启用”以确认。

API

以下 curl 示例演示如何在创建外部位置及更新现有外部位置时启用回退模式。

创建新的外部位置：

curl -X POST -H 'Authorization: Bearer <token>' \
https://<workspace-URL>/api/2.1/unity-catalog/external-locations \
--data
'{
  "name": "fallback_mode_enabled_external_location",
  "url": "abfss://container-name@storage-account.dfs.core.chinacloudapi.cn/external_location_container/url",
  "credential_name": "external_location_credential",
  "fallback": true
  "skip_validation": true
}'

更新外部位置：

curl -X PATCH \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
https://<workspace-URL>/api/2.1/unity-catalog/external-locations/<external-location-name> \
--data
 '{
   "comment": "fallback mode enabled",
   "fallback": true
  }'

步骤 3：创建联合目录

在此步骤中，使用在步骤 1 中创建的连接，在 Unity Catalog 中创建一个联合目录，该目录指向在步骤 2 中创建的外部位置。联合目录是外部目录类型，Unity Catalog 中的安全对象，可镜像外部数据系统中的数据库或目录，使你能够在 Azure Databricks 工作区中对该数据系统执行查询，并由 Unity Catalog 管理访问权限。在这种情况下，镜像目录就是在 Hive 元存储中注册的数据。

只要用户或工作流与联合目录进行交互，元数据就会从 Hive 元存储同步。

要求

权限要求：

创建外部目录：

Unity Catalog 元存储上的 CREATE CATALOG 特权。
连接的所有权或连接的 CREATE FOREIGN CATALOG 特权。
若要输入外部目录的授权路径，必须具有涵盖这些路径的外部位置的 CREATE FOREIGN SECURABLE 特权。默认情况下，外部位置的所有者拥有此特权。

要使用外部目录：

拥有目录或 USE CATALOG 的所有权

计算要求：

若要使用目录资源管理器创建目录：无需计算。
要使用 SQL 创建目录：Databricks Runtime 13.3 LTS 或更高版本。
要使用目录：Databricks Runtime 13.3 LTS、14.3 LTS、15.1 或更高版本上的共享群集。

创建外部目录

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

注意

还可以使用 Unity Catalog API。请参阅 Databricks REST API 参考中的创建目录。

在 Azure Databricks 工作区中，单击 “目录”以打开目录资源管理器。
在“快速访问”页面上，单击“添加数据”按钮并选择“添加目录”。
输入“目录名称”，然后选择“外部”的目录“类型”。
从下拉列表中选择在步骤 1 中创建的连接。
在“授权路径”字段中，输入在步骤 2 中定义为外部位置的云存储位置的路径。例如，abfss://container@storageaccount.dfs.core.chinacloudapi.cn/demo,abfss://container@storageaccount.dfs.core.chinacloudapi.cn/depts/finance。

授权路径仅是联合目录的附加安全层。请参阅什么是授权路径？。
单击 “创建” 。
（可选）单击“配置”以打开一个向导，引导你授予目录权限并添加标记。也可稍后执行这些步骤。

请参阅管理 Unity Catalog 中特权和将标记应用于 Unity Catalog 安全对象。
（可选）将目录绑定到特定工作区。

默认情况下，可从附加到 Unity Catalog 元存储的任何工作区（受用户特权限制）访问目录。如果只想允许从特定工作区进行访问，请转到“工作区”选项卡并分配工作区。请参阅仅限特定工作区能访问目录。
使用 Hive 元存储元数据来填充联合目录。

只要用户或工作流与联合目录进行交互，元数据就会从 Hive 元存储同步。第一个交互填充 Unity Catalog 中的目录，并使其内容在目录资源管理器 UI 中可见。可通过在目录资源管理器中选择和启动受支持的计算资源来填充目录。你必须是目录所有者（由于创建了目录，你就是目录所有者）或具有 USE CATALOG 特权的用户。

在笔记本或 SQL 查询编辑器中运行以下 SQL 命令。括号中的项是可选的。替换占位符值替：
- <catalog-name>：Azure Databricks 中目录的名称。
- <connection-name>：在步骤 1 中创建的连接对象的名称。
- <path1>,<path2>：输入在步骤 2 中定义为外部位置的云存储位置的路径。例如，abfss://container@storageaccount.dfs.core.chinacloudapi.cn/demo,abfss://container@storageaccount.dfs.core.chinacloudapi.cn/depts/finance。授权路径仅是联合目录的附加安全层。请参阅什么是授权路径？。
```
CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (authorized_paths '<path1>,<path2>');
```
只要用户或工作流与联合目录进行交互，元数据就会从 Hive 元存储同步。

另请参阅管理和使用外部目录。

通过

为外部 Hive 元存储启用 Hive 元存储联合

开始之前

步骤 1：将 Unity Catalog 连接到外部 Hive 元存储

要求

创建连接

目录资源管理器

SQL

步骤 2：为 Hive 元存储中的数据创建外部位置

要求

用于创建外部位置的选项

在外部位置启用回退模式

目录资源管理器

API

步骤 3：创建联合目录

要求

创建外部目录

其他资源