datalineage-summary

データリネージの概要

このスキルでは、特定の中心アセット（テーブルレベルのリネージ）または特定のフィールド（カラムレベルのリネージ）について、データリネージグラフを調査し、要約する方法をエージェントに案内します。複雑なノードやリンクの詳細を平易な日本語に置き換え、データがアセットにどのように入り、どのように出ていくかを、直感的な左から右への流れで説明します。

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用時の帰属情報をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内での実行は不可）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:datalineage-summary)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:datalineage-summary) を追加してください。

前提条件

このスキルでは、グラフのたどり先を取得するために、Google Cloud の data lineage (Knowledge Catalog) MCP Server を使用します。上流と下流の両方向で search_lineage クエリを実行できることを確認してください。接続設定とツールスキーマの詳細については、MCP の使用方法を参照してください。

ワークフローのロジック

1. リネージの取得

中心点から両方向（上流と下流）のリネージグラフを取得するには、MCP ツールを別々に2回呼び出します。1回は "direction": "UPSTREAM"、もう1回は "direction": "DOWNSTREAM" を指定します。

• ロケーションの方針：提供されたKnowledge Catalog のロケーションリンクから read_url ツールを使用して、ロケーションの包括的な一覧を動的に取得する必要があります。クロスリージョンのリネージを見逃さないよう、locations 配列に値を設定する前に、このリンクで Google Cloud の現在のリージョン一覧を必ず確認してください。このリンクから取得した、サポート対象のすべての物理リージョンを locations 配列に設定する必要があります。必要に応じて、bq show または gcloud storage ls を使って、アセットが実際に存在するリージョンを確認してもかまいません。

• 検索パラメーター：search_lineage を呼び出す際は、堅牢なデフォルト値として maxDepth = 10、maxResults = 5000、maxProcessPerLink = 10 を使用してください。たとえば、DOWNSTREAM 呼び出しは次のように指定します（必要に応じて locations 配列を拡張してください）。

  {
    "parent": "projects/project_id/locations/us",
    "locations": [
      "us",
      "us-central1",
      "us-east1",
      "us-west1",
      "europe-west1",
      "asia-northeast1"
    ],
    "rootCriteria": {
      "entities": {
        "entities": [
          {
            "fullyQualifiedName": "bigquery:project.dataset.table"
          }
        ]
      }
    },
    "direction": "DOWNSTREAM",
    "limits": {
      "maxDepth": 10,
      "maxResults": 5000,
      "maxProcessPerLink": 10
    }
  }
  

  上流のリネージを取得するには、同様に "direction": "UPSTREAM" を指定して呼び出してください。

• カラムレベルのリネージ（CLL）：search_lineage ツールでは、field 配列を設定することで、すべてのカラムレベルのリネージ（CLL）を取得できます。テーブルレベルのリネージ（TLL）が必要な場合は、"*" ワイルドカードを使用して、TLL リンクとあわせて CLL リンクも取得するように設定してください。たとえば、次のように指定します。

  "rootCriteria": {
    "entities": {
      "entities": [
        {
          "fullyQualifiedName": "bigquery:project.dataset.table",
          "field": [
            "*"
          ]
        }
      ]
    }
  }
  

  特定のカラムを評価する場合は、"*" をカラム名（例："efficiency_score"）に置き換えてください。

2. 要約

以下のプロンプトのガイドラインに従って要約を生成します。

• ペルソナ：データリネージュの専門アナリストとして、データフローを左から右へ簡潔でわかりやすく説明してください。
• 構成と流れ：要約本文からすぐに始め、次の構成にしてください。
  • 全体的なフローの種類：推定されるワークフローの種類とデータドメインを示します （例：「これは特徴量エンジニアリングのワークフローと思われます……」）。
  • システムの概要：関係する主要なシステムを最初に列挙します。列レベルのリネージュを求められた場合は、分析範囲が指定されたフィールドに限定されることを、最初に明示しなければなりません。
  • 上流のリネージュ：正確な太字の見出し **Upstream Lineage:** を使用します。中心となるアセットにデータがどのように到達するかを説明し、主要なソースシステム、プロジェクト、処理タスク（Dataproc 上の Spark など）に触れてください。
  • 下流のリネージュ：正確な太字の見出し **Downstream Lineage:** を使用します。中心となるアセットから最終的な利用システムにデータがどのように流れるかを詳しく説明してください。
  • 分析メタデータ：要約の範囲を明確にするため、API 呼び出しで使用したパラメーターを表示します。出力には次の項目を含めてください。
    • 検索対象の場所：{list_of_locations_queried}
    • 親の場所：{parent_path}
    • 深さの上限：{maxDepth}
    • リンクあたりのプロセス数の上限：{maxProcessPerLink}
    • ユーザーへのヒント：すべての場所が検索されていない場合は検索対象の場所を拡張する、または深さを増やして再実行するよう提案するプロンプト。
• 詳細度の制約：
  • 個々のファイルやテーブルよりも、システム、プロジェクト、データセット間のフローを優先してください。
  • アセットが5個未満の場合は、具体的なアセット名（ソーステーブル、中間ビュー、利用側のテーブルなど）を必ず列挙してください。5個未満の場合に件数だけで要約してはいけません。5個以上の場合は、件数でまとめてください（例：「Cloud Storage バケット5個」）。
  • 件数を記載するのは、最終的なソース、最終的な利用先、アセットの合計数に限ります。
  • プロジェクトが1つだけの場合は、データセットごとにプロジェクト名を繰り返さないでください。
• 文体：専門用語や「明確な事実がそれぞれ存在します」のような一般的な表現は避けてください。簡潔でわかりやすく記述してください。最終出力は Markdown にしてください。

3. 要約を返す

最終的な要約をユーザーに返します。

外部ドキュメント

• Knowledge Catalog Data Lineage Documentation
• Use the Data Lineage MCP server
• Knowledge Catalog Data Lineage API Reference