2026 年 4 月 10 日より、Dataplex Universal Catalog は Knowledge Catalog と呼ばれるようになりました。API、クライアントライブラリ、CLI、IAM の名前は変更されません。詳細については、Google Cloud Knowledge Catalog の概要をご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Antigravity CLI を使用してデータコンテキストをテストする

Knowledge Catalog（旧称: Dataplex Universal Catalog）のメタデータ拡充により、構造化データのコンテキストを提供できるため、AI エージェントは信頼できる認定ソースに基づいて回答をグラウンディングできます。このチュートリアルでは、サンプルの BigQuery テーブルにカスタムアスペクトをアタッチし、Antigravity CLI を使用して、AI エージェントがガバナンスルールをどのように適用するかをテストします。

目標

テスト用に、BigQuery に現実的な多層データレイクをデプロイする。
Knowledge Catalog でカスタムメタデータテンプレート（アスペクトタイプ）を設計して登録し、公式のデータプロダクトと未加工のサンドボックステーブルを区別します。
Antigravity CLI（agy）を使用して、データガバナンスルールと AI エージェントのグラウンディングを確認します。

始める前に

始める前に、次の操作を行ってください。

このチュートリアルで使用する Google Cloud プロジェクトを選択します。
プロジェクトに対して課金が有効になっていることを確認します。

このチュートリアルを完了するには、BigQuery と Knowledge Catalog の基本的な知識も必要です。

環境を準備する

このチュートリアルでは、クラウドで動作するコマンドライン環境である Google Cloud Shell を使用します。Antigravity CLI（agy）は Google Cloud Shell にプリインストールされています。

Google Cloud コンソールで、右上のツールバーにある [Cloud Shell をアクティブにする] をクリックします。環境がプロビジョニングされ、接続されるまでしばらく待ちます。
Cloud Shell で、PROJECT_ID 変数と REGION 変数を設定して、今後のすべてのコマンドが特定の Google Cloud プロジェクトをターゲットにするようにします。
```
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
```

必要な Google Cloud サービスを有効にします。

gcloud services enable \
  artifactregistry.googleapis.com \
  bigquery.googleapis.com \
  dataplex.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com

Google Cloud DevRel Demos リポジトリのクローンを作成します。

GitHub からインフラストラクチャコードとスクリプトをダウンロードします。スパースチェックアウトを使用して、このチュートリアルに必要な特定のフォルダのみを pull します。

# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos

# Specify and download only the folder you need for this tutorial
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

BigQuery にサンプルデータレイクをデプロイする

現実世界のデータ環境がクリーンであることはめったにありません。AI エージェントは推論できますが、特定の企業に関する知識はゼロから始まります。エージェントに「第 1 四半期の収益は？」と質問したとします。ガイダンスがない場合、エージェントは、公式レポートから未加工のテストデータまで、データベース内の「revenue」という名前の数十のテーブルから選択する可能性があります。エージェントが最も近い名前のテーブルを選択すると、未検証のソースに基づいて、説得力のある誤った回答が返される可能性があります。

このシナリオをシミュレートするには、「公式」データマートと信頼できない「サンドボックス」テーブルを組み合わせる必要があります。設定スクリプトを使用して、BigQuery のデータセットとテーブルをデプロイします。

設定スクリプトを実行可能にして、実行します。これにより、3 つの BigQuery データセット（finance_mart、marketing_prod、analyst_sandbox）が作成され、テーブルにサンプルデータが入力されます。

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

これで、データが完全に格納されたデータレイクが作成されましたが、ガバナンスは適用されていません。AI エージェントにとって、すべてのテーブルはまったく同じように見えます。

Knowledge Catalog でカスタムアスペクトタイプを定義する

次に、データガバナンスのルールを定義します。Knowledge Catalog でこれを行うには、再利用可能な、厳密に型指定されたメタデータテンプレートであるアスペクトタイプを作成します。

このセクションでは、gcloud CLI を使用してこのテンプレートを登録し、定義方法を確認します。

アスペクトテンプレートのスキーマを調べる

aspect_template.json の内容を出力して、スキーマ定義を確認します。

cat aspect_template.json

次の JSON 構造が表示されます。

