创建和管理 Delta Sharing 的共享

本文介绍如何创建和管理 Delta Sharing 的共享。

共享是 Unity Catalog 中的安全对象，可用于与一个或多个接收者共享以下数据资产：

• 表和表分区
• 视图，包括限制行和列级访问的动态视图
• 卷
• 笔记本
• AI 模型

如果共享整个架构（数据库），则接收者可以在共享架构时访问该架构中的所有表、视图、模型和卷，以及将来添加到该架构中的任何数据和 AI 资产。

一个共享只能包含一个 Unity Catalog 元存储中的数据和 AI 资产。 可随时添加或删除共享中的数据和 AI 资产。

有关详细信息，请参阅《共享、提供商和收件人》。

要求

若要创建共享，你必须：

• 是元存储管理员，或者对要共享的数据所要注册到的 Unity Catalog 元存储拥有 CREATE SHARE 特权。
• 使用附加了 Unity Catalog 元存储的 Azure Databricks 工作区创建共享。

若要将表或视图添加到共享，你必须：

• 是共享所有者。
• 对包含表或视图的目录和架构具有 USE CATALOG 和 USE SCHEMA 特权，或者拥有目录或架构的所有权。
• 对表或视图拥有 SELECT 特权。 必须保留该特权才能继续共享表或视图。 如果丢失该特权，则收件人无法通过共享访问表或视图。 因此，Databricks 建议使用组作为共享所有者。

若要将卷添加到共享，你必须：

• 是共享所有者。
• 对包含卷的目录和架构具有 USE CATALOG 和 USE SCHEMA 特权，或者拥有目录或架构的所有权。
• 对卷具有 READ VOLUME 特权。 你必须保留该特权才能继续共享卷。 如果丢失，则接收者无法通过共享访问该卷。 因此，Databricks 建议使用组作为共享所有者。

若要将模型添加到共享，你必须：

• 是共享所有者。
• 对包含模型的目录和架构具有 USE CATALOG 和 USE SCHEMA 特权，或者拥有目录或架构的所有权。
• 对模型具有 EXECUTE 特权。 必须保留该特权才能继续共享模型。 如果失去该特权，则收件人无法通过共享访问模型。 因此，Databricks 建议使用组作为共享所有者。

若要共享整个架构，你必须：

• 是共享所有者和架构所有者，或者具有 USE SCHEMA.
• 对架构具有 SELECT，可共享表。
• 对架构具有 READ VOLUME，可共享卷。

若要将笔记本文件添加到共享，你必须：

• 是共享所有者，并且拥有笔记本的“可读”权限。

若要授予对共享的接收者访问权限，你必须是以下角色之一：

• 元存储管理员。
• 对共享和接收者对象（(USE SHARE + SET SHARE PERMISSION) 或共享所有者）和（USE RECIPIENT 或接收者所有者）拥有委托权限或所有权的用户。

若要查看共享，你必须是以下角色之一：

• 元存储管理员（可查看所有对象）
• 拥有 USE SHARE 特权的用户（可查看所有对象）
• 共享对象所有者

计算要求：

• 如果你使用 Databricks 笔记本创建共享，则群集必须使用 Databricks Runtime 11.3 LTS 或更高版本以及共享或单用户群集访问模式。
• 如果使用 SQL 声明向共享添加架构（或者更新或删除架构），则必须使用运行 Databricks Runtime 13.3 LTS 或更高版本的 SQL 仓库或计算。 使用目录资源管理器执行相同操作没有计算要求。

创建共享对象

若要创建共享，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 CREATE SHARE SQL 命令。

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

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，单击“共享数据”按钮。

4. 在“创建共享”页上，输入共享名称和可选注释。

5. 单击“保存并继续”。

   可以继续添加数据资产，也可以停止并稍后返回。

6. 在“添加数据资产”选项卡上，选择要共享的表、卷、视图和模型。

   有关详细说明，请参阅：

   • 将表添加到共享
   • 将卷添加到共享
   • 将视图添加到共享
   • 将模型添加到共享

7. 单击“保存并继续”。

8. 在“添加笔记本”选项卡上，选择要共享的笔记本。

   有关详细说明，请参阅将笔记本文件添加到共享。

9. 单击“保存并继续”。

