使用 Unity 目錄擷取和檢視資料譜系

發行項
12/13/2024

本文說明如何使用目錄總管、資料譜系系統資料表和 REST API 來擷取和視覺化資料譜系。

您可以使用 Unity 目錄來擷取在 Azure Databricks 上執行的查詢之間的執行階段資料譜系。所有語言都支援譜系，且譜系會擷取到資料行層級。譜系資料包含與查詢相關的筆記本、工作和儀表板。譜系可以在目錄總管中以近即時的方式視覺化，並使用譜系系統資料表和 Databricks REST API 以程式設計方式擷取。

譜系會彙總至連結至 Unity 目錄中繼存放區的所有工作區。這表示在一個工作區中擷取的譜系在中繼存放區共用的任何其他工作區中均可見。使用者必須擁有正確的權限，才能檢視譜系資料。譜系資料會保留 1 年。

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

譜系概觀

如需追蹤機器學習模型譜系的相關資訊，請參閱在 Unity 目錄中追蹤模型的資料譜系。

需求

使用 Unity 目錄擷取資料譜系需要下列項目：

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

範例

注意

下列範例使用目錄名稱 lineage_data 和結構描述名稱 lineagedemo。若要使用不同的目錄和結構描述，請變更範例中使用的名稱。
若要完成此範例，您必須對結構描述擁有 CREATE 和 USE SCHEMA 權限。具有架構上 MANAGE 許可權的中繼存放區管理員、目錄擁有者、架構擁有者或使用者可以授與這些許可權。例如，若要授與群組 "data_engineers" 中的所有使用者在 lineagedemo 目錄的 lineage_data 結構描述中建立資料表的權限，具有上述其中一種權限或角色的使用者可以執行下列查詢：
```
CREATE SCHEMA lineage_data.lineagedemo;
GRANT USE SCHEMA, CREATE on SCHEMA lineage_data.lineagedemo to `data_engineers`;
```

擷取和探索譜系

若要擷取譜系資料：

移至您的 Azure Databricks 登陸頁面，按下側邊欄中的 [新增]，然後從功能表中選取 [筆記本]。
輸入筆記本的名稱，然後在 [預設語言] 中選取 "SQL"。
在 [叢集] 中，選取具有 Unity 目錄存取權的叢集。
按一下 [建立]。

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

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"，或按下，並選取 [執行儲存格]。

若要使用目錄總管來檢視這些查詢產生的譜系：

在 Azure Databricks 工作區頂端列的 [搜尋] 方塊中，搜尋 lineage_data.lineagedemo.dinner 資料表並加以選取。
選取 [譜系] 索引標籤。譜系面板隨即出現，並顯示相關的資料表 (在此範例中為 menu 資料表)。
若要檢視資料譜系的互動式圖表，請按下 [查看譜系圖]。依預設，圖表中會顯示一個層級。按下節點上的圖示，以顯示更多可用的連線。
按下連接譜系圖中節點的箭號，以開啟 [譜系連線] 面板。 [譜系連線] 面板會顯示連線的詳細資料，包括來源和目標資料表、筆記本和工作。
若要顯示與 dinner 資料表關聯的筆記本，請在 [譜系連線] 面板中選取筆記本，或關閉譜系圖，然後按下 [筆記本]。若要在新索引標籤中開啟筆記本，請按下筆記本名稱。
若要檢視資料行層級譜系，請按下圖表中的資料行，以顯示相關資料行的連結。例如，按下 "full_menu" 資料行會顯示該資料行衍生自的上游資料行：

若要使用不同的語言來檢視譜系，例如 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.price 資料表並加以選取。
移至 [譜系] 索引標籤，然後按下 [查看譜系圖]。按下圖示，以探索查詢產生的資料譜系。
按下連接譜系圖中節點的箭號，以開啟 [譜系連線] 面板。 [譜系連線] 面板會顯示連線的詳細資料，包括來源和目標資料表、筆記本和工作。

擷取並檢視工作流程譜系

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

