使用 Unity Catalog 捕获和查看数据世系

可以使用 Unity Catalog 在对 Azure Databricks 运行的查询中捕获运行时数据世系。 所有语言都支持世系，世系捕获级别低至列。 世系数据包括与查询相关的笔记本、工作流和仪表板。 可以在目录资源管理器中准实时地可视化世系，使用 Databricks REST API 检索世系。

注意

还可以使用世系系统表（公共预览版）查看和查询世系数据。 有关详细信息，请参阅世系系统表引用。

将聚合附加到 Unity Catalog 元存储的所有工作区中的世系。 这意味着，在一个工作区中捕获的世系将在共享该元存储的任何其他工作区中可见。 用户必须拥有正确的权限才能查看世系数据。 世系数据会保留 1 年。

本文介绍如何使用目录资源管理器和 REST API 可视化世系。 若要了解如何跟踪机器学习模型的世系，请参阅跟踪 Unity Catalog 中模型的数据世系。

要求

使用 Unity Catalog 捕获数据世系需要满足以下要求：

• 工作区必须已启用 Unity Catalog。

• 表必须已在 Unity Catalog 元存储中注册。

• 查询必须使用 Spark 数据帧（例如，返回数据帧的 Spark SQL 函数）或 Databricks SQL 接口。 有关 Databricks SQL 和 PySpark 查询的示例，请参阅示例。

• 若要查看表或视图的世系，用户必须至少对表或视图的父目录具有 BROWSE 特权。

• 若要查看笔记本、工作流或仪表板的世系信息，用户必须对这些对象拥有工作区中的访问控制设置所定义的权限。 请参阅世系权限。

• 若要查看 已启用 Unity Catalog 的管道的世系，必须对该管道具有 CAN_VIEW 权限。

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

限制

• 只有 Databricks Runtime 11.3 LTS 或更高版本支持 Delta 表之间的流式传输。

• 由于世系是在 1 年的滚动时段内计算的，因此不会显示超过 1 年前收集的世系。 例如，如果作业或查询从表 A 读取数据并写入表 B，则表 A 和表 B 之间的链接仅显示 1 年。

  可以按时间范围筛选世系数据。 选中“所有世系”后，将显示从 2023 年 6 月开始收集的世系数据。

• 查看世系时，使用作业 API runs submit 请求的工作流不可用。 使用 runs submit 请求时仍会捕获表和列级别的世系，但不会捕获指向运行的链接。

• Unity Catalog 会尽可能将世系捕获到列级别。 但在某些情况下无法捕获列级世系。

• 仅当源和目标都由表名引用时，才支持列世系（示例：select * from <catalog>.<schema>.<table>）。 如果源或目标按路径寻址（示例：select * from delta."s3://<bucket>/<path>"），则无法捕获列世系。

• 如果重命名表，则不会为重命名的表捕获世系。

• 如果使用 Spark SQL 数据集检查点，则不会捕获世系。 请参阅 Apache Spark 文档中的 pyspark.sql.DataFrame.checkpoint。

• 在大多数情况下，Unity 目录从 Delta Live Tables 管道捕获世系。 但是，在某些情况下无法保证世系覆盖率完整，例如管道使用 APPLY CHANGES API 或 TEMPORARY 表时。

示例

注意

• 以下示例使用目录名称 lineage_data 和架构名称 lineagedemo。 若要使用不同的目录和架构，请更改示例中使用的名称。

• 若要完成此示例，必须对架构拥有 CREATE 和 USE SCHEMA 特权。 元存储管理员、目录所有者或架构所有者可以授予这些特权。 例如，要为组“data_engineers”中的所有用户授予在 lineage_data 目录中的 lineagedemo 架构内创建表的权限，具有上述特权或角色之一的用户可以运行以下查询：

  CREATE SCHEMA lineage_data.lineagedemo;
  GRANT USE SCHEMA, CREATE on SCHEMA lineage_data.lineagedemo to `data_engineers`;
  

捕获和浏览世系

若要捕获世系数据，请使用以下步骤：

1. 转到 Azure Databricks 登陆页，单击边栏中的 “新建”，然后从菜单中选择“笔记本”。

2. 输入笔记本的名称，然后在“默认语言”中选择“SQL”。

3. 在“群集”中，选择有权访问 Unity Catalog 的群集。

4. 单击“创建”。

5. 在第一个笔记本单元格中输入以下查询：

   CREATE TABLE IF NOT EXISTS
     lineage_data.lineagedemo.menu (
       recipe_id INT,
       app string,
       main string,
       dessert string
     );
   
   INSERT INTO lineage_data.lineagedemo.menu
       (recipe_id, app, main, dessert)
   VALUES
       (1,"Ceviche", "Tacos", "Flan"),
       (2,"Tomato Soup", "Souffle", "Creme Brulee"),
       (3,"Chips","Grilled Cheese","Cheesecake");
   
   CREATE TABLE
     lineage_data.lineagedemo.dinner
   AS SELECT
     recipe_id, concat(app," + ", main," + ",dessert)
   AS
     full_menu
   FROM
     lineage_data.lineagedemo.menu
   

6. 若要运行查询，请在该单元格中单击，然后按 Shift+Enter，或单击并选择“运行单元格”。

若要使用目录资源管理器查看这些查询生成的世系，请使用以下步骤：

1. 在 Azure Databricks 工作区顶部栏的“搜索”框中，输入 lineage_data.lineagedemo.dinner 并单击“在 Databricks 中搜索 lineage_data.lineagedemo.dinner”。

