Unity Catalog を使用したデータ系列のキャプチャと表示

[アーティクル]
05/03/2024

Unity Catalog を使用すると、Azure Databricks に対して実行されたクエリを対象にランタイムデータ系列をキャプチャできます。系列はすべての言語でサポートされ、列レベルまでキャプチャされます。系列データには、クエリに関連するノートブック、ワークフロー、ダッシュボードが含まれます。系列は、カタログエクスプローラーでほぼリアルタイムに視覚化し、Databricks REST API を使用して取得できます。

Note

また、系列システムテーブル (パブリックプレビュー) を使用して系列データの表示およびクエリの実行をすることもできます。詳しくは、「系列システムテーブル参照」を参照してください。

系列は、Unity Catalog メタストアにアタッチされているすべてのワークスペースにわたって集約されます。つまり、あるワークスペースでキャプチャされた系列は、そのメタストアを共有する他のすべてのワークスペースに表示されます。系列データを表示するためには、適切なアクセス許可がユーザーに付与されている必要があります。系列データは 1 年間保持されます。

この記事では、Catalog Explorer と REST API を使用して系列を視覚化する方法について説明します。機械学習モデルの系列の追跡については、「Unity Catalog でモデルのデータ系列を追跡する」を参照してください。

要件

Unity Catalog を使ってデータ系列を取得するための要件は次のとおりです。

ワークスペースで Unity カタログが有効になっている必要があります。
テーブルは Unity カタログメタストアに登録する必要があります。
クエリでは、Spark DataFrame (DataFrame を返す Spark SQL 関数など) または Databricks SQL インターフェイスを使用する必要があります。 Databricks SQL クエリと PySpark クエリの例については、「例」を参照してください。
テーブルまたはビューの系列を表示するには、少なくとも、そのテーブルまたはビューの親カタログに対する BROWSE 権限がユーザーに付与されている必要があります。
ノートブック、ワークフロー、ダッシュボードの系列情報を表示するには、ワークスペースのアクセス制御設定で定義されているこれらのオブジェクトに対するアクセス許可がユーザーに付与されている必要があります。「系列のアクセス許可」を参照してください。
Unity カタログ対応パイプラインの系列を表示するには、パイプラインに対する CAN_VIEW アクセス許可が必要です。
Azure Databricks コントロールプレーンの Event Hub エンドポイントへの接続を許可するために、送信ファイアウォール規則の更新が必要になる場合があります。通常、これは、Azure Databricks ワークスペースが独自の VNet (VNet インジェクションとも呼ばれます) にデプロイされている場合に適用されます。ワークスペースリージョンの Event Hub エンドポイントを取得するには、「メタストア、成果物 BLOB ストレージ、システムテーブルストレージ、ログ BLOB ストレージ、イベントハブエンドポイントの IP アドレス」を参照してください。 Azure Databricks のユーザー定義ルート (UDR) の設定については、「Azure Databricks のユーザー定義ルート設定」を参照してください。

制限事項

Delta テーブル間のストリーミングは、Databricks Runtime 11.3 LTS 以上でのみサポートされます。
系列は 1 年間のローリングウィンドウで計算されるため、1 年よりも前に収集された系列は表示されません。たとえば、ジョブまたはクエリでテーブル A からデータを読み取り、テーブル B に書き込んだ場合、テーブル A とテーブル B の間のリンクは 1 年間だけ表示されます。

