使用 Unity 目錄擷取和檢視數據譜系
本文說明如何使用目錄總管、數據譜系系統數據表和 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管線的許可權。您可能需要更新輸出防火牆規則，以允許連線到 Azure Databricks 控制平面中的事件中樞端點。 一般而言，如果您的 Azure Databricks 工作區部署在您自己的 VNet 中（也稱為 VNet 插入）。 若要取得工作區區域的事件中樞端點，請參閱中繼存放區、成品 Blob 記憶體、系統資料表儲存體、記錄 Blob 儲存體和事件中樞端點 IP 位址。 如需為 Azure Databricks 設定使用者定義路由 （UDR） 的相關資訊，請參閱 Azure Databricks 的使用者定義路由設定。
限制
只有在 Databricks Runtime 11.3 LTS 或更高版本中才支援差異資料表之間的串流。
因為譜系是基於一年移動時段計算的，所以將不會顯示超過一年前收集的譜系。 例如，如果作業或查詢從資料表 A 讀取資料，並寫入資料表 B，則資料表 A 與資料表 B 之間的連結只會顯示 1 年。
您可以依時間範圍篩選譜系資料。 選取 [所有譜系] 時，會顯示從 2023 年 6 月開始收集的譜系數據。
檢視譜系時無法使用使用作業 API
runs submit要求的工作流程。 使用runs submit要求時，仍會擷取數據表和數據行層級歷程，但不會擷取執行的連結。Unity 目錄會儘可能的擷取資料行層級的譜系。 不過，在某些情況下，無法擷取資料行層級的譜系。
只有當來源和目標都以數據表名稱參考時，才支援數據行譜系（範例：
select * from <catalog>.<schema>.<table>）。 如果來源或目標由路徑尋址，則無法擷取數據行譜系（範例：select * from delta."s3://<bucket>/<path>"）。如果資料表已重新命名，則不會針對重新命名的資料表擷取譜系。
如果您使用 Spark SQL 資料集檢查點，則不會擷取譜系。 請參閱 Apache Spark 檔中的 pyspark.sql.DataFrame.checkpoint 。
在大部分情況下，Unity 目錄會從差異即時資料表管線擷取譜系。 不過，在某些情況下，無法保證完整的歷程涵蓋範圍，例如管線使用 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`;
擷取和探索譜系
若要擷取譜系數據，請使用下列步驟：
移至您的 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，然後按兩下 Databricks 中的 [搜尋lineage_data.lineagedemo.dinner]。在 [數據表] 底下
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，然後按兩下 Databricks 中的 [搜尋lineage_data.lineagedemo.price]。在 [數據表] 底下
price，按兩下數據表。選取 [ 譜系] 索引卷 標，然後按兩下 [ 查看譜系圖表]。 按兩下
圖示以探索 SQL 和 Python 查詢所產生的數據歷程。
按兩下譜系圖形中連接節點的箭號，以開啟 [譜系連接 ] 面板。 [譜系連線] 面板會顯示連線的詳細數據，包括來源和目標數據表、筆記本和工作流程。
擷取和檢視工作流程譜系
譜系也會針對讀取或寫入 Unity 目錄的任何工作流程擷取。 若要示範檢視 Azure Databricks 工作流程的譜系，請使用下列步驟：
單擊提要欄位中的 [
新增]，然後從功能表中選取 [筆記本]。輸入筆記本的名稱，然後選取 [默認語言] 中的 [SQL]。
按一下 [建立]。
在第一個筆記本數據格中，輸入下列查詢：
SELECT * FROM lineage_data.lineagedemo.menu按兩下頂端列中的 [ 排程 ]。 在排程對話框中，選取 [ 手動]，選取具有 Unity 目錄存取權的叢集，然後按兩下 [ 建立]。
按兩下 [ 立即執行]。
在 Azure Databricks 工作區頂端列中的 [搜尋] 方塊中，輸入
lineage_data.lineagedemo.menu，然後按兩下 Databricks 中的 [搜尋lineage_data.lineagedemo.menu]。在 [數據表檢視所有數據表] 下
menu，按兩下數據表。選取 [歷程] 索引標籤，按兩下 [工作流程]，然後選取 [下游] 索引卷標。作業名稱會顯示在 [作業名稱] 底下，做為數據表的
menu取用者。
擷取和檢視儀錶板譜系
若要示範檢視 SQL 儀錶板的譜系，請使用下列步驟：
- 移至您的 Azure Databricks 登陸頁面，然後按下提要欄位中的 [目錄]，以開啟 [目錄總管]。
- 按兩下目錄名稱，按兩下 lineagedemo，然後選取
menu資料表。 您也可以使用 頂端列中的 [搜尋數據表] 文字框來搜尋menu資料表。 - 按兩下 [ 動作 > 建立快速儀錶板]。
- 選取要新增至儀錶板的數據行，然後按兩下 [ 建立]。
- 在 Azure Databricks 工作區頂端列中的 [搜尋] 方塊中，輸入
lineage_data.lineagedemo.menu，然後按兩下 Databricks 中的 [搜尋lineage_data.lineagedemo.menu]。 - 在 [數據表檢視所有數據表] 下
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`;
檢視數據表的lineage_data.lineagedemo.menu譜系圖形時userA，他們會看到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 Catalog 物件的中繼存放區。 如需刪除中繼存放區的詳細資訊，請參閱 刪除中繼存放區。 數據將在 90 天內刪除。
使用系統數據表查詢譜系數據
您可以使用譜系系統數據表，以程式設計方式查詢譜系數據。 如需詳細指示，請參閱 使用系統數據表 監視使用方式和 歷程系統數據表參考。
如果您的工作區位於不支援譜系系統數據表的區域，您也可以使用數據歷程 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"
}
]
}
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應