10. 在“添加收件人”选项卡上，选择要与之共享的收件人。

    有关详细说明，请参阅管理对 Delta Sharing 数据共享的访问权限（适用于提供者）。

11. 单击“共享数据”以与收件人共享数据。

SQL

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

CREATE SHARE [IF NOT EXISTS] <share-name>
[COMMENT "<comment>"];

现在可以向共享添加表、卷、视图和模型。

有关详细说明，请参阅：

• 将表添加到共享
• 将卷添加到共享
• 将视图添加到共享
• 将模型添加到共享

CLI

使用 Databricks CLI 运行以下命令。

databricks shares create <share-name>

可以使用 --comment 添加注释或用 --json 向共享添加资产。 有关详细信息，请参阅以下部分。

现在可以向共享添加表、卷、视图和模型。

有关详细说明，请参阅：

• 将表添加到共享
• 将卷添加到共享
• 将视图添加到共享
• 将模型添加到共享

将表添加到共享

若要将表添加到共享，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SQL 命令。

所需权限：共享对象的所有者，对包含表的目录和架构拥有 USE CATALOG 和 USE SCHEMA 特权，并对表拥有 SELECT 特权。 必须拥有 SELECT 特权才能共享表。 有关详细信息，请参阅要求。

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到要向其添加表的共享，然后单击其名称。

4. 单击“管理资产”>“添加数据资产”。

5. 在“添加表”页面，选择整个架构（数据库）或单个表和视图。

   • 若要选择某个表或视图，请先选择目录，然后选择包含相应表或视图的架构，再然后是相应的表或视图本身。

     可以使用工作区搜索，按名称、列名或注释来搜索表。 请参阅搜索工作区项目。

   • 若要选择架构，先选择目录，然后选择架构。

     有关共享架构的详细信息，请参阅向共享添加架构。

6. （可选）单击“高级表选项”以指定以下选项。 如果选择整个架构，则别名和分区不可用。 如果选择整个架构，则默认包含表历史记录。

   • 别名：备用表名，使表名更具可读性。 别名是收件人明白且必须在查询中使用的表名称。 如果指定了别名，则收件人不能使用实际表名。

   • 分区：仅共享表的一部分。 例如 (column = 'value')。 请参阅指定要共享的表分区和使用接收者属性执行分区筛选。

   • 历史记录共享：共享表历史记录，以便接收者能够执行“按时间顺序查看”查询或使用 Spark 结构化流式处理来读取表。 需要 Databricks Runtime 12.2 LTS 或更高版本。

     注意

     如果除了执行时间旅行查询和流式读取之外，你还希望客户能够使用 table_changes() 函数查询表的更改数据源 (CDF)，则必须在共享表的 WITH HISTORY 之前启用表上的 CDF。

7. 单击“保存” 。

SQL

在笔记本或 Databricks SQL 查询编辑器中运行以下命令来添加表：

ALTER SHARE <share-name> ADD TABLE <catalog-name>.<schema-name>.<table-name>  [COMMENT "<comment>"]
   [PARTITION(<clause>)] [AS <alias>]
   [WITH HISTORY | WITHOUT HISTORY];

运行以下命令来添加整个架构。 ADD SCHEMA 命令要求使用运行 Databricks Runtime 13.3 LTS 或更高版本的 SQL 仓库或计算。 有关共享架构的详细信息，请参阅向共享添加架构。

ALTER SHARE <share-name> ADD SCHEMA <catalog-name>.<schema-name>
[COMMENT "<comment>"];

具有下列选项。 如果选择整个架构，则 PARTITION 和 AS <alias> 不可用。 如果选择整个架构，则所有表默认选择 WITH HISTORY。

• PARTITION(<clause>)：如果只想共享表的一部分，可以指定分区。 例如 (column = 'value')。请参阅指定要共享的表分区和使用接收者属性执行分区筛选。

• AS <alias>：备用表名或别名，使表名更具可读性。 别名是收件人明白且必须在查询中使用的表名称。 如果指定了别名，则收件人不能使用实际表名。 使用格式 <schema-name>.<table-name>。

• WITH HISTORY 或 WITHOUT HISTORY：指定 WITH HISTORY 后，将共享包含完整历史记录的表，使接收者能够执行“按时间顺序查看”查询和流式读取。 表共享的默认行为是 WITHOUT HISTORY，架构共享的默认行为是 WITH HISTORY。 需要 Databricks Runtime 12.2 LTS 或更高版本。

  注意

  如果除了执行时间旅行查询和流式读取之外，你还希望客户能够使用 table_changes() 函数查询表的更改数据源 (CDF)，则必须在共享表的 WITH HISTORY 之前启用表上的 CDF。

