使用 Unity 目录查看数据世系

2025-05-22

本文介绍如何使用目录资源管理器、数据世系系统表和 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 权限。

计算要求：

增量表之间的流式传输进行世系跟踪需要 Databricks Runtime 11.3 LTS 或更高版本。
DLT 工作负载的列世系跟踪需要 Databricks Runtime 13.3 LTS 或更高版本。

网络要求：

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

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

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

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

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

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

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

查看工作流（作业）流程

若要查看工作流关系，请转到表的世系选项卡，单击“工作流”，然后选择“下游”选项卡。作业名称作为表的使用者显示在作业名称下。

查看仪表板世系

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

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

使用数据世系 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 请求的作业在世系视图中不可用。当作业使用 runs submit 请求时，系统仍会捕获表和列级世系，但不会捕获指向运行的链接。
如果重命名表或视图，则不会为重命名的表或视图捕获世系。
如果重命名架构或目录，则重命名的目录或架构下的表和视图不会捕获世系。
如果使用 Spark SQL 数据集检查点，则不会捕获世系。
在大多数情况下，Unity Catalog 从 DLT 管道捕获世系。但是，在某些情况下，无法保证数据流的全覆盖，例如当管道使用 APPLY CHANGES API 或 ‘PRIVATE’ 表时。
世系不会捕获堆栈函数。
全局临时视图不会在世系中捕获。
system.information_schema 下的表不会在世系中捕获。
Unity Catalog 会尽可能将世系捕获到列级别。但在某些情况下无法捕获列级世系。这些包括：
- 如果源或目标被引用为路径，则无法捕获列世系（例如：select * from delta."s3://<bucket>/<path>"）。仅当源和目标都由表名引用时，才支持列世系（示例：select * from <catalog>.<schema>.<table>）。
- 默认情况下，MERGE 操作不会捕获完整的列级世系。
  
  可以通过将 Spark 属性 MERGE 设置为 spark.databricks.dataLineage.mergeIntoV2Enabled 来打开 true 操作的世系捕获。启用此标志可能会降低查询性能，尤其是在涉及非常宽表的工作负载中。

通过