世系系统表引用

此页面包含两个世系系统表的参考。 这些系统表基于 Unity 目录 的数据世系功能构建，使你能够以编程方式查询世系数据来推动决策和报告。 若要访问表，必须在目录中启用 system 架构。 有关详细信息，请参阅 “启用系统表”。

表世系表

表世系系统表包括 Unity Catalog 表或路径上每个读取或写入事件的记录。 这包括但不限于作业运行、笔记本运行以及使用读取或写入事件更新的仪表板。

表路径：此系统表位于 system.access.table_lineage。

表世系架构

表世系系统表使用以下架构。

列世系表

列世系表不包括没有源的事件。 例如，如果使用显式值向列中插入数据，则该事件不会被捕获。 如果读取列，则无论是否写入输出，该事件都会被捕获。

表路径：此系统表位于 system.access.column_lineage。

列世系架构

列世系系统表使用以下架构：

读取世系系统表

• 若要确定事件是读取还是写入，可以查看源类型和目标类型。
  • 只读：源类型不为 null，但目标类型为 null。
  • 只写：目标类型不为 null，但源类型为 null。
  • 读取和写入：源类型和目标类型均不为 null。

实体元数据参考

该 entity_metadata 结构具有以下架构：

job_info:
  job_id: "string"
  job_run_id: "string"
dashboard_id: "string"
legacy_dashboard_id: "string"
notebook_id: "string"
sql_query_id: "string"
dlt_pipeline_info:
  dlt_pipeline_id: "string"
  dlt_update_id: "string"

Azure Databricks 记录 Lakeflow Spark 声明性管道、笔记本、作业、Databricks SQL 查询和仪表板中的世系事件。 不支持来自其他实体的事件。

可以根据事件类型填充多个值。 例如，运行笔记本任务的作业将同时填充 job_info 和 notebook_id。

如果所有 entity_metadata 值都 null位于其中，则表示事件中未涉及 Azure Databricks 实体。 例如，它可能是 JDBC 查询或用户单击 Azure Databricks UI 中的“示例数据”选项卡的结果。

世系系统表示例

为了举例说明如何在系统表中记录世系，下面提供了一个示例查询，后跟查询创建的世系记录：

CREATE OR REPLACE TABLE car_features
AS SELECT *,  in1+in2 as premium_feature_set
FROM car_features_exterior
JOIN car_features_interior
USING(id, model);

system.access.table_lineage 中的记录如下所示：

system.access.column_lineage 中的记录如下所示：

使用表世系表分析表的受欢迎程度

表世系系统表可用于估计表的受欢迎程度。 例如，以下代码片段检索过去 7 天内最常查询的 100 个表：

SELECT
  source_table_full_name,
  COUNT(distinct event_id) AS num_of_queries
FROM
  system.access.table_lineage t
WHERE
  t.event_date > CURRENT_DATE() - INTERVAL 7 DAYS
  AND t.source_table_full_name IS NOT NULL
GROUP BY source_table_full_name
ORDER BY num_of_queries DESC
LIMIT 100;

可以与 查询历史记录系统表 联接，以获取有关 SQL 仓库或无服务器计算上运行的查询的其他详细信息，包括缓存中提供的查询（请注意世系系统表不会发出缓存查询结果的条目）。 例如，以下代码片段检索过去 7 天内查询超过一小时的执行时间的表：

SELECT
  t.source_table_full_name,
  COUNT(distinct event_id) AS num_of_queries_over_hour
FROM
  system.query.history h
INNER JOIN system.access.table_lineage t
  ON t.statement_id = h.cache_origin_statement_id
WHERE
  h.total_duration_ms > 3600000
  AND t.event_date > CURRENT_DATE() - INTERVAL 7 DAYS
  AND t.source_table_full_name IS NOT NULL
GROUP BY t.source_table_full_name
ORDER BY num_of_queries_over_hour DESC;

排查外部表查询问题

使用外部表的云存储路径引用外部表时，关联的世系记录仅包括路径名称，而不包括表名。 例如，此查询的世系记录将包括路径名称，而不是表名：

SELECT * FROM delta.`abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1`;

如果尝试通过路径引用查询外部表的沿袭记录，则必须使用source_path或target_path来代替source_table_full_name或target_table_full_name进行筛选查询。 例如，以下查询可拉取外部表的所有世系记录：

SELECT *
FROM system.access.table_lineage
WHERE
  source_path = "abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1" OR
  target_path = "abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1";

基于外部表名称检索世系记录

如果不想手动检索云存储路径以查找世系，可以使用以下函数来使用表名称获取世系数据。 如果要查询列世系，还可以在函数中将 system.access.table_lineage 替换为 system.access.column_lineage。

def getLineageForTable(table_name):
  table_path = spark.sql(f"describe detail {table_name}").select("location").head()[0]

  df = spark.read.table("system.access.table_lineage")
  return df.where(
    (df.source_table_full_name == table_name)
    | (df.target_table_full_name == table_name)
    | (df.source_path == table_path)
    | (df.target_path == table_path)
  )

然后使用以下命令调用函数并显示外部表的世系记录：

display(getLineageForTable("table_name"))