有关 ALTER SHARE 选项的详细信息，请参阅 ALTER SHARE。

CLI

使用 Databricks CLI 运行以下命令来添加表。

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "ADD",
        "data_object": {
          "name": "<table-full-name>",
          "data_object_type": "TABLE",
          "shared_as": "<table-alias>"
        }
      }
    ]
  }'

若要添加架构，请运行以下 Databricks CLI 命令：

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "ADD",
        "data_object": {
          "name": "<schema-full-name>",
          "data_object_type": "SCHEMA"
        }
      }
    ]
  }'

若要了解此示例中列出的选项，请查看 SQL 选项卡上的说明。

若要了解其他参数，请运行 databricks shares update --help 或查看 REST API 参考中的 PATCH /api/2.1/unity-catalog/shares/。

有关从共享中删除表的信息，请参阅更新共享。

指定要共享的表分区

若要在将表添加到共享时仅共享表的一部分，可提供分区规范。 在将表添加到共享或更新共享时，可以使用目录资源管理器、Databricks Unity Catalog CLI 或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SQL 命令指定分区。 请参阅将表添加到共享和更新共享。

基本示例

以下 SQL 示例共享 inventoryyear 表中的部分数据，该表按 month 和 date 列分区：

• 2021 年的数据。
• 2020 年 12 月的数据。
• 2019 年 12 月 25 日的数据。

ALTER SHARE share_name
ADD TABLE inventory
PARTITION (year = "2021"),
          (year = "2020", month = "Dec"),
          (year = "2019", month = "Dec", date = "2019-12-25");

使用接收者属性执行分区筛选

可以共享与数据接收者属性匹配的表分区，这也称为参数化分区共享。

默认属性包括：

• databricks.accountId：数据接收者所属的 Azure Databricks 帐户（仅适用于 Databricks 到 Databricks 共享）。
• databricks.metastoreId：数据接收者所属的 Unity Catalog 元存储（仅适用于 Databricks 到 Databricks 共享）。
• databricks.name：数据接收者的名称。

在创建或更新接收者时，可以创建所需的任何自定义属性。

按接收者属性进行筛选可以使用同一共享在多个 Databricks 帐户、工作区和用户之间共享相同的表，同时在共享目标之间保留数据边界。

例如，如果表包含一个 Azure Databricks 帐户 ID 列，则你可以使用按 Azure Databricks 帐户 ID 定义的表分区创建单个共享。 当你共享时，Delta Sharing 仅向每个接收者动态传送与其 Azure Databricks 帐户关联的数据。

如果无法按属性动态分区，则必须为每个接收者单独创建一个共享。

若要在创建或更新共享时指定按接收者属性筛选的分区，可以使用目录资源管理器，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 CURRENT_RECIPIENT SQL 函数：

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到要更新的共享，然后单击其名称。

4. 单击“管理资产”>“添加数据资产”。

5. 在“添加表”页上，选择包含该表的目录和数据库，然后选择该表。

   如果你不确定哪个目录和数据库包含表，可以使用工作区搜索按名称、列名或注释进行搜索。 请参阅搜索工作区项目。

6. （可选）单击“高级表选项”以添加“分区”规范。

   在“将分区添加到表”对话框中，使用以下语法添加基于属性的分区规范：

   (<column-name> = CURRENT_RECIPIENT().<property-key>)
   

   例如，

   (country = CURRENT_RECIPIENT().'country')
   

7. 单击“保存” 。

SQL

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

ALTER SHARE <share-name> ADD TABLE <catalog-name>.<schema-name>.<table-name>
   PARTITION (<column-name> = CURRENT_RECIPIENT().<property-key>);

例如，

ALTER SHARE acme ADD TABLE acme.default.some_table
  PARTITION (country = CURRENT_RECIPIENT().'country');

将具有删除矢量或列映射的表添加到共享

删除向量是可在 Delta 表上启用的一项存储优化功能。 请参阅什么是删除向量？。

Azure Databricks 还支持 Delta 表的列映射。 请参阅使用 Delta Lake 列映射重命名和删除列。