{
  "name": "OfficialDataProductSpec",
  "type": "record",
  "recordFields": [
    {
      "name": "product_tier",
      "type": "enum",
      "enumValues": [
        { "name": "GOLD_CRITICAL", "index": 1 },
        { "name": "SILVER_STANDARD", "index": 2 },
        { "name": "BRONZE_ADHOC", "index": 3 }
      ],
      ...
    },
    {
      "name": "is_certified",
      "type": "bool",
      "...": "..."
    }
  ]
}

このスキーマでは、重要度ティア（GOLD_CRITICAL、SILVER_STANDARD、BRONZE_ADHOC）の enum や is_certified の bool など、厳格なデータ型が適用されます。これにより、メタデータが構造化され、機械で読み取り可能な状態が維持されます。

Knowledge Catalog にアスペクトタイプを登録する

次の gcloud コマンドを実行して、このテンプレートをナレッジカタログレジストリに登録します。

gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --description="Defines the comprehensive profile of a data product for data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

データレイクテーブルにガバナンスアスペクトを適用する

これは重要なエンジニアリングステップです。現時点では、テーブル finance_mart.fin_monthly_closing_internal と analyst_sandbox.tmp_data_dump_v2_final_real は AI エージェントにとって同じように見えます。これらは列を持つオブジェクトにすぎません。

これらを区別するために、アスペクトを適用します。アスペクトは、認定されたメタデータラベルをこれらのテーブルにアタッチして区別します。実際の企業では、CI/CD パイプラインを使用してこれを自動化します。このチュートリアルでは、スクリプトを使用してその自動化をシミュレートします。

アスペクトメタデータペイロードを生成する

Knowledge Catalog のアスペクトキーは、グローバルに一意である必要があります（プロジェクト ID が接頭辞として付加されます）。./generate_payloads.sh スクリプトは、YAML メタデータファイルを動的に生成します。

chmod +x ./generate_payloads.sh
./generate_payloads.sh

これにより、さまざまなデータガバナンスシナリオ（fin_internal.yaml、fin_public.yaml、mkt_realtime.yaml、sandbox.yaml）を定義する 4 つの YAML ファイルを含む aspect_payloads/ ディレクトリが作成されます。

BigQuery テーブルにアスペクトを適用する

スクリプトを実行する前に、テーブルにアタッチするデータを確認します。次のコマンドを実行して、内部財務データのメタデータを表示します。
```
cat aspect_payloads/fin_internal.yaml
```
YAML ファイルは、テーブルのビジネスコンテキストを定義します。
```
your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true
```
このプロンプトでは、is_certified: true の設定や GOLD_CRITICAL ティアの割り当てなど、ビジネスコンテキストが明示的に定義されています。これにより、AI エージェントはテーブル名に基づいて推測するのではなく、明確で構造化されたルールを評価できます。
アプリケーションスクリプトを実行します。このスクリプトは、BigQuery テーブルを反復処理し、gcloud dataplex entries update コマンドを使用してメタデータペイロードを各テーブルにアタッチします。
```
chmod +x ./apply_governance.sh
./apply_governance.sh
```

Google Cloud コンソールで適用されたアスペクトを確認する

次に進む前に、スクリプトが Google Cloud コンソールでアスペクトを正しく適用したことを確認します。

Google Cloud コンソールで [ナレッジカタログ] ページを開きます。上部にある検索バーを使って拡張機能を探すことができます。
fin_monthly_closing_internal を検索します。結果で BigQuery テーブル名を選択して、詳細ページを開きます。
下部の [オプションのタグとアスペクト] セクションで、official-data-product-spec アスペクトを見つけます。値が、適用した「ゴールド内部」シナリオと一致していることを確認します。

これで、技術的に同一の BigQuery テーブル（fin_monthly_closing_internal と tmp_data_dump_v2_final_real）が、機械で読み取り可能なメタデータによって論理的に区別されていることを確認できました。

Antigravity CLI でデータコンテキストをテストする

アプリケーションをビルドする前に、Antigravity CLI を使用してデータガバナンスロジックをローカルで検証できます。これを行うには、Knowledge Catalog プラグインをインストールし、エージェントスキルを構成します。

Knowledge Catalog プラグインをインストールする

Cloud Shell で、サービスプラグインをインストールします。

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

エージェントスキルの定義を検査する

