データアセットのコンテキストを取得する

データのコンテキストは、AI アプリケーションにデータアセットに関する深い理解を提供し、LLM が生成するレスポンスの精度と関連性を向上させます。

lookupContext メソッドは、単一の API リクエストを使用してコンテキストのギャップを埋め、インタラクティブな Agentic Workflows に最適化されたアセットのメタデータの事前フォーマット済みバンドルを取得します。このコンパクトで LLM 対応のコンテキストを使用して、エージェントがデータアセットを評価して使用する際の根拠とすることができます。

lookupContext メソッドは、Knowledge Catalog に保存されている任意のデータアセット（BigQuery テーブル、データセット、ルーティンなど）や、データ ドメイン、その他のエントリに使用できます。

エージェントはどのようにしてデータ コンテキストを取得できますか？

1. エージェントは、コンテキストの取得に関連する可能性のあるデータアセットを取得します（Knowledge Catalog のセマンティック検索などを使用）。
2. エージェントは lookupContext メソッドを使用して、特定の資産のコンテキストを取得する単一の API 呼び出しまたは MCP ツール リクエストを行います。

3. このメソッドは、事前フォーマットされたテキスト ブロックを含むレスポンスを返します。リクエストで指定する format パラメータに応じて、ドキュメントは YAML、XML、JSON 形式になります。

   レスポンスには次のコンテキスト要素が含まれます。

   コンテキスト要素	説明
   テクニカル メタデータ	リソース スキーマと物理構成（BigQuery のパーティション分割とクラスタリング戦略、引数、戻り値の型、ソースコードを含む BigQuery ルーティン定義など）。
   運用メタデータ	過去のクエリログとデータ分析情報に基づく結合やその他の関係。詳細については、データ関係を表示するをご覧ください。
   ビジネスの説明	関連するビジネス用語、概要、カタログ アノテーション、ソースシステムでキャプチャされ Knowledge Catalog で自動生成された説明、ガイドライン。 注: データアセットのガイドライン アスペクトを使用すると、エージェントがデータアセットを検出、検査、使用する際に役立つ追加のコンテキストをキャプチャできます。
   データ プロファイル	分布統計、個別の値の数、null 比率、サンプル値。
   データ品質	事前定義されたルールに対する自動データ品質チェックの出力。
   関連するデータアセットのコンテキスト	関連するデータアセットのコンテキスト（用語集の用語や、頻繁に結合されるテーブルなどの関連アセット）。関連アセットに対して返されるコンテキストには、メインアセットと同じ範囲の要素が含まれます。

4. エージェントはこのレスポンスを使用して、関連するアセットの選択や使用をガイドします。

始める前に

lookupContext メソッドを使用する前に、必要なロールが付与され、必要な API が有効になっていることを確認してください。

必要なロール

lookupContext メソッドを呼び出すために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するように管理者へ依頼してください。 Google Cloud iam.gserviceaccount.com

• エントリ、エントリ グループ、用語集などのカタログ リソースへの読み取りアクセス: Dataplex Catalog 閲覧者 （roles/dataplex.catalogViewer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

API を有効にする

lookupContext メソッドを使用するには、プロジェクトで次の API を有効にします。

• Knowledge Catalog API

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、所有者ロール（roles/owner）を介してこの権限が付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

API の有効化

データアセットのコンテキストを取得する

データアセットのコンテキストを取得するには、lookupContext メソッドに Dataplex API で直接アクセスするか、Knowledge Catalog リモート Model Context Protocol（MCP）サーバー または データベース向け MCP ツールボックス を使用します。

lookupContext メソッドは、権限に基づいてリソースをフィルタします。レスポンスには、ID にアクセスするために必要な Identity and Access Management（IAM）権限が付与されているアセットのデータのみが含まれます。リクエストされたリソースに対する権限がない場合、このメソッドは空のレスポンスを返します。

REST

データアセットのコンテキストを取得するには、次のリクエストを送信します。

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

次のように置き換えます。

• PROJECT_ID: プロジェクト Google Cloud の ID
• LOCATION: アセット が存在するリージョン（us-central1 など）
• RESOURCES：コンテキストを取得するエントリ名（最大 10 個）。projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry} の形式で指定します。 複数のリソースの場合、API はリクエストされたリソース間の関係（頻繁なスキーマ結合など）を確立し、コンテキストに関係情報を返します。
• OPTIONS: コンテキストを定義できるオプション:
  • format はコンテキスト ファイルの形式です。例: yaml
  • context_budget は、レスポンスが制限される文字数です。all_schema_fields パラメータを true に設定すると、API は context_budget 値に関係なくすべてのスキーマ フィールドを返します。

BigQuery テーブルのコンテキストを取得するリクエストの例は次のとおりです。

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

レスポンスは、次のような事前フォーマットされたテキスト ブロックです。

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

このサンプルを試す前に、Python の設定手順を Knowledge Catalog クイックスタート: クライアント ライブラリの使用にあるを完了してください。 詳細については、 Knowledge Catalog Python API のリファレンス ドキュメントをご覧ください。

Knowledge Catalog への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、 ローカル開発環境の認証の設定をご覧ください。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

次の例は、BigQuery テーブルのコンテキストを取得する方法を示しています。

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

ルーティンのコンテキストを取得する

lookupContext メソッドを使用すると、 BigQuery ルーティン（ユーザー定義関数、テーブル関数、ストアド プロシージャなど）のコンテキストを取得できます。エージェントはこのコンテキストを使用して、ルーティンの機能と呼び出し方法を把握できます（SQL クエリの生成時など）。ルーティンのコンテキストには次の情報が含まれます。

• ルーティンのタイプ（スカラー関数、テーブル関数、プロシージャなど）。
• ルーティンの言語。
• ルーティンの引数と戻り値の型。
• ルーティンのソースコード（定義本文）。
• Knowledge Catalog の説明やその他のメタデータ。

ルーティンのコンテキストを取得するには、 resources リストにルーティンのエントリ名を含めます。エントリ名の形式は次のとおりです。

projects/PROJECT_ID/locations/LOCATION/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID

次のように置き換えます。

• PROJECT_ID: ルーティンを含むプロジェクトの ID。
• LOCATION: ルーティンを含むデータセットのロケーション（us など）。
• DATASET_ID: ルーティンを含むデータセットの ID。
• ROUTINE_ID: ルーティンの ID。

コンテキスト検索のベスト プラクティスは何ですか？

lookupContext メソッドを使用する際に結果を最適化するには、次のベスト プラクティスを検討してください。

• context_budget パラメータを使用して、出力コンテキストの選択した長さをリクエストします。lookupContext メソッドは、パラメータで指定された制限内で、最も関連性の高いコンテキストを出力にできるだけ収めることを目指します。
• resources リストには最大 10 個のデータアセットを一覧表示できます。たとえば、resources リストに複数のテーブルを含めると、API はそれらのテーブルだけでなく、それらのテーブル間の結合パスのコンテキストも提供するため、これらのテーブルを一緒に使用する方法に関する必要なガイダンスを提供できます。
• LLM またはエージェントの解析ロジックに最適な yaml や json などの format オプションを使用して、コストのかかる変換を回避します。

次のステップ

• データを検出するエージェントを構築する方法を学習する。
• メタデータを拡充するエージェントを構築する方法を学習する。
• Knowledge Catalog の検索構文を理解する。
• データ関係の表示について学習する。