若要共享具有删除矢量或列映射的表，必须将该表与历史记录一起共享。 请参阅将表添加到共享。

共享具有删除矢量或列映射的表时，接收者可通过 SQL 仓库、运行 Databricks Runtime 14.1 或更高版本的群集、或者通过运行开源 delta-sharing-spark 3.1 或更高版本的计算来读取该表。 请参阅读取启用了删除矢量或列映射的表和读取启用了删除矢量或列映射的表。

向共享添加视图

视图是从一个或多个表或其他视图创建的只读对象。 可以从包含在 Unity Catalog 元存储中的多个架构和目录中的表和其他视图创建视图。 请参阅创建和管理视图。

本部分介绍如何使用 Catalog Explorer、Databricks CLI 或 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SQL 命令向共享添加视图。 如果你倾向于使用 Unity Catalog REST API，请参阅 REST API 参考中的 PATCH /api/2.1/unity-catalog/shares/。

所需权限：共享对象的所有者，对包含视图的目录和架构拥有 USE CATALOG 和 USE SCHEMA 特权，并对视图拥有 SELECT 特权。 必须拥有 SELECT 特权才能共享视图。 有关详细信息，请参阅要求。

附加要求：

• 视图共享仅在 Databricks 到 Databricks 共享中受支持。
• 必须在 Delta 表或其他可共享视图上定义可共享视图。
• 不能共享引用共享表或共享视图的视图。
• 向共享添加视图时，必须在 Databricks Runtime 13.3 LTS 或更高版本上使用 SQL 仓库或群集。
• 有关收件人使用视图的要求和限制，请参阅读取共享视图。

若要向共享添加视图，请执行以下操作：

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到要向其添加视图的共享，然后单击其名称。

4. 单击“管理资产”>“添加数据资产”。

5. 在“添加表”页上，搜索或浏览要共享的视图并将其选中。

6. （可选）单击“高级表选项”以指定“别名”或备用视图名称，使视图名称更具可读性。 别名是收件人明白且必须在查询中使用的名称。 如果指定了别名，则收件人不能使用实际视图名称。

7. 单击“保存” 。

SQL

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

ALTER SHARE <share-name> ADD VIEW <catalog-name>.<schema-name>.<view-name>
   [COMMENT "<comment>"]
   [AS <alias>];

选项包括：

• AS <alias>：备用视图名称或别名，以使视图名称更具可读性。 别名是收件人明白且必须在查询中使用的视图名称。 如果指定了别名，则收件人不能使用实际视图名称。 使用格式 <schema-name>.<view-name>。
• COMMENT "<comment>"：注释显示在目录资源管理器 UI 中，当你使用 SQL 语句列出和显示视图详细信息时也会出现注释。

有关 ALTER SHARE 选项的详细信息，请参阅 ALTER SHARE。

CLI

运行以下 Databricks CLI 命令：

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "ADD",
        "data_object": {
          "name": "<view-full-name>",
          "data_object_type": "VIEW",
          "shared_as": "<view-alias>"
        }
      }
    ]
  }'

"shared_as": "<view-alias>" 是可选的，它提供备用视图名称或别名，使视图名称更易读。 别名是收件人明白且必须在查询中使用的视图名称。 如果指定了别名，则收件人不能使用实际视图名称。 使用格式 <schema-name>.<view-name>。

若要了解其他参数，请运行 databricks shares update --help 或查看 REST API 参考中的 PATCH /api/2.1/unity-catalog/shares/。

有关从共享中移除视图的信息，请参阅更新共享。

向共享中添加动态视图以筛选行和列

可以使用动态视图配置对表数据的细粒度访问控制，包括：

• 列或行级别的安全性。
• 数据掩码。

创建使用 CURRENT_RECIPIENT() 函数的动态视图时，可以根据在收件人定义中指定的属性限制收件人访问权限。

本部分通过相关示例介绍如何使用动态视图限制收件人在行和列级别的表数据访问权限。

要求

• Databricks Runtime 版本：Databricks Runtime 14.2 及以上版本中支持 CURRENT_RECIPIENT 函数。
• 权限：
  • 若要创建视图，你需为共享对象的所有者，在包含视图的目录和架构上具有 USE CATALOG 和 USE SCHEMA，对视图具有 SELECT。 必须拥有 SELECT 特权才能共享视图。
  • 若要设置收件人的属性，你需为收件人对象的所有者。