エージェントスキルは、.agents/skills/knowledge-catalog-governance/SKILL.md にある静的で再利用可能な定義ファイルです。これには、「安全なデータが必要」などの抽象的な人間のルールを構造化された技術的なルックアップに変換するロジックが含まれています。

スキルの設定を確認し、データコンテキストの仕組みを理解するには、SKILL.md ファイルを調べます。

cat .agents/skills/knowledge-catalog-governance/SKILL.md

このプロンプトは、フェーズ 1（メタデータの検証）とフェーズ 2（クエリの実行）のループを厳密に実行するようモデルに指示しています。モデルは、SQL ステートメントを構築する前にメタデータを検出して検証する必要があります。この検索ファーストのロジックにより、エージェントがテーブル名を推測したり、未検証のソースから回答をハルシネーションしたりすることを防ぎます。

Antigravity CLI セッションを開始する

Antigravity CLI セッションを開始します。プロジェクトフォルダにいるため、CLI は .agents/skills ディレクトリからスキルを自動的に検出して読み込みます。

agy

CLI でプラグインのインストールを確認する

Antigravity CLI プロンプトで、プラグインが有効になっていることを確認します。「/mcp」と入力して、構成済みのツールとプラグインを一覧表示します。

/mcp

出力には、knowledge-catalog がアクティブなプラグインとして表示され、使用可能なツールが表示されます。

MCP Servers ... >  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

データコンテキスト検証シナリオを実行する

次に、データコンテキストを実際に確認します。これらのプロンプトを Antigravity CLI セッションに 1 つずつ貼り付けます。

シナリオ 1: 認定ゴールドティアデータを取得する

Antigravity CLI が、重要な取締役会のために最も信頼できるデータを見つけられるかどうかを確認します。

We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?

CLI は元データをスキップして fin_monthly_closing_internal を見つける必要があります。これは、以前に適用した GOLD_CRITICAL タグと INTERNAL_ONLY タグに対して「最終版」データと「機密」データのリクエストを照合することで行われます。

シナリオ 2: 外部で承認されたデータに取得を制限する

データを外部と共有したいとします。CLI で内部シークレットが漏洩しないようにする必要があります。

I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?

内部テーブルには最も詳細な情報が含まれていますが、CLI はそれをバイパスする必要があります。EXTERNAL_READY というタグが付けられたテーブルはのみであるため、fin_quarterly_public_report が表示されます。

シナリオ 3: リアルタイムストリーミングデータを取得する

データサイエンティストは、最新の情報を必要とすることがよくあります。Antigravity CLI が、1 日 1 回のバッチ処理とライブ配信の違いを理解しているかどうかを確認します。

My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?

CLI で mkt_realtime_campaign_performance が見つかるはずです。メタデータ内の REALTIME_STREAMING の更新の頻度を識別します。

シナリオ 4: 認定されていないサンドボックスデータを探索する

「完璧」よりも「十分」の方が良い場合もあります。Antigravity CLI で、試験運用版の ML 作業用の未加工のサンドボックスデータを見つけられるかどうかを確認します。

I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment.

CLI で tmp_data_dump_v2_final_real が見つかるはずです。この選択が正しいのは、BRONZE_ADHOC ティアと一致し、is_certified: false で明示的にマークされているためです。

テストが完了したら、CLI セッションを終了します。

/quit

クリーンアップ

定期的な請求が発生しないようにするには、次の手順を行います。

Antigravity CLI セッションにいる場合は、Ctrl+C を 2 回押すか、/quit と入力してセッションを終了します。
クリーンアップスクリプトを実行して、このチュートリアルで作成した BigQuery テーブル、データセット、Knowledge Catalog のアスペクトタイプを破棄します。
```
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
```
サービスプラグインをアンインストールし、ローカルのデモファイルを削除します。
```
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos
```

次のステップ

他の Knowledge Catalog のユースケースを試す。

Antigravity CLI を使用してデータ コンテキストをテストする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

目標

始める前に

環境を準備する

BigQuery にサンプル データレイクをデプロイする

Knowledge Catalog でカスタム アスペクト タイプを定義する

アスペクト テンプレートのスキーマを調べる

Knowledge Catalog にアスペクト タイプを登録する

データレイク テーブルにガバナンス アスペクトを適用する

アスペクト メタデータ ペイロードを生成する