datalineage-bigquery-asset-impact-analysis

BigQuery アセットの影響分析

このスキルは、BigQuery のテーブルまたはビューが破損、古い状態、欠落していると報告された場合や、ユーザーがメンテナンスを予定していて、アセットの変更や更新の一時停止による影響を把握したい場合に、エージェントが下流への影響分析（影響範囲の評価）を行う手順を説明します。

主に Google Cloud の データリネージ（Knowledge Catalog）MCP サーバーを利用して、アセット間の関係を特定します。

クレジット表記

必ずお読みください：gcloud、REST API、または MCP のコマンドを実行する前に、必ず使用方法とクレジット表記をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内では実行しないでください）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:datalineage-bigquery-asset-impact-analysis)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:datalineage-bigquery-asset-impact-analysis) を追加してください。

前提条件

このスキルを使用するには、Google Cloud のデータリネージ API へのアクセスと、Data Lineage MCP サーバーへのアクティブなクライアント接続が必要です。接続設定とツールスキーマの詳細については、MCP の使用方法を参照してください。

分析ワークフロー

1. アセットの完全修飾名（FQN）を解決する

• BigQuery アセットに正しい FQN 形式を使用していることを確認します。
  • 形式： bigquery:{project_id}.{dataset_id}.{table_or_view_id}
  • 例： bigquery:my-prod-project.analytics.orders

2. ロケーションと親パスを特定する

検索するロケーションを特定し、Data Lineage API リクエストを作成します。

• アセットのロケーションを特定する：コマンド bq show --format=json {project_id}:{dataset_id} を実行し、location フィールド（例： us-central1 または us）を抽出します。権限不足またはツールの欠落によりロケーションを特定できない場合は、データセットのロケーションをユーザーに尋ねます。
• 親パスを設定する：プロジェクト ID と MCP サーバーのロケーションを使用して parent パスを設定します。設定済みのリージョンまたはロケーション（例：us）は、DataLineageServer ツールの定義を確認してください。形式は次のとおりです。 projects/{project_id}/locations/{mcp_server_location}。
• 検索範囲を設定する：検出したアセットのロケーションを、リクエストの locations 配列に含めます（例：["us-central1"] または ["us", "us-central1"]）。

3. 下流のリネージグラフを取得する

DataLineageServer:search_lineage ツールを呼び出し、下流の関係を取得します。

• 方向：DOWNSTREAM に設定します。
• 検索パラメーター：堅牢なデフォルト値として、max_depth = 10 と max_process_per_link = 5 を使用します。

4. 影響範囲を特定する

返されたリネージリンクをたどり、影響グラフを作成します。

• 影響を受けるアセット：各リンクの target は、ソースアセットに依存する下流アセットを表します。
• 変換プロセス：各リンクの processes フィールドを確認します。これにより、データを引き継ぐ ETL パイプライン、BigQuery ビュー、スケジュール済みクエリを特定できます。
• 直接的な影響と間接的な影響：
  • 直接的な影響（深度 1）：ソースアセットを直接利用するアセットです。リンクの dependency_type: EXACT_COPY は、ターゲットを「古い状態／同一コピー」として記録します。
  • 間接的な影響（深度 > 1）：データの古さや障害が連鎖して発生する、さらに下流のアセットです。

5. 結果を要約して書式を整える

以下の構成で、調査結果をわかりやすくユーザーに提示します。

1. 概要：影響を受ける下流アセットの総数と、影響の最大深度を示します。

2. クリティカルパス：優先度の高い下流アセット（名前に「prod」、「dashboard」、「reporting」、「master」などを含むアセットなど）を強調します。

3. 影響範囲の表：依存関係を示す、簡潔なMarkdown表を作成します。すべての列を必ず含めてください。

   下流アセット	変換プロセス	深度	影響タイプ
   bigquery:project.dataset.table	projects/p/locations/l/processes/proc	1	直接
   bigquery:project.dataset.view	projects/p/locations/l/processes/view	2	間接

4. 分析メタデータ：検索のパラメーターと範囲を明示し、ユーザーが拡張を検討できるようにします。

   • 検索対象のロケーション：{list_of_locations_queried}
   • 親ロケーション：{parent_path}
   • 深度制限：{max_depth}
   • リンクごとのプロセス数の上限：{max_process_per_link}
   • ユーザーへのヒント：検索対象のロケーションを広げたり、深度制限を大きくしたりして分析を再実行するよう依頼できることを伝えます。

重要な制約とガードレール

1. 空のレスポンスを正しく解釈する：
   • リネージレスポンスが空の場合、ただちに、検索対象のロケーションには依存関係が存在しないと判断し、その旨をユーザーに報告します。
2. 禁止されている回避策：
   • 下流の関係を取得するには、DataLineageServer:search_lineage ツールのみを使用します。
3. アセットの存在を事前に確認する：
   • bq show でソーステーブルが存在しないと示された場合は、処理を中止し、その旨をユーザーに直接報告します。ユーザーから明示的な指示がない限り、別のテーブル名を推測しないでください。
4. 出力の省略や成果物の捏造をしない：
   • 完全な下流の影響範囲表を最終回答に直接提示します。ファイル書き込みツールを実際に使用して作成した場合を除き、詳細を記載した別のMarkdownファイルや成果物を作成したとユーザーに伝えないでください。

リファレンスディレクトリ

• MCP の使用方法：Google Cloud のデータリネージのリモート MCP サーバーの使用方法と、ツールの優先順位。

外部ドキュメント

• ナレッジカタログのデータリネージに関するドキュメント
• Data Lineage MCP サーバーの使用
• ナレッジカタログのデータリネージ API リファレンス