• 限制：视图共享的所有限制，包括 Databricks 到 Databricks 共享的限制，以及以下限制：
  • 当提供程序共享使用 CURRENT_RECIPIENT 函数的视图时，由于共享上下文的原因，提供程序无法直接查询该视图。 若要测试此类动态视图，提供程序须与自己共享视图并以收件人身份查询视图。
  • 提供程序无法创建引用动态视图的视图。

设置收件人属性

在这些示例中，要共享的表具有一个名为 country 的列，只有具有匹配的 country 属性的收件人才能查看特定行或列。

可在 Azure Databricks 笔记本或 SQL 查询编辑器中使用目录资源管理器或 SQL 命令设置收件人属性。

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“收件人”选项卡上，找到要向其添加属性的收件人，然后单击其名称。

4. 单击“编辑属性”。

5. 在“编辑收件人属性”对话框中，输入列名称作为键（在本例中为 country），并输入要按其筛选的值（例如，CA）。

6. 单击“ 保存”。

SQL

若要设置收件人的属性，使用 ALTER RECIPIENT。 在此示例中，country 属性设置为 CA。

ALTER RECIPIENT recipient1 SET PROPERTIES ('country' = 'CA');

创建对收件人设置了行级权限的动态视图

在此示例中，只有具有匹配的 country 属性的收件人才能查看某些行。

CREATE VIEW my_catalog.default.view1 AS
  SELECT * FROM my_catalog.default.my_table
  WHERE country = CURRENT_RECIPIENT('country');

另一种做法是让数据提供程序保留独立的映射表，该表将事实数据表字段映射到收件人属性，从而允许将收件人属性与事实数据表字段解耦，可提供更大的灵活性。

创建对收件人设置了列级权限的动态视图

在此示例中，只有匹配 country 属性的收件人才能查看某些列。 其他人看到的返回的数据是 REDACTED：

CREATE VIEW my_catalog.default.view2 AS
  SELECT
  CASE
    WHEN CURRENT_RECIPIENT('country') = 'US' THEN pii
    ELSE 'REDACTED'
  END AS pii
  FROM my_catalog.default.my_table;

与收件人共享动态视图

若要与收件人共享动态视图，请使用与标准视图所用相同的 SQL 命令或 UI 过程。 请参阅向共享添加视图。

将卷添加到共享

卷是 Unity Catalog 对象，表示云对象存储位置中的逻辑存储卷。 它们主要用于提供对非表格数据资产的治理。 请参阅“什么是 Unity Catalog 卷？”。

本部分介绍如何使用 Catalog Explorer、Databricks CLI 或 Azure Databricks 笔记本或 SQL 查询编辑器中的 SQL 命令向共享添加卷。 如果你倾向于使用 Unity Catalog REST API，请参阅 REST API 参考中的 PATCH /api/2.1/unity-catalog/shares/。

所需权限：共享对象的所有者，对包含卷的目录和架构拥有 USE CATALOG 和 USE SCHEMA 特权，并对卷拥有 READ VOLUME 特权。 必须拥有 READ VOLUME 特权才能共享卷。 有关详细信息，请参阅要求。

附加要求：

• 卷共享仅在 Databricks 到 Databricks 共享中受支持。
• 向共享添加卷时，必须使用 2023.50 或更高版本的 SQL 仓库或 Databricks Runtime 14.1 或更高版本上的群集。
• 如果提供程序端的卷存储具有自定义网络配置（例如防火墙或专用链接），则提供程序必须确保接收方的控制平面和数据平面地址已正确列入允许列表，以便能够连接到卷的存储位置。

向共享添加卷：

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到要向其添加卷的共享，然后单击其名称。

4. 单击“管理资产 > 编辑资产”。

5. 在“编辑资产”页上，搜索或浏览到要共享的卷并将其选中。

   或者，可以选择包含卷的整个架构。 请参阅向共享添加架构。

6. （可选）单击“高级选项”指定备用卷名称或别名，使卷名称更易读。

   如果选择整个架构，则别名不可用。

   别名是收件人明白且必须在查询中使用的名称。 如果某个别名已被指定，则接收者不能使用实际的卷名称。

7. 单击“保存” 。

SQL

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

