使用 Unity Catalog 擷取和檢視數據歷程

發行項
01/10/2025

本文說明如何使用 Catalog Explorer、數據譜系系統 tables和 REST API 來擷取和可視化數據譜系。

您可以使用 Unity Catalog，在 Azure Databricks 上執行的查詢之間擷取運行時間數據譜系。譜系的支援涵蓋所有語言，並精確到 column 層級。譜系資料包含與查詢相關的筆記本、工作和儀表板。譜系可以在 Catalog Explorer 中以近乎即時的方式可視化，並使用譜系系統 tables 和 Databricks REST API 以程序設計方式擷取。

譜系會匯總連結至 Unity Catalog 中繼存放區的所有工作區。這表示在一個工作區中擷取的譜系在 shares 該中繼存放區的任何其他工作區中都可見。具體來說，註冊於中繼存放區的 tables 和其他數據物件，在連接到中繼存放區的所有工作區中，擁有至少 BROWSE 許可權的使用者可以看到。不過，來自其他工作區的筆記本和儀錶板等工作區層級對象的詳細資訊已被隱藏（請參閱限制和譜系許可權）。

歷程數據會保留一年。

下圖是範例譜系圖。本文稍後會說明特定的資料譜系功能和範例。

譜系概觀

如需追蹤機器學習模型譜系的相關信息，請參閱在 Unity Catalog中追蹤模型的數據譜系。

需求

若要使用 Unity Catalog擷取數據血緣，需要具備下列項目：

工作區必須已啟用 Unity Catalog。
Tables 必須在 Unity Catalog 中繼存放區中註冊。
查詢必須使用 Spark DataFrame (例如會傳回 DataFrame 的 Spark SQL 函式) 或 Databricks SQL 介面。如需 Databricks SQL 和 PySpark 查詢的範例，請參閱範例。
若要檢視 table 或檢視的譜系，使用者至少需要在 table 或檢視的父 catalog 上擁有 BROWSE 許可權。父項 catalog 也必須從工作區可以存取。請參閱對特定工作區的存取 Limitcatalog。
若要檢視筆記本、工作或儀表板的譜系資訊，使用者必須擁有這些物件的權限，如工作區中的存取控制設定所定義。請參閱譜系權限。
若要檢視已啟用 Unity Catalog管線的譜系，您必須具有管線 CAN_VIEW 許可權。
Delta tables 的串流譜系追蹤需要 Databricks Runtime 11.3 LTS 或更高版本。
Column Delta Live Tables 工作負載的譜系追蹤需要 Databricks Runtime 13.3 LTS 或更新版本。
您可能需要 update 輸出防火牆規則，以允許連線到 Azure Databricks 控制平面中的事件中樞端點。通常，如果您的 Azure Databricks 工作區部署在您自己的 VNet (也稱為 VNet 插入) 中，則適用此規則。若要 get 工作區區域的事件中樞端點，請參閱中繼存放區、成品 Blob 記憶體、系統 tables 記憶體、記錄 Blob 記憶體和事件中樞端點 IP 位址。如需為 Azure Databricks 設定使用者定義路由 (UDR) 的相關資訊，請參閱 Azure Databricks 的使用者定義路由設定。

範例

注意

下列範例使用 catalog 名稱 lineage_data 和 schema 名稱 lineagedemo。若要使用不同的 catalog 和 schema，請變更範例中使用的名稱。
若要完成此範例，您必須在 schema上擁有 CREATE 和 USE SCHEMA 許可權。中繼存放區系統管理員、catalog 擁有者、schema 擁有者，或在 schema 具有 MANAGE 許可權的使用者，可以 grant 這些許可權。例如，若要為群組『data_engineers』中的所有使用者提供在 lineage_datacatalog的 lineagedemoschema 中建立 tables 的許可權，具有上述其中一個許可權或角色的使用者可以執行下列查詢：
```
CREATE SCHEMA lineage_data.lineagedemo;
GRANT USE SCHEMA, CREATE on SCHEMA lineage_data.lineagedemo to `data_engineers`;
```

擷取和探索譜系

若要擷取譜系資料：

移至您的 Azure Databricks 登陸頁面，按一下側邊欄中的 [新增]，然後從選單中選擇 selectNotebook。
在 [預設語言]中輸入筆記本的名稱，並 selectSQL。
在叢集中，select 具有 Unity Catalog存取權的叢集。
按一下 [建立]。

在第一個筆記本儲存格中，輸入下列查詢：

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

若要執行查詢，請按下資料格，然後按 shift+enter，或單擊 [執行功能表]，然後 select[執行儲存格]。

若要使用 Catalog Explorer 來檢視這些查詢所產生的譜系：

