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

重要

この機能はパブリック プレビュー段階にあります。

この記事では、2 つの系列システム テーブルの概要について説明します。 これらのシステム テーブルは Unity Catalog のデータ系列機能に構築されており、プログラムで系列データにクエリを実行して、意思決定とレポート作成を促進できます。

系列システム テーブルは 2 つあります。

• system.access.table_lineage
• system.access.column_lineage

Note

どちらの系列テーブルも、常に系列をキャプチャできるわけではないため、すべての読み取り/書き込みイベントのサブセットを表します。 レコードは、系列を推論できる場合にのみ生成されます。

テーブル系列テーブル

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

列系列テーブル

列系列テーブルには、ソースのないイベントは含まれません。 たとえば、明示的な値を使用して列に挿入した場合はキャプチャされません。 列を読み取ると、出力を書き込むかどうかに関係なくキャプチャされます。 列の系列は、Delta Live Tables ではサポートされていません。

系列システム テーブル スキーマ

系列システム テーブルでは、次のスキーマが使用されます。 テーブル系列スキーマには source_column_name と target_column_name は含まれません。

列名	データ型	説明	例
account_id	string	Azure Databricks アカウントの ID。	7af234db-66d7-4db3-bbf0-956098224879
metastore_id	string	Unity Catalog メタストアの ID。	5a31ba44-bbf4-4174-bf33-e1fa078e6765
workspace_id	string	ワークスペースの ID	123456789012345
entity_type	string	系列トランザクションがキャプチャされたエンティティの種類。 値は、NOTEBOOK、JOB、PIPELINE、DASHBOARD_V3 (ダッシュボード)、DBSQL_DASHBOARD (レガシ ダッシュボード)、DBSQL_QUERY、または NULL です。	NOTEBOOK
entity_id	string	系列トランザクションがキャプチャされたエンティティの ID。 entity_type が NULL の場合、entity_id は NULL です。	* ノートブック: 23098402394234 * ジョブ: 23098402394234 * Databricks SQL クエリ: e9cd8a31-de2f-4206-adfa-4f6605d68d88 * ダッシュボード: 01ef070d110715f2b6d3061b8bda89ea * レガシ ダッシュボード: e9cd8a31-de2f-4206-adfa-4f6605d68d88 * パイプライン: e9cd8a31-de2f-4206-adfa-4f6605d68d88
entity_run_id	string	エンティティの一意の実行を記述する ID、または NULL。 これは、エンティティの種類ごとに異なります。 * ノートブック: command_run_id * ジョブ: job_run_id * Databricks SQL クエリ: query_run_id * ダッシュボード: query_run_id * レガシ ダッシュボード: query_run_id * パイプライン: pipeline_update_id entity_type が NULL の場合、entity_run_id は NULL です。	* ノートブック: e3cr5a10-de6f-6206-fdfa-4f5505d68d55 * ジョブ: 51090402394234 * Databricks SQL クエリ: e9cd8a31-de2f-4206-adfa-4f6605d68d88 * ダッシュボード: c3ra5m10-pt6o-6206-mdfa-4f5505d68d55 * レガシ ダッシュボード: c3ra5m10-pt6o-6206-mdfa-4f5505d68d55 * パイプライン: c5am1e0r-on2f-4206-adfa-4f6605d68d88
source_table_full_name	string	ソース テーブルを識別する 3 部構成の名前。	catalog.schema.table
source_table_catalog	string	ソース テーブルのカタログ。	catalog
source_table_schema	string	ソース テーブルのスキーマ。	catalog.schema
source_table_name	string	ソース テーブルの名前です。	table
source_path	string	ソース テーブルのクラウド ストレージ内の場所。クラウド ストレージから直接読み取っている場合はパス。	abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1
source_type	string	ソースの種類。 値は TABLE、PATH、VIEW、または STREAMING_TABLE です。	TABLE
source_column_name	string	変換元列の名前です。	date
target_table_full_name	string	ターゲット テーブルを識別する 3 部構成の名前。	catalog.schema.table
target_table_catalog	string	ターゲット テーブルのカタログ。	catalog
target_table_schema	string	ターゲット テーブルのスキーマ。	catalog.schema
target_table_name	string	ターゲット テーブルの名前。	table
target_path	string	ターゲット テーブルのクラウド ストレージ内の場所。	abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1
target_type	string	対象の型です。 値は TABLE、PATH、VIEW、または STREAMING TABLE です。	TABLE
target_column_name	string	ターゲット列の名前。	date
created_by	string	この系列を生成したユーザー。 これは、Azure Databricks ユーザー名、Azure Databricks サービス プリンシパル ID、"System-User"、または NULL ユーザー情報をキャプチャできない場合に使用できます。	crampton.rods@email.com
event_time	timestamp	系列が生成された時刻のタイムスタンプ。	2023-06-20T19:47:21.194+0000
event_date	日にち	系列が生成された日付。 これはパーティション分割された列です。	2023-06-20

系列システム テーブルの読み取り

系列システム テーブルを分析するときは、次の考慮事項に注意してください。

• entity_type の場合、Azure Databricks は Delta Live Tables、ノートブック、ジョブ、Databricks SQL クエリ、ダッシュボードをサポートしています。 他のエンティティからのイベントはサポートされていません。
• entity_type が null と表示される場合は、Azure Databricks エンティティがイベントと関係ないことを意味します。 たとえば、JDBC クエリの結果、またはユーザーが Azure Databricks UI の [サンプル データ] タブをクリックした場合などです。
• イベントが読み取りまたは書き込みのいずれであったかを確認するには、ソースの種類とターゲットの種類を表示できます。
  • 読み取り専用: ソースの種類は null ではありませんが、ターゲットの種類は null です。
  • 書き込み専用: ターゲットの種類は null ではありませんが、ソースの種類は null です。
  • 読み取りおよび書き込み: ソースの種類とターゲットの種類がいずれも null ではありません。

系列システム テーブルの例

系列をシステム テーブルに記録する方法の例として、クエリの例と、クエリによって作成される系列レコードを次に示します。

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 のレコードは次のようになります。

entity_type	entity_id	source_table_name	target_table_name	created_by	event_time
NOTEBOOK	27080565267	car_features_exterior	car_features	crampton@email.com	2023-01-25T16:19:58.908+0000
NOTEBOOK	27080565267	car_features_interior	car_features	crampton@email.com	2023-01-25T16:19:58.908+0000

system.access.column_lineage のレコードは次のようになります。

entity_type	entity_id	source_table_name	target_table_name	source_column_name	target_column_name	event_time
NOTEBOOK	27080565267	car_features_interior	car_features	in1	premium_feature_set	2023-01-25T16:19:58.908+0000
NOTEBOOK	27080565267	car_features_interior	car_features	in2	premium_feature_set	2023-01-25T16:19:58.908+0000

Note

上記の例では、すべての系列列が示されているわけではありません。 完全なスキーマについては、上記の系列スキーマを参照してください。

外部テーブル クエリのトラブルシューティング

クラウド ストレージ パスを使用して外部テーブルを参照する場合、関連付けられている系列レコードには、テーブル名ではなくパス名のみが含まれます。 たとえば、このクエリの系列レコードには、テーブル名ではなくパス名が含まれます:

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

パスによって参照される外部テーブルの系列レコードに対してクエリを実行する場合は、source_table_full_name または target_table_full_name の代わりに source_path または target_path を使用してクエリをフィルター処理する必要があります。 たとえば、次のクエリでは、外部テーブルのすべての系列レコードがプルされます:

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