ALTER SHARE <share-name> ADD VOLUME <catalog-name>.<schema-name>.<volume-name>
   [COMMENT "<comment>"]
   [AS <alias>];

选项包括：

• AS <alias>：备用卷名称或别名，使卷名称更易读。 别名是接收者会看到且必须在查询中使用的卷名称。 如果某个别名已被指定，则接收者不能使用实际的卷名称。 使用格式 <schema-name>.<volume-name>。
• COMMENT "<comment>"：注释显示在 Catalog Explorer UI 中，当你使用 SQL 语句列出和显示卷详细信息时也会出现注释。

有关 ALTER SHARE 选项的详细信息，请参阅 ALTER SHARE。

CLI

使用 Databricks CLI 0.210 或更高版本运行以下命令：

 databricks shares update <share-name> \
   --json '{
     "updates": [
       {
         "action": "ADD",
         "data_object": {
           "name": "<volume-full-name>",
           "data_object_type": "VOLUME",
           "string_shared_as": "<volume-alias>"
         }
       }
     ]
   }'

"string_shared_as": "<volume-alias>" 是可选的，它提供备用卷名称或别名，使卷名称更易读。 别名是接收者会看到且必须在查询中使用的卷名称。 如果某个别名已被指定，则接收者不能使用实际的卷名称。 使用格式 <schema-name>.<volume-name>。

若要了解其他参数，请运行 databricks shares update --help 或查看 REST API 参考中的 PATCH /api/2.1/unity-catalog/shares/。

有关从共享中移除卷的信息，请参阅更新共享。

将模型添加到共享

本部分介绍如何使用 Catalog Explorer、Databricks CLI 或 Azure Databricks 笔记本或 SQL 查询编辑器中的 SQL 命令向共享添加模型。 如果你倾向于使用 Unity Catalog REST API，请参阅 REST API 参考中的 PATCH /api/2.1/unity-catalog/shares/。

所需权限：共享对象的所有者，对包含模型的目录和架构拥有 USE CATALOG 和 USE SCHEMA 特权，并对模型拥有 EXECUTE 特权。 必须拥有 EXECUTE 特权才能共享模型。 有关详细信息，请参阅要求。

附加要求：

• 模型共享仅在 Databricks 到 Databricks 共享中受支持。
• 向共享添加模型时，必须使用 2023.50 或更高版本的 SQL 仓库或 Databricks Runtime 14.0 或更高版本上的群集。

将模型添加到共享：

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到要向其添加模型的共享，然后单击其名称。

4. 单击“管理资产 > 编辑资产”。

5. 在“编辑资产”页上，搜索或浏览到要共享的模型并将其选中。

   或者，可以选择包含模型的整个架构。 请参阅向共享添加架构。

6. （可选）单击“高级选项”指定备用模型名称或别名，使模型名称更易读。

   如果选择整个架构，则别名不可用。

   别名是收件人明白且必须在查询中使用的名称。 如果指定了别名，则收件人不能使用实际模型名称。

7. 单击“保存” 。

SQL

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

ALTER SHARE <share-name> ADD MODEL <catalog-name>.<schema-name>.<model-name>
   [COMMENT "<comment>"]
   [AS <alias>];

选项包括：

• AS <alias>：备用模型名称或别名，以使模型名称更具可读性。 别名是收件人明白且必须在查询中使用的模型名称。 如果指定了别名，则收件人不能使用实际模型名称。 使用格式 <schema-name>.<model-name>。
• COMMENT "<comment>"：注释显示在目录资源管理器 UI 中，当你使用 SQL 语句列出和显示模型详细信息时也会出现注释。

有关 ALTER SHARE 选项的详细信息，请参阅 ALTER SHARE。

CLI

使用 Databricks CLI 0.210 或更高版本运行以下命令：

 databricks shares update <share-name> \
   --json '{
     "updates": [
       {
         "action": "ADD",
         "data_object": {
           "name": "<model-full-name>",
           "data_object_type": "MODEL",
           "string_shared_as": "<model-alias>"
         }
       }
     ]
   }'

"string_shared_as": "<model-alias>" 是可选的，它提供备用模型名称或别名，使模型名称更易读。 别名是收件人明白且必须在查询中使用的模型名称。 如果指定了别名，则收件人不能使用实际模型名称。 使用格式 <schema-name>.<model-name>。

