系列システム テーブル参照

このページには、2 つの系列システム テーブルの参照が含まれています。 これらのシステム テーブルは、Unity Catalog の データ系列機能に基づいて構築されており、プログラムによって系列データを照会して意思決定とレポートを促進できます。 テーブルにアクセスするには、 system カタログでスキーマを有効にする必要があります。 詳細については、「 システム テーブルを有効にする」を参照してください。

テーブル系列テーブル

テーブル系列システム テーブルには、Unity Catalog テーブルまたはパスの読み取り/書き込みイベントごとに 1 つのレコードが含まれています。 これには、ジョブの実行、ノートブックの実行、読み取りまたは書き込みイベントで更新されたダッシュボードが含まれますが、これらに限定されません。

テーブル パス: このシステム テーブルは 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 日間の実行時間が 1 時間を超えるクエリを含むテーブルを取得します。

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"))