使用 Unity 目录查看数据世系

2025-06-30

本文介绍如何使用目录资源管理器、数据世系系统表和 REST API 可视化数据世系。

数据世系概述

Unity Catalog 通过在 Azure Databricks 上运行的查询捕获运行时数据世系。所有语言都支持世系，并且捕获到列级别。世系数据包括与查询相关的笔记本、作业和仪表板。可在目录资源管理器中近乎实时地可视化世系，还可使用世系系统表和 Databricks REST API 以编程方式检索世系。

世系将聚合所有连接到 Unity Catalog 元存储的工作区。这意味着只要在一个工作区中捕获世系，该世系在共享该元存储的任何其他工作区中均可见。具体而言，在所有连接到元存储的工作区中，元存储中注册的表和其他数据对象对至少具有这些对象 BROWSE 权限的用户可见。但是，有关工作区级别对象（如其他工作区中的笔记本和仪表板）的详细信息将被屏蔽（请参阅世系限制和世系权限）。

世系数据保留一年。

下图是一个示例世系图。

世系概述。

若要了解如何跟踪机器学习模型的世系，请参阅跟踪 Unity Catalog 中模型的数据世系。

要求

如要使用 Unity Catalog 跟踪数据世系，请采取以下做法：

表必须在 Unity Catalog 元存储中注册。
查询必须使用 Spark DataFrame（例如，返回 DataFrame 的 Spark SQL 函数）或 Databricks SQL 接口（例如 Notebooks 或 SQL 查询编辑器）。

查看数据世系：

必须至少对表或视图的父目录具有 BROWSE 权限。同时，必须能从工作区访问父目录。请参阅将目录访问限制为特定工作区。
对于笔记本、作业或仪表板，必须具有工作区中访问控制设置定义的这些对象的权限。有关详细信息，请参阅世系权限。
对于已启用 Unity 目录功能的流水线，您必须拥有该流水线的 CAN VIEW 权限。

计算要求：

对 Delta 表之间的流式传输进行世系跟踪需要 Databricks Runtime 11.3 LTS 或更高版本。
Lakeflow 声明性管道工作负载的列世系跟踪需要 Databricks Runtime 13.3 LTS 或更高版本。

网络要求：

可能需要更新出站防火墙规则，才能在 Azure Databricks 控制平面中连接到事件中心终结点。通常，这一点适用于 Azure Databricks 工作区部署在你自己的 VNet 中（也称为 VNet 注入）的情况。若要获取适用于你的工作区区域的事件中心终结点，请参阅元存储、项目 Blob 存储、系统表存储、日志 Blob 存储和事件中心终结点 IP 地址。有关为 Azure Databricks 设置用户定义的规则 (UDR) 的信息，请参阅 Azure Databricks 的用户定义的路由设置。

使用目录资源管理器查看数据世系

如要使用目录资源管理器查看表世系，请采取以下做法：

在 Azure Databricks 工作区中，单击目录。
搜索或浏览表。
选择“ 世系 ”选项卡。世系面板随即显示并显示相关表。
若要查看数据世系的交互式图形，请单击“查看世系图形”。

默认情况下，图形中显示一个级别。单击节点上的图标以显示更多连接（如果可用）。
单击连接世系图中节点的箭头，以打开“世系连接”面板。

“世系连接”面板显示有关连接的详细信息，包括源表和目标表、笔记本和作业。
若要显示与表关联的笔记本，请在 数据血统连接 面板中选择笔记本，或关闭数据血统图并单击 笔记本。

要在新选项卡中打开笔记本，请单击笔记本名称。
若要查看列级世系，请单击图形中的列以显示指向相关列的链接。例如，单击此示例图中的 full_menu 列，会显示此列派生自的上游列：

查看作业世系

若要查看作业世系，请转到表的世系选项卡，选择作业，然后选择下游。作业名称以表的使用者身份显示在作业名称下。