在 Azure Databricks 工作區頂端列的 [搜尋] 方塊中，搜尋 lineage_data.lineagedemo.dinnertable 並 select。
Select [譜系] 標籤。譜系面板隨即出現，並顯示相關的 tables（在此範例中為 menutable）。
若要檢視資料譜系的互動式圖表，請按下 [查看譜系圖]。依預設，圖表中會顯示一個層級。點擊節點上的圖示，以顯示更多的 connections（若有）。
按下連接譜系圖中節點的箭號，以開啟 [譜系連線] 面板。 譜系連線 面板會顯示連線的詳細數據，包括來源和目標 tables、筆記本和作業。
若要顯示與 dinnertable相關聯的筆記本，請在 select譜系連線面板中查看筆記本，或關閉譜系圖形並點擊 [Notebooks]。若要在新索引標籤中開啟筆記本，請按下筆記本名稱。
若要檢視 column層級譜系，請按兩下圖形中的 column 以顯示相關 columns的連結。例如，按一下 [full_menu] column 會顯示 columns 的上游，從中衍生出 column。

若要使用不同的語言來檢視譜系，例如 Python：

開啟您先前建立的筆記本、建立新的儲存格，然後輸入下列 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")

透過以下方式執行儲存格：按下儲存格，然後按 "shift+enter"，或按下，並選取 [執行儲存格]。
在 Azure Databricks 工作區頂端列的 [搜尋] 方塊中，搜尋 lineage_data.lineagedemo.pricetable 並 select。
移至 [譜系] 索引標籤，然後按下 [查看譜系圖]。按下圖示，以探索查詢產生的資料譜系。
按下連接譜系圖中節點的箭號，以開啟 [譜系連線] 面板。 譜系連線 面板會展現連線的詳細資訊，包括來源、目標 tables、筆記本和作業。

擷取並檢視工作流程譜系

也會針對讀取或寫入 Unity 的任何工作流程擷取譜系 Catalog。若要檢視 Azure Databricks 工作流程的譜系：

在側邊欄中單擊新增，然後在選單中選擇 selectNotebook。
在 [默認語言]中輸入筆記本的名稱，然後在中輸入 SQL。
按一下 [建立]。
在第一個筆記本儲存格中，輸入下列查詢：
```
SELECT * FROM lineage_data.lineagedemo.menu
```
按兩下頂端列中的 [排程]。在排程對話框中，select手動，select 具有 Unity Catalog存取權的叢集，然後按建立。
按下 [立即執行]。
在 Azure Databricks 工作區頂端列的 [搜尋] 方塊中，搜尋 lineage_data.lineagedemo.menutable 並 select。
在 [歷程] 索引標籤上，按兩下 [工作流程]，然後 select[下游] 索引卷標。作業名稱會顯示在 [作業名稱] 底下， 做為 menutable的取用者。

擷取並檢視儀表板譜系

若要建立儀表板並檢視其資料譜系：

前往您的 Azure Databricks 登陸頁面，然後在側邊欄中點擊 [Catalog] 以開啟 Catalog Explorer。
點選 catalog 名稱、譜系，selectmenutable。您也可以使用頂端列中的 [搜索] 方塊來搜索 menutable。
按下 [在儀表板中開啟]。
Select 您想要新增至儀錶板的 columns，然後按下 [建立]。
發佈儀表板。

只會在資料譜系中追蹤已發佈的儀表板。
在頂端列的 [搜尋] 方塊中，搜尋 lineage_data.lineagedemo.menutable 並 select。
在 [譜系] 索引標籤上，按下 [儀表板]。儀錶板會顯示在 [儀錶板名稱] 底下， 做為功能表 table的取用者。

譜系權限