按一下側邊欄中的 [新增]，然後從功能表中選取 [筆記本]。
輸入筆記本的名稱，然後在 [預設語言] 中選取 "SQL"。
按一下 [建立]。
在第一個筆記本儲存格中，輸入下列查詢：
```
SELECT * FROM lineage_data.lineagedemo.menu
```
按兩下頂端列中的 [排程]。在排程對話方塊中，選取 [手動]，選取具有 Unity 目錄存取權的叢集，然後按下 [建立]。
按下 [立即執行]。
在 Azure Databricks 工作區頂端列的 [搜尋] 方塊中，搜尋 lineage_data.lineagedemo.menu 資料表並加以選取。
在 [譜系] 索引標籤上，按下 [工作流程]，然後選取 [下游] 索引標籤。工作名稱會顯示在 [工作名稱] 底下，做為 menu 資料表的取用者。

擷取並檢視儀表板譜系

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

移至您的 Azure Databricks 登陸頁面，然後按下側邊欄中的 [目錄]，以開啟 [目錄總管]。
按下目錄名稱，按下 "lineagedemo"，然後選取 menu 資料表。您也可以使用頂端列中的 [搜尋] 方塊來搜尋 menu 資料表。
按下 [在儀表板中開啟]。
選取您要新增至儀表板的資料行，然後按下 [建立]。
發佈儀表板。

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

譜系權限

譜系圖會與 Unity 目錄共用相同的權限模型。如果使用者在資料表上沒有 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 資料表在向 masked 的顯示中會顯示為 userA 節點，而且 userA 無法展開圖表，以顯示他們沒有權限存取的資料表中的下游資料表。

若要執行下列命令，以授與 BROWSE 權限給非管理使用者 userB：

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

userB 現在可以檢視 lineage_data 結構描述中任何資料表的譜系圖。

如需有關管理 Unity 目錄中安全物件存取權的詳細資訊，請參閱管理 Unity 目錄中的權限。如需有關管理工作區物件 (例如筆記本、工作和儀表板) 存取權的詳細資訊，請參閱存取控制清單。

刪除譜系資料

警告

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

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

使用系統資料表查詢譜系資料

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

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

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

資料譜系 API 可讓您擷取資料表和資料行譜系。不過，如果您的工作區位於支援譜系系統資料表的區域，您應使用系統資料表查詢，而不是 REST API。系統資料表是以程式設計方式擷取譜系資料的較佳選項。大部分區域都支援譜系系統資料表。

重要

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

擷取資料表譜系

此範例會擷取 dinner 資料表的譜系資料。

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

擷取資料行譜系

此範例會擷取 dinner 資料表的資料行資料。

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

限制

因為譜系是基於一年移動時段計算的，所以將不會顯示超過一年前收集的譜系。例如，如果工作或查詢從資料表 A 讀取資料，並寫入資料表 B，則資料表 A 與資料表 B 之間的連結只會顯示一年。您可以在一年時段內依時間範圍篩選譜系資料。
檢視譜系時，使用工作 API runs submit 要求的工作不可用。使用 runs submit 要求時，仍會擷取資料表和資料行層級的譜系，但不會擷取執行的連結。
Unity 目錄會儘可能的擷取資料行層級的譜系。不過，在某些情況下，無法擷取資料行層級的譜系。
只有當來源和目標都以資料表名稱參考時，才支援資料行譜系 (範例：select * from <catalog>.<schema>.<table>)。如果來源或目標依路徑定址，則無法擷取資料行譜系 (範例：select * from delta."s3://<bucket>/<path>")。
如果資料表或檢視已重新命名，則不會針對重新命名的資料表或檢視擷取譜系。
如果結構描述或目錄已重新命名，則不會在重新命名的目錄或結構描述下針對資料表和檢視擷取譜系。
如果您使用 Spark SQL 資料集檢查點，則不會擷取譜系。
在大部分情況下，Unity 目錄會從差異即時資料表管線擷取譜系。不過，在某些情況下，無法保證完整的譜系涵蓋範圍，例如管線使用 APPLY CHANGES API 或 TEMPORARY 資料表時。
譜系不會擷取堆疊函式。
全域暫存檢視不會在譜系中擷取。
system.information_schema 底下的資料表不會在譜系中擷取。
作業預設 MERGE 不會擷取完整的數據行層級歷程。

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

共用方式為

使用 Unity 目錄擷取和檢視資料譜系

需求

範例

擷取和探索譜系

擷取並檢視工作流程譜系

擷取並檢視儀表板譜系

譜系權限

刪除譜系資料

使用系統資料表查詢譜系資料

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

擷取資料表譜系

Request

回應

擷取資料行譜系

Request

回應

限制

意見反應

其他資源