查看仪表板世系

若要查看仪表板世系，请转到表的“世系”选项卡，然后单击“仪表板”。仪表板会作为表的使用者出现在“仪表板名称”下。

使用 Databricks 助手获取表世系

Databricks 助手提供有关表世系和见解的详细信息。

若要使用助手获取世系信息，请执行以下操作：

在工作区边栏中，单击“ 目录。
浏览或搜索目录，单击目录名称，然后单击右上角的“ 助理”图标。
在助手提示符下，键入：
- /getTableLineages 以查看上游和下游依赖项。
- /getTableInsights 用于访问元数据驱动的见解，例如用户活动和查询模式。

这些查询使助手能够回答诸如“显示下游世系”或“最常查询此表的人员”等问题。

Databricks 助手提供表世系和见解。

使用系统表查询世系数据

可使用世系系统表以编程方式查询世系数据。有关详细说明，请参阅使用系统表监视帐户活动和世系系统表参考。

如果工作区位于不支持世系系统表的区域，则可以改用数据世系 REST API 以编程方式检索世系数据。

使用数据世系 REST API 检索世系

使用数据世系 API 可以检索表和列世系。但是，如果工作区位于支持世系系统表的区域，则应使用系统表查询而不是 REST API。要以编程方式检索世系数据，系统表选项更适合。大多数区域支持世系系统表。

重要

要访问 Databricks REST API，必须进行身份验证。

检索表世系

此示例检索 dinner 表的世系数据。

请求

curl --netrc -X GET \
-H 'Content-Type: application/json' \
https://<workspace-instance>/api/2.0/lineage-tracking/table-lineage \
-d '{"table_name": "lineage_data.lineagedemo.dinner", "include_entity_lineage": true}'

替换 <workspace-instance>。

此示例使用 .netrc 文件。

响应

{
  "upstreams": [
    {
      "tableInfo": {
        "name": "menu",
        "catalog_name": "lineage_data",
        "schema_name": "lineagedemo",
        "table_type": "TABLE"
      },
      "notebookInfos": [
        {
          "workspace_id": 4169371664718798,
          "notebook_id": 1111169262439324
        }
      ]
    }
  ],
  "downstreams": [
    {
      "notebookInfos": [
        {
          "workspace_id": 4169371664718798,
          "notebook_id": 1111169262439324
        }
      ]
    },
    {
      "tableInfo": {
        "name": "dinner_price",
        "catalog_name": "lineage_data",
        "schema_name": "lineagedemo",
        "table_type": "TABLE"
      },
      "notebookInfos": [
        {
          "workspace_id": 4169371664718798,
          "notebook_id": 1111169262439324
        }
      ]
    }
  ]
}

检索列世系

此示例检索 dinner 表的列数据。

请求

curl --netrc -X GET \
-H 'Content-Type: application/json' \
https://<workspace-instance>/api/2.0/lineage-tracking/column-lineage \
-d '{"table_name": "lineage_data.lineagedemo.dinner", "column_name": "dessert"}'

替换 <workspace-instance>。

此示例使用 .netrc 文件。

响应

{
  "upstream_cols": [
    {
      "name": "dessert",
      "catalog_name": "lineage_data",
      "schema_name": "lineagedemo",
      "table_name": "menu",
      "table_type": "TABLE"
    },
    {
      "name": "main",
      "catalog_name": "lineage_data",
      "schema_name": "lineagedemo",
      "table_name": "menu",
      "table_type": "TABLE"
    },
    {
      "name": "app",
      "catalog_name": "lineage_data",
      "schema_name": "lineagedemo",
      "table_name": "menu",
      "table_type": "TABLE"
    }
  ],
  "downstream_cols": [
    {
      "name": "full_menu",
      "catalog_name": "lineage_data",
      "schema_name": "lineagedemo",
      "table_name": "dinner_price",
      "table_type": "TABLE"
    }
  ]
}

世系权限