譜系圖與 Unity Catalog共用相同的權限模型。 Tables 和其他在 Unity Catalog 中繼存放區中註冊的數據物件，只有至少具有這些物件 BROWSE 許可權的使用者才能看見。如果使用者在 table上沒有 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`;

當查看 userAviewslineage_data.lineagedemo.menutable的譜系圖時，他們會看到 menutable。它們將無法看到相關聯 tables的相關信息，例如下游 lineage_data.lineagedemo.dinnertable。 dinner table 會在顯示給 userA的畫面中顯示為 masked 節點，而 userA 無法展開圖形來顯示他們無權訪問的 tables 下游 tables。

如果您執行下列命令來 grantuserB的 BROWSE 許可權，該使用者可以檢視 lineage_dataschema中任何 table 的譜系圖形：

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

同樣地，譜系用戶必須具有特定許可權，才能檢視筆記本、作業和儀錶板等工作區物件。此外，他們只能在登入建立這些物件的工作區時，查看工作區對象的詳細資訊。其他工作區中工作區層級的物件詳細資訊會在譜系圖形中隱藏。

如需在 Unity Catalog中管理可保護物件存取權的詳細資訊，請參閱 Unity Catalog中的管理許可權。如需有關管理工作區物件 (例如筆記本、工作和儀表板) 存取權的詳細資訊，請參閱存取控制清單。

刪除譜系資料

警告

下列指示會刪除儲存在 Unity Catalog中的所有物件。請僅在必要時使用這些指令。例如，若要符合合規性需求。

若要刪除歷程數據，您必須刪除管理 Unity Catalog 物件的中繼存放區。如需有關刪除中繼存放區的詳細資訊，請參閱刪除中繼存放區。資料將在 90 天內刪除。

使用 tables 系統查詢歷程數據

您可以使用譜系系統 tables，以程式設計方式查詢譜系數據。如需詳細指示以監視帳戶活動，請參閱系統 tables 和歷程系統 tables 參考。

如果您的工作區位於不支援譜系系統的區域 tables，您也可以使用資料歷程 REST API，以程序設計方式擷取譜系數據。

使用資料譜系 REST API 擷取譜系

數據譜系 API 可讓您擷取 table 和 column 譜系。不過，如果您的工作區位於支援譜系系統 tables的區域，您應該使用系統 table 查詢，而不是 REST API。系統 tables 是程序設計擷取譜系數據更好的選項。大部分區域都支援譜系系統 tables。

重要

若要存取 Databricks REST API，您必須驗證。

擷取 table 譜系

此範例會擷取 dinnertable的譜系數據。

Request

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
        }
      ]
    }
  ]
}

擷取 column 譜系

此範例會擷取 dinnertable的數據 column。

Request

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 中繼資料儲存庫的所有工作區都會匯總相關譜系資料，但像筆記本和儀錶板等工作區對象的詳細資料只會顯示在它們創建的工作區中。
由於譜系是以一年滾動 window計算，因此不會顯示一年多前收集的譜系。例如，如果作業或查詢從 table A 讀取數據並寫入至 table B，則 table A 與 table B 之間的連結只會顯示一年。您可以在一年內依時間範圍篩選譜系數據 window。
檢視譜系時，使用工作 API runs submit 要求的工作不可用。使用 runs submit 請求時，仍會擷取 Table 和 column 層級歷程，但不會擷取到運行的鏈結。
Unity Catalog 盡可能地擷取到 column 層級的譜系。不過，在某些情況下 wherecolumn無法擷取層級譜系。
只有當來源和目標都以 table 名稱參考時，才支援 Column 譜系（例如：select * from <catalog>.<schema>.<table>）。如果來源或目標由路徑尋址，則無法擷取 Column 譜系（例如：select * from delta."s3://<bucket>/<path>"）。
如果重新命名 table 或檢視，則不會捕捉 table 或檢視重新命名後的血緣關係。
如果重新命名 schema 或 catalog，則無法擷取位於重新命名的 catalog 或 schema下的 tables 和 views 的歷程。
如果您使用 Spark SQL 資料集檢查點，則不會擷取譜系。
在大部分情況下，Unity Catalog 會從 Delta Live Tables 管線擷取譜系。不過，在某些情況下，無法保證完整的歷程涵蓋範圍，例如當管線使用 APPLY CHANGES API 或 TEMPORARY tables時。
譜系不會擷取堆疊函式。
全域臨時 views 不會被系譜所捕捉。
system.information_schema 下的 Tables 不會被記錄在資料譜系中。
預設情況下，不會擷取 MERGE 作業的完整 column層級歷程。

您可以將 Spark 屬性MERGEspark.databricks.dataLineage.mergeIntoV2Enabled設定為 true ，以開啟作業的歷程擷取。開啟此旗標可能會降低查詢效能，特別是在涉及非常寬泛的工作負載 tables。

共用方式為

使用 Unity Catalog 擷取和檢視數據歷程

需求

範例

擷取和探索譜系

擷取並檢視工作流程譜系

擷取並檢視儀表板譜系

譜系權限

刪除譜系資料

使用 tables 系統查詢歷程數據

使用資料譜系 REST API 擷取譜系

擷取 table 譜系

Request

回應

擷取 column 譜系

Request

回應

限制

意見反應

其他資源

共用方式為

使用 Unity Catalog 擷取和檢視數據歷程

需求

範例

擷取和探索譜系

擷取並檢視工作流程譜系

擷取並檢視儀表板譜系

譜系權限

刪除譜系資料

使用 tables 系統查詢 歷程數據

使用資料譜系 REST API 擷取譜系

擷取 table 譜系

Request

回應

擷取 column 譜系

Request

回應

限制

意見反應

其他資源

使用 tables 系統查詢歷程數據