向数据和 AI 资产添加注释

  • 项目

本文介绍数据和 AI 资产的注释，并解释如何添加注释。 注释可以帮助你和其他用户查找和管理所需的数据和 AI 资产。

注释提供用于批注安全对象的元数据字段。 可以向 Unity Catalog 中的任何安全对象（例如目录、架构、表、卷、AI 模型等）添加注释。 还可以向表列添加注释。

可以手动添加注释，也可以让 Databricks 为你创建 AI 生成的注释。 AI 生成的注释（也称为 AI 生成的文档）可用于表和表列。 请参阅将 AI 生成的注释添加到 Unity Catalog 对象。

修改 Unity Catalog 表（或旧版 Hive 元存储中的 Delta Lake 表）的注释时，表历史记录中的 SET TBLPROPERTIES 操作会记录用于定义表注释的 SQL 查询。

开始之前

必须满足以下要求才能添加或编辑注释：

  • 若要在目录、架构、卷、模型、共享、接收者、提供者、存储凭据、外部位置或连接上添加或编辑注释，你必须是对象的所有者。
  • 若要在表或列上添加或编辑注释，你必须是所有者或具有以下权限：
    • 表的 MODIFY 和 SELECT 权限。
    • 父目录和架构的 USE CATALOG 和 USE SCHEMA 权限。
  • 必须使用支持 Unity Catalog（共享或单用户计算）的 SQL 仓库或其他计算。
  • 如要使用 AI 生成的注释，必须为工作区启用 AI 辅助功能。 请参阅将 AI 生成的注释添加到 Unity Catalog 对象。

添加和编辑注释

可以向安全对象添加注释，也可以使用 SQL 命令或目录资源管理器编辑它们。

目录资源管理器

  1. 在工作区边栏中，单击 “目录”图标“目录”图标以打开目录资源管理器。

  2. 搜索并选择要添加注释的对象。

    数据和 AI 对象在“目录”窗格中列出，并且可搜索。 可以使用单击 齿轮图标 齿轮图标时打开的菜单访问共享、存储凭据、外部位置和连接。

  3. 添加注释或编辑现有注释。

    • 若要使用 AI 生成的注释向表添加注释，请查看“概览”选项卡右侧窗格中的“AI 建议的注释”。它可能需要几秒钟才能显示。 按原样接受，或编辑并保存。
    • 若要使用 AI 生成的注释向表列添加注释，请单击列表上方的“AI 生成”按钮。 Databricks 会为每一列生成注释。 按原样接受或编辑它们。 单击复选标记，保存注释。
    • 若要向不支持 AI 生成的注释的对象添加注释，请单击“添加注释”以添加注释。
    • 若要在不使用 AI 生成的注释的情况下向表列添加注释，请单击列行中的 用于添加列标记或注释的图标“添加注释”图标。
    • 如果注释已经存在，它将出现在“概览”选项卡的右侧窗格中或对象名称下方。 如果该注释不是 AI 生成的，请单击 “编辑”图标 编辑图标进行编辑。

可以使用基本 Markdown 在目录资源管理器 UI 中设置注释样式。 当由 DESCRIBE 语句返回时，Markdown 样式不会呈现。 目录资源管理器支持除图像之外的所有基本语法，并且仅呈现两个标题级别。 有关更多信息，请参阅基本语法。

有关 AI 生成的注释的详细信息，请参阅将 AI 生成的注释添加到 Unity Catalog 对象。

SQL

可以使用 SQL 命令将字符串文字作为注释添加到 Unity Catalog 中的任何安全对象以及旧版 Hive 元存储中管理的表。 使用的 SQL 命令取决于要为其添加或编辑注释的对象：

  • 若要为除表列之外的任何现有安全对象添加或更新注释，请使用 COMMENT ON 命令。 请参阅 COMMENT ON。

    还可以将 COMMENT 选项与对象的 ALTER <object> 命令（例如，ALTER TABLE）一起使用。 请参阅 ALTER <object> 命令的 SQL 参考文章。

  • 若要添加或更新现有表的列注释，请将 ALTER TABLE 命令与 ALTER COLUMN 子句和列上的 COMMENT 选项一起使用。 请参阅 ALTER TABLE 和 ALTER TABLE … COLUMN 子句。

  • 若要在创建对象时添加注释，请将 COMMENT 选项与 CREATE <object> 命令一起使用。 请参阅 SQL 参考文章以了解要使用的 CREATE <object> 命令。