系列データは、概算時間でフィルター処理することができます。 [すべての系列] を選択すると、2023 年 1 月以降に収集された系列データが表示されます。
Jobs API runs submit 要求を使用するワークフローは、系列を表示するときに使用できません。 runs submit 要求の使用時もテーブルレベルと列レベルの系列はキャプチャされますが、実行へのリンクはキャプチャされません。
Unity Catalog は、可能な限り列レベルに系列を取り込みます。ただし、列レベルの系列を取り込むことができない場合があります。
列の系列は、ソースとターゲットの両方がテーブル名で参照されている場合にのみサポートされます (例: select * from <catalog>.<schema>.<table>)。ソースまたはターゲットがパスでアドレス指定されている場合、列の系列をキャプチャできません (例: select * from delta."s3://<bucket>/<path>")。
テーブルの名前が変わった場合、名前が変わったテーブルの系列は取り込まれません。
Spark SQL データセットのチェックポイントを使用する場合、系列はキャプチャされません。 Apache Spark ドキュメントの「pyspark.sql.DataFrame.checkpoint」を参照してください。
Unity Catalog でキャプチャされる系列は、ほとんどの場合、Delta Live Tables パイプラインからのものです。ただし、パイプラインで 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 のランディングページにアクセスし、サイドバーの [新規] をクリックし、メニューから [Notebook](ノートブック) を選択します。
ノートブックの名前を入力し、[既定の言語] で [SQL] を選択します。
[クラスター] で、Unity Catalog にアクセスできるクラスターを選択します。
Create をクリックしてください。

1 つ目のノートブックセルに、次のクエリを入力します。

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 キーを押すか、をクリックして [セルの実行] を選択します。

これらのクエリによって生成された系列を Catalog Explorer を使用して表示するには、次の手順に従います:

Azure Databricks ワークスペースの上部バーにある [検索] ボックスに「lineage_data.lineagedemo.dinner」と入力し、[Search lineage_data.lineagedemo.dinner in Databricks] (Databricks で lineage_data.lineagedemo.dinner を検索) をクリックします。
[テーブル] で dinner テーブルをクリックします。
[データ系列] タブを選択します。系列パネルが表示され、関連テーブルが表示されます (この例では menu テーブルです)。
データ系列のインタラクティブグラフを表示するには、[See Lineage Graph] (系列グラフの表示) をクリックします。既定では、1 つのレベルがグラフに表示されます。ノードのアイコンをクリックすると、使用可能な場合は、さらに多くの接続を表示できます。
系列グラフ内の各ノードを接続する矢印をクリックして、[Lineage connection] (系列接続) パネルを開きます。接続元と接続先のテーブル、ノートブック、ワークフローなど、その接続の詳細が [Lineage connection] (系列接続) パネルに表示されます。
dinner テーブルに関連付けられているノートブックを表示するには、[Lineage connection] (系列接続) パネルでノートブックを選択するか、系列グラフを閉じて [Notebooks] (ノートブック) をクリックします。新しいタブでノートブックを開くには、ノートブック名をクリックします。
列レベルの系列を表示するには、グラフ内の列をクリックして、関連する列へのリンクを表示します。たとえば、"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」と入力し、[Search lineage_data.lineagedemo.price in Databricks] (Databricks で lineage_data.lineagedemo.price を検索) をクリックします。
[テーブル] で price テーブルをクリックします。
[Lineage] (系列) タブを選択し、[See Lineage Graph] (系列グラフの表示) を選択します。アイコンをクリックすると、SQL や Python のクエリによって生成されたデータ系列を調べることができます。
系列グラフ内の各ノードを接続する矢印をクリックして、[Lineage connection] (系列接続) パネルを開きます。接続元と接続先のテーブル、ノートブック、ワークフローなど、その接続の詳細が [Lineage connection] (系列接続) パネルに表示されます。

ワークフロー系列をキャプチャして表示する

系列は、Unity Catalog に対して読み取りまたは書き込みを行うワークフローに対してもキャプチャされます。 Azure Databricks ワークフローの系列を表示するには、次の手順に従います。