若要了解其他参数，请运行 databricks shares update --help 或查看 REST API 参考中的 PATCH /api/2.1/unity-catalog/shares/。

有关从共享中移除模型的信息，请参阅更新共享。

向共享添加架构

将整个架构添加到共享时，接收者将不仅可以访问创建架构时架构中的所有数据资产，还可以访问之后添加到架构中的任何资产。 这包括架构中的所有表、视图和卷。 以这种方式共享的表始终包含完整的历史记录。

使用 SQL 添加、更新或删除架构需要一个运行 Databricks Runtime 13.3 LTS 或更高版本的 SQL 仓库或计算。 使用目录资源管理器执行相同操作没有计算要求。

所需权限：共享对象的所有者和架构的所有者（或在架构上拥有 USE SCHEMA 和 SELECT 权限的用户）。

若要向共享添加架构，请按照向共享添加表中的说明进行操作，操作时注意指定如何添加架构的内容。

如果选择整个架构，则表别名、分区和卷别名不可用。 如果你已为架构中的任何资产创建了别名或分区，则当你将整个架构添加到共享时会移除它们。

如果要为使用架构共享共享的表或卷指定高级选项，则必须使用 SQL 共享表或卷，并为表或卷提供一个不同于架构名称的别名。

将笔记本文件添加到共享

使用目录资源管理器将笔记本文件添加到共享。

所需的权限：是共享对象的所有者，并对要共享的笔记本拥有“可读”权限。

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到要向其添加笔记本的共享，然后单击其名称。

4. 单击“管理资产”并选择“添加笔记本文件”。

5. 在“添加笔记本文件”页上，单击文件图标以浏览要共享的笔记本。

   单击要共享的文件，然后单击“选择”。

   （可选）在“共享为”字段中为该文件指定一个用户友好的别名。 这是接收者将看到的标识符。

6. 单击“保存” 。

共享的笔记本文件现在会显示在“资产”选项卡上的“笔记本文件”列表中。

从共享中删除笔记本文件

若要从共享中删除笔记本文件，请执行以下操作：

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到包含该笔记本的共享，然后单击共享名称。

4. 在“资产”选项卡上，找到要从共享中删除的笔记本文件。

5. 单击行右侧的 串形菜单，然后选择“删除笔记本文件”。

6. 在确认对话框中，单击“删除”。

更新共享中的笔记本文件

若要更新已共享的笔记本，必须重新添加它，并在“共享为”字段中为其指定一个新别名。 Databricks 建议使用指示笔记本修订状态的名称，例如 <old-name>-update-1。 可能需要将更改通知给接收者。 接收者必须选择并克隆新笔记本才能利用你做出的更新。

向收件人授予对共享的访问权限

若要向接收者授予共享访问权限，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 GRANT ON SHARE SQL 命令。

所需的权限：下列其中一项：

• 元存储管理员。
• 对共享和接收者对象（(USE SHARE + SET SHARE PERMISSION) 或共享所有者）和（USE RECIPIENT 或接收者所有者）拥有委托权限或所有权。

有关说明，请参阅管理对 Delta Sharing 数据共享的访问权限（适用于提供者）。 本文还介绍如何撤销收件人对共享的访问权限。

查看共享和共享详细信息

若要查看共享列表或共享详细信息，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SQL 命令。

所需的权限：返回的共享列表取决于你的角色和权限。 元存储管理员和拥有 USE SHARE 特权的用户可以查看所有共享。 否则，你只能查看自己是共享对象所有者的共享。

详细信息包括：

• 共享的所有者、创建者、创建时间戳、更新程序、更新时间戳、注释。
• 共享中的数据资产。
• 有权访问共享的收件人。

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 打开“共享”选项卡以查看共享列表。

4. 在“详细信息”选项卡上查看共享详细信息。

SQL

要查看共享列表，请在笔记本或 Databricks SQL 查询编辑器中运行以下命令。 （可选）将 <pattern> 替换为 LIKE 谓词。

SHOW SHARES [LIKE <pattern>];

若要查看有关特定共享的详细信息，请运行以下命令。

DESCRIBE SHARE <share-name>;

若要查看有关共享中的所有表、视图和卷的详细信息，请运行以下命令。

SHOW ALL IN SHARE <share-name>;

CLI

若要查看共享列表，请使用 Databricks CLI 运行以下命令。