谱系图与 Unity Catalog 共享相同的权限模型。在 Unity Catalog 元存储中注册的表和其他数据对象仅对至少具有对这些对象的 BROWSE 权限的用户可见。如果用户对表没有 BROWSE 或 SELECT 特权，则无法浏览其世系。世系图展示的是跨所有连接到元存储的工作区的 Unity Catalog 对象，前提是用户具备足够的对象权限。

例如，针对 userA运行以下命令：

GRANT USE SCHEMA on lineage_data.lineagedemo to `userA@company.com`;
GRANT SELECT on lineage_data.lineagedemo.menu to `userA@company.com`;

userA 查看 lineage_data.lineagedemo.menu 表的世系图时，将看到 menu 表。他们将无法查看关联表（例如下游 lineage_data.lineagedemo.dinner 表）的相关信息。展示给 dinner 时，masked 表显示为 userA 节点，并且 userA 无法通过展开图表来查看其无权访问的表的下游表。

如果运行以下命令将 BROWSE 权限授予 userB，则该用户可以查看 lineage_data 架构中任何表的世系图。

GRANT BROWSE on lineage_data to `userB@company.com`;

同样，世系用户必须具有查看工作区对象（如笔记本、作业和仪表板）的特定权限。此外，他们只能在登录到在其中创建这些对象的工作区时查看有关工作区对象的详细信息。有关其他工作区中工作区级别对象的详细信息在世系图中被屏蔽。

若要详细了解如何在 Unity Catalog 中管理对安全对象的访问，请参阅管理 Unity Catalog 中的特权。若要详细了解如何管理对工作区对象（例如笔记本、作业、仪表板）的访问，请参阅访问控制列表。

世系限制

数据世系具有以下限制。这些限制也适用于世系系统表：

尽管会为连接到同一 Unity Catalog 元存储的所有工作空间汇总数据世系，但工作区对象（如笔记本和仪表板）的详细信息仅在其创建时所在的工作空间中可见。
由于世系是在 1 年的滚动时段内计算的，因此不会显示超过 1 年前收集的世系数据。例如，如果作业或查询从表 A 读取数据并写入表 B，则表 A 和表 B 之间的链接仅显示 1 年。你可以在一年内按时间范围筛选世系数据。
使用作业 API runs submit 请求或 spark submit 任务类型的作业在世系视图中不可用。这些工作流仍会捕获表和列级别世系，但不会捕获指向作业运行的链接。
如果已重命名表或视图，则不会为重命名的表或视图捕获世系。
如果重命名架构或目录，则不会为重命名的目录或架构下的表和视图捕获世系。
如果使用 Spark SQL 数据集检查点，则不会捕获世系。
在大多数情况下，Unity Catalog 会从 Lakeflow 声明性管道捕获世系。但是，在某些情况下，无法保证完整世系覆盖范围，例如管道使用 PRIVATE 表时。
世系不会捕获 Stack 函数。
世系中不会捕获全局临时视图。
世系中不会捕获 system.information_schema 下的表。
Unity Catalog 会尽可能将世系捕获到列级别。然而，在某些情况下无法捕获列级别世系。这些包括：
- 如果源或目标被引用为路径，则无法捕获列世系（例如：select * from delta."s3://<bucket>/<path>"）。仅当源和目标都由表名引用时，才支持列世系（示例：select * from <catalog>.<schema>.<table>）。
- 使用通用表表达式（CTE）、列重命名、用户定义的函数（UDF）或弹性分布式数据集（RDD），所有这些都可以掩盖源列和目标列之间的映射。
- 默认情况下，不会为 MERGE 操作捕获完整的列级别世系。
  
  可以通过将 Spark 属性 MERGE 设置为 spark.databricks.dataLineage.mergeIntoV2Enabled 来启用 true 操作的世系捕获。启用此标志可能会降低查询性能，尤其是在涉及非常宽表的工作负荷中。