2. 在“表”下，单击 dinner 表。

3. 选择“世系”选项卡。此时会出现世系面板，其中会显示相关表（在本例中为 menu 表）。

4. 若要查看数据世系的交互式图形，请单击“查看世系图形”。 默认情况下，图形中显示一个级别。 可以单击节点上的 图标，以显示更多连接（如果可用）。

5. 单击连接世系图形中节点的箭头会打开“世系连接”面板。 “世系连接”面板显示有关连接的详细信息，包括源表和目标表、笔记本和工作流。

   

6. 若要显示与 dinner 表关联的笔记本，请在“世系连接”面板中选择该笔记本，或关闭世系图形并单击“笔记本”。 若要在新选项卡中打开笔记本，请单击笔记本名称。

7. 若要查看列级世系，请单击图中的列以显示相关列的链接。 例如，单击“full_menu”列将显示该列派生自的上游列：

   

为了演示如何使用不同的语言（例如 Python）创建和查看世系，请使用以下步骤：

1. 打开之前创建的笔记本，创建新单元格，然后输入以下 Python 代码：

   %python
   from pyspark.sql.functions import rand, round
   df = spark.range(3).withColumn("price", round(10*rand(seed=42),2)).withColumnRenamed("id","recipe_id")
   
   df.write.mode("overwrite").saveAsTable("lineage_data.lineagedemo.price")
   
   dinner = spark.read.table("lineage_data.lineagedemo.dinner")
   price = spark.read.table("lineage_data.lineagedemo.price")
   
   dinner_price = dinner.join(price, on="recipe_id")
   dinner_price.write.mode("overwrite").saveAsTable("lineage_data.lineagedemo.dinner_price")
   

2. 通过在单元格中单击并按 Shift+Enter，或者单击并选择“运行单元格”，来运行该单元格。

3. 在 Azure Databricks 工作区顶部栏的“搜索”框中，输入 lineage_data.lineagedemo.price 并单击“在 Databricks 中搜索 lineage_data.lineagedemo.price”。

4. 在“表”下，单击 price 表。

5. 选择“世系”选项卡并单击“查看世系图形”。 单击 图标以浏览 SQL 和 Python 查询生成的数据世系。

   

6. 单击连接世系图形中节点的箭头会打开“世系连接”面板。 “世系连接”面板显示有关连接的详细信息，包括源表和目标表、笔记本和工作流。

捕获和查看工作流世系

还会为读取或写入 Unity Catalog 的任何工作流捕获世系。 为了演示如何查看 Azure Databricks 工作流的世系，请使用以下步骤：

1. 单击边栏中的 “新建”，然后从菜单中选择“笔记本”。

2. 输入笔记本的名称，然后在“默认语言”中选择“SQL”。

3. 单击“创建”。

4. 在第一个笔记本单元格中输入以下查询：

   SELECT * FROM lineage_data.lineagedemo.menu
   

5. 单击顶部栏中的“计划”。 在计划对话中，选择“手动”，选择有权访问 Unity Catalog 的群集，然后单击“创建”。

6. 单击“立即运行”。

7. 在 Azure Databricks 工作区顶部栏的“搜索”框中，输入 lineage_data.lineagedemo.menu 并单击“在 Databricks 中搜索 lineage_data.lineagedemo.menu”。

8. 在“表”>“查看所有表”下，单击 menu 表。

9. 选择“世系”选项卡，单击“工作流”，然后选择“下游”选项卡。作业名称将作为 menu 表的使用者显示在“作业名称”下。

捕获和查看仪表板世系

为了演示如何查看 SQL 仪表板的世系，请使用以下步骤：

1. 转到 Azure Databricks 登陆页，然后通过在边栏中单击“目录”打开目录资源管理器。
2. 单击目录名称，单击“lineagedemo”，然后选择 menu 表。 还可以使用顶部栏中的“搜索表”文本框来搜索 menu 表。
3. 单击“操作”>“创建快速仪表板”。
4. 选择要添加到仪表板的列，然后单击“创建”。
5. 在 Azure Databricks 工作区顶部栏的“搜索”框中，输入 lineage_data.lineagedemo.menu 并单击“在 Databricks 中搜索 lineage_data.lineagedemo.menu”。
6. 在“表”>“查看所有表”下，单击 menu 表。
7. 选择“世系”选项卡并单击“仪表板”。 仪表板名称将作为 menu 表的使用者显示在“仪表板名称”下。

世系权限

世系图形的权限模型与 Unity Catalog 相同。 如果用户对表没有 BROWSE 或 SELECT 特权，则无法浏览世系。 此外，用户只能查看他们有权查看的笔记本、工作流和仪表板。 例如，如果对非管理员用户 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 表在 userA 看到的视图中显示为 masked 节点，并且 userA 无法展开图形以显示他们无权访问的表中的下游表。

如果运行以下命令向非管理员用户 userB 授予 BROWSE 权限：

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

userB 现在可以查看 lineage_data 架构中任何表的世系图。

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

删除世系数据

警告

下面说明如何删除 Unity Catalog 中存储的所有对象。 请仅在必要时按这些说明操作。 例如，在需要满足合规性要求时。

若要删除世系数据，必须删除管理 Unity Catalog 对象的元存储。 有关删除元存储的详细信息，请参阅删除元存储。 数据将在 90 天内删除。

数据世系 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"
    }
  ]
}