databricks shares list

若要查看有关特定共享的详细信息，请运行以下命令。

databricks shares get <share-name>

查看对共享具有权限的收件人

若要查看收件人有权访问的共享列表，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SHOW GRANTS TO RECIPIENT SQL 命令。

所需的权限：元存储管理员、USE SHARE 特权或共享对象所有者。

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，查找并选择收件人。

4. 转到“收件人”选项卡，查看可以访问共享的收件人列表。

SQL

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

SHOW GRANTS ON SHARE <share-name>;

CLI

使用 Databricks CLI 运行以下命令。

databricks shares share-permissions <share-name>

更新共享

除了向共享添加表、视图、卷和笔记本，你还可以：

• 重命名共享。
• 从共享中移除表、视图、卷和架构。
• 添加或更新共享注释。
• 启用或禁用对表的历史记录数据的访问，使接收者能够执行“按时间顺序查看”查询或表的流式读取。
• 添加、更新或删除分区定义。
• 更改共享所有者。

若要对共享进行这些更新，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SQL 命令。 不能使用目录资源管理器重命名共享。

所需的权限：若要更新共享所有者，你必须是以下角色之一：元存储管理员、共享对象的所有者，或者同时拥有 USE SHARE 和 SET SHARE PERMISSION 特权的用户。 若要更新共享名称，你必须是元存储管理员（或拥有 CREATE_SHARE 特权的用户）和共享所有者。 若要更新任何其他共享属性，你必须是所有者。

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到要更新的共享，然后单击其名称。

在共享详细信息页中，执行以下操作：

• 单击“所有者”或“注释”字段旁边的 编辑图标以更新这些值。
• 单击资产行中的串形菜单 按钮以将其删除。
• 单击“管理资产 > 编辑资产”以更新所有其他属性：
  • 若要移除资产，请清除资产旁边的复选框。
  • 若要添加、更新或移除分区定义，请单击“高级选项”。

SQL

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

重命名共享：

ALTER SHARE <share-name> RENAME TO <new-share-name>;

从共享中删除表：

ALTER SHARE share_name REMOVE TABLE <table-name>;

从共享中移除卷：

ALTER SHARE share_name REMOVE VOLUME <volume-name>;

添加或更新共享注释：

COMMENT ON SHARE <share-name> IS '<comment>';

为共享中的表添加或修改分区：

ALTER SHARE <share-name> ADD TABLE <table-name> PARTITION(<clause>);

更改共享所有者：

ALTER SHARE <share-name> OWNER TO  '<principal>'

-- Principal must be an account-level user email address or group name.

为表启用历史记录共享：

ALTER SHARE <share-name> ADD TABLE <table-name> WITH HISTORY;

有关 ALTER SHARE 参数的详细信息，请参阅 ALTER SHARE。

CLI

使用 Databricks CLI 运行以下命令。

重命名共享：

databricks shares update <share-name> --name <new-share-name>

从共享中删除表：

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "REMOVE",
        "data_object": {
          "name": "<table-full-name>",
          "data_object_type": "TABLE",
          "shared_as": "<table-alias>"
        }
      }
    ]
  }'

从共享中移除卷（使用 Databricks CLI 0.210 或更高版本）：

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "REMOVE",
        "data_object": {
          "name": "<volume-full-name>",
          "data_object_type": "VOLUME",
          "string_shared_as": "<volume-alias>"
        }
      }
    ]
  }'

添加或更新共享注释：

databricks shares update <share-name> --comment '<comment>'

更改共享所有者：

databricks  shares update <share-name> --owner '<principal>'

主体必须是帐户级用户电子邮件地址或组名称。

删除共享

若要删除共享，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 DELETE SHARE SQL 命令。 你需要是共享的所有者。

删除共享时，收件人无法再访问共享数据。

所需的权限：共享对象所有者。

目录资源管理器

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

2. 在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”。

   或者，在“快速访问”页中，单击“Delta Sharing >”按钮。

3. 在“与我共享的内容”选项卡上，找到要删除的共享，然后单击其名称。

4. 单击 kebab 菜单并选择“删除”。

5. 在确认对话框中，单击“删除”。

SQL

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

DROP SHARE [IF EXISTS] <share-name>;

CLI

使用 Databricks CLI 运行以下命令。

databricks shares delete <share-name>