サイドバーの [新規] をクリックし、メニューから [Notebook](ノートブック) を選択します。
ノートブックの名前を入力し、[既定の言語] で [SQL] を選択します。
Create をクリックしてください。
1 つ目のノートブックセルに、次のクエリを入力します。
```
SELECT * FROM lineage_data.lineagedemo.menu
```
上部のバーの [スケジュール] をクリックします。スケジュールダイアログで、[手動] を選択し、Unity Catalog にアクセスできるクラスターを選択して、[作成] をクリックします。
[今すぐ実行] をクリックします。
Azure Databricks ワークスペースの上部バーにある [検索] ボックスに「lineage_data.lineagedemo.menu」と入力し、[Search lineage_data.lineagedemo.menu in Databricks] (Databricks で lineage_data.lineagedemo.menu を検索) をクリックします。
[Tables View all tables] (すべてのテーブルのテーブルビュー) で、menu テーブルをクリックします。
[Lineage] (系列) タブを選択し、[ワークフロー] をクリックして [ダウンストリーム] タブを選択します。そのジョブ名が、menu テーブルのコンシューマーとして [ジョブ名] に表示されます。

ダッシュボードの系列をキャプチャして表示する

SQL ダッシュボードの系列を表示するには、次の手順に従います。

Azure Databricks のランディングページに移動し、サイドバーの [カタログ] をクリックして Catalog Explorer を開いてください。
カタログ名をクリックし、[lineagedemo] をクリックして、menu テーブルを選択します。上部のバーの [Search tables] (テーブルの検索) ボックスを使用して menu テーブルを検索することもできます。
[Actions] (操作) > [Create a quick dashboard] (クイックダッシュボードの作成) をクリックします。
ダッシュボードに追加する列を選択し、[作成] をクリックします。
Azure Databricks ワークスペースの上部バーにある [検索] ボックスに「lineage_data.lineagedemo.menu」と入力し、[Search lineage_data.lineagedemo.menu in Databricks] (Databricks で lineage_data.lineagedemo.menu を検索) をクリックします。
[Tables View all tables] (すべてのテーブルのテーブルビュー) で、menu テーブルをクリックします。
[Lineage] (系列) タブを選択し、[ダッシュボード] をクリックします。ダッシュボード名が、メニューテーブルのコンシューマーとして [Dashboard Name] (ダッシュボード名) に表示されます。

系列のアクセス許可

系列グラフは、Unity Catalog と同じアクセス許可モデルを共有します。テーブルに対する 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 テーブルなど、関連付けられているテーブルに関する情報を表示することはできません。 userA に対する表示では、dinner テーブルが masked ノードとして表示されます。userA がグラフを展開して、自分に権限がないテーブルのダウンストリームテーブルを表示することはできません。

次のコマンドを実行して、管理者以外のユーザー userB に BROWSE アクセス許可を付与する場合:

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

userB は、lineage_data スキーマ内の任意のテーブルの系列グラフを表示できるようになりました。

Unity Catalog でセキュリティ保護可能なオブジェクトへのアクセスを管理する方法の詳細については、「Unity Catalog の特権の管理」を参照してください。ノートブック、ワークフロー、ダッシュボードなどのワークスペースオブジェクトへのアクセスの管理の詳細については、「アクセス制御リスト」を参照してください。

系列データを削除する

警告

次の手順では、Unity Catalog に格納されているオブジェクトがすべて削除されます。必要な場合にのみ実行するようにしてください。たとえば、コンプライアンス要件を満たすために実行します。

系列データを削除するには、Unity Catalog オブジェクトを管理しているメタストアを削除する必要があります。メタストアの削除の詳細については、「メタストアを削除する」を参照してください。データは 90 日以内に削除されます。

データ系列 API

データ系列 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 ファイルを使用します。

Response

{
  "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 ファイルを使用します。

Response

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

Unity Catalog を使用したデータ系列のキャプチャと表示

要件

制限事項

例

系列をキャプチャして探索する

ワークフロー系列をキャプチャして表示する

ダッシュボードの系列をキャプチャして表示する

系列のアクセス許可

系列データを削除する

データ系列 API

テーブルの系列を取得する

要求

Response

列の系列を取得する

要求

Response

フィードバック

フィードバック

その他のリソース