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

データを取り巻くコンテキストにより、AI アプリケーションはデータ資産を深く理解し、LLM で生成されたレスポンスの精度と関連性を高めることができます。

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

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

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

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

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

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

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

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

始める前に

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

必要なロール

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

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

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

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

API を有効にする

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

• Knowledge Catalog API

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

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

API の有効化

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

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

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

このサンプルを試す前に、クライアント ライブラリを使用した Knowledge Catalog のクイックスタートにある Python の設定手順を行ってください。詳細については、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 メソッドを使用する際の成果を最適化するには、次のベスト プラクティスを参考にしてください。

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

次のステップ

• データを検出するエージェントを構築する方法について学習する。
• メタデータを拡充するエージェントを構築する方法を学習する。
• Knowledge Catalog の検索構文を理解する。
• 詳しくは、データ リレーションを表示するをご覧ください。