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

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

dbt Core からメタデータをインポートする

このドキュメントでは、gcloud コマンドを使用して、dbt Core と MetricFlow から Knowledge Catalog（以前の Dataplex Universal Catalog）にメタデータをインポートする方法について説明します。

dbt インテグレーションによってキャプチャされるメタデータは次のとおりです。

技術メタデータ: 主要なリソース（ソース、シード、モデル）とその技術プロパティ（列名、データ型、行数）が含まれます。
ビジネスメタデータとセマンティックメタデータ: dbt MetricFlow を活用し、セマンティックモデル、指標、保存済みクエリなどのビジネス定義とロジックが含まれます。
運用メタデータとデータ品質メタデータ: タイミング、成功または失敗のステータス、データの更新速度、テストとテスト結果などの実行メタデータが含まれます。
リネージと関係のメタデータ: 変換グラフ（DAG）と dbt リソース間の依存関係、物理変換ブロックを追跡してリンクする物理リネージ、結合キーと動的結合、親子関係が含まれます。
使用状況のメタデータ: dbt の外部でデータがどのように使用されているかをマッピングする、エクスポージャーでキャプチャされたメタデータが含まれます。

dbt Core と MetricFlow からメタデータをインポートする前に、次のタスクを完了します。

必要なロールと権限を付与します。
Knowledge Catalog API を有効にします。
dbt の前提条件を満たします。
宛先エントリグループがまだ存在しない場合は、作成します。
Cloud Storage のロールを理解する。

IAM のロールと権限

Knowledge Catalog コネクタジョブを作成して管理するには、Knowledge Catalog と Cloud Storage の権限を付与する Identity and Access Management（IAM）ロールが必要です。

dbt コネクタの構成に必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。

エントリグループを作成して管理するには: プロジェクトに対する Dataplex Catalog 管理者（roles/dataplex.catalogAdmin）、Dataplex Catalog 編集者（roles/dataplex.catalogEditor）、または Dataplex エントリグループオーナー（roles/dataplex.entryGroupOwner）。
dbt gcloud コマンドを実行してメタデータインポートジョブを作成する: 最小権限の原則に従って、次のロールを付与します。
- プロジェクトに対する Dataplex メタデータジョブオーナー（roles/dataplex.metadataJobOwner）。
- ターゲットエントリグループまたはプロジェクトに対する Dataplex エントリグループインポータ（roles/dataplex.entryGroupImporter）。
または、プロジェクトに対する Dataplex Catalog 管理者（roles/dataplex.catalogAdmin）ロールと Dataplex メタデータジョブオーナー（roles/dataplex.metadataJobOwner）ロールを付与することもできます。
変換されたメタデータを出力ステージングバケット（--storage-uri）にアップロードするには、ステージングバケットに対するストレージオブジェクト作成者（roles/storage.objectCreator）またはストレージオブジェクト管理者（roles/storage.objectAdmin）の権限が必要です。
入力 Cloud Storage バケットから dbt アーティファクトを読み取る（Cloud Storage を使用している場合は --artifacts-path）: 入力アーティファクトバケットに対するストレージオブジェクト閲覧者（roles/storage.objectViewer）またはストレージオブジェクト管理者（roles/storage.objectAdmin）。Storage オブジェクト管理者ロールがある場合、Storage オブジェクト閲覧者ロールは必要ありません。
dbt メタデータを表示するには: プロジェクトに対する Dataplex Catalog 閲覧者（roles/dataplex.catalogViewer）。
Cloud Logging でログを表示するには: プロジェクトに対するログビューア（roles/logging.viewer）。

また、インポートジョブがステージングされたメタデータファイルを読み取れるように、出力ステージング Cloud Storage バケット（--storage-uri）に対する Storage オブジェクト閲覧者（roles/storage.objectViewer）ロールを Knowledge Catalog サービスエージェント（service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com）に付与する必要があります。

ロールの付与の詳細については、アクセスの管理をご覧ください。

API を有効にする

Knowledge Catalog API を有効にします。

API の有効化

dbt の前提条件

dbt メタデータの完全なセットをインポートするには、4 つの dbt JSON アーティファクトファイルをすべて生成することをおすすめします。manifest.json のみが必要です。他のものはインポートを強化するもので、それらがなくても変換は正常に機能します。

manifest.json （必須）: コアプロジェクトの構造と実行グラフ。MetricFlow のセマンティックモデル、指標、保存済みクエリも含まれます。
catalog.json: 列名とデータ型。catalog.json がないと、スキーマアスペクトは型指定されていない列とともにインポートされます。
run_results.json: テスト結果と実行メタデータ。
sources.json: ソースの鮮度。

dbt メタデータアーティファクト JSON ファイルの完全なセットを生成するには、次の dbt コマンドをこの順序で実行します。

dbt source freshness
dbt build
dbt docs generate --no-compile

警告: --no-compile がないと、dbt docs generate はすべてのノードの run_results.json を success ステータスで上書きします。上記の dbt build のテスト結果が失われ、カタログはすべてのデータ品質テストを合格としてレポートします。

Cloud Storage のロールについて

dbt メタデータのインポートには、異なる目的で使用される 2 つの異なる Cloud Storage ロケーションが関係します。これらを混同しないでください。

入力（dbt ソースアーティファクト）: 生成された dbt JSON ファイルが存在する場所。これは、マシンまたは CI ランナー（./target/ や . など）のローカルディレクトリパス、または入力 Cloud Storage バケット URI 接頭辞（gs://my-dbt-artifacts-bucket/target/ など）にできます。このパスは --artifacts-path フラグを使用して指定します。gcloud コマンドは、ジョブの準備中にこれらの入力ファイルを読み取ります。Cloud Storage を使用する場合、gcloud コマンドを実行する呼び出し元には読み取りアクセス権（roles/storage.objectViewer または roles/storage.objectAdmin）が必要です。Knowledge Catalog サービスエージェントは、入力アーティファクトバケットにアクセスする必要はありません。
出力（Knowledge Catalog インポートステージングバケット）: gcloud コマンドが変換されたメタデータインポートファイル（dbt_metadata.jsonl）をアップロードする Cloud Storage バケット URI 接頭辞（gs://my-staging-bucket/dbt-imports/ など）。Knowledge Catalog インポートジョブは、取り込み中にこの接頭辞から読み取ります。この URI は --storage-uri フラグを使用して指定します。gcloud コマンドを実行する呼び出し元には、ファイルをアップロードするための書き込みアクセス権（roles/storage.objectCreator または roles/storage.objectAdmin）が必要です。また、Knowledge Catalog サービスエージェントには、ファイルをインポートするための読み取りアクセス権（roles/storage.objectViewer）が必要です。

dbt 接続を構成する

dbt 接続を確立するには、まず適切な dbt コマンドを実行してメタデータアーティファクトを生成する必要があります。JSON ファイルが保存され、アクセス可能になると、インポートプロセスで次のアクションが実行されます。

入力アーティファクトを読み取る: dbt Core と MetricFlow によって生成された JSON アーティファクトを、入力の場所（--artifacts-path で指定されたローカルディレクトリまたは Cloud Storage URI）から読み取ります。
メタデータを変換する: コンテンツを Knowledge Catalog メタデータインポート形式（dbt_metadata.jsonl）に変換します。
ステージングにアップロード: 変換されたメタデータインポートファイルを、--storage-uri で指定された出力ステージングの Cloud Storage の場所にアップロードします。
インポートジョブをトリガーする: Knowledge Catalog サービスエージェントに、--storage-uri からステージングされたメタデータを読み取って Knowledge Catalog リソースに取り込むよう指示する Knowledge Catalog メタデータインポートジョブをトリガーします。

コンソール

Google Cloud コンソールで、[Knowledge Catalog] > [コネクタ] ページに移動します。

[コネクタ] に移動
[Add connection] をクリックします。
[コネクタ] リストで、[dbt Core と MetricFlow] カードを選択します。

注: dbt Core メタデータの取り込みでは、取り込み前にクライアントサイドの dbt アーティファクト JSON ファイル（manifest.json、catalog.json、run_results.json、sources.json）を Knowledge Catalog のインポート形式に変換する必要があるため、このカードを選択すると、CLI または API の手順が表示されます。
インポートした dbt アセットを表示するには、[検索] ページに移動するか、宛先のエントリグループ ページを表示します。

gcloud

dbt メタデータジョブを作成する手順は次のとおりです。

dbt メタデータアーティファクトファイルがローカルまたは入力 Cloud Storage バケットに保存されていることを確認します。
呼び出し元と Knowledge Catalog サービスエージェントの両方に適切な権限が構成された出力ステージング Cloud Storage バケットがあることを確認します。
Cloud Shell、ローカルターミナル、または自動ワークフローツールから、gcloud コマンドを実行します。
```
gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/
```
必須フラグ
- --storage-uri=STORAGE_URI: 変換された JSONL がアップロードされる （出力/ステージング）Cloud Storage URI 接頭辞（gs://bucket/path/）。インポートジョブは、取り込み中にこの接頭辞から読み取ります。呼び出し元には書き込みアクセス権（roles/storage.objectCreator または roles/storage.objectAdmin）が、Knowledge Catalog サービスエージェントには読み取りアクセス権（roles/storage.objectViewer）が必要です。
オプションフラグ
- --artifacts-path=ARTIFACTS_PATH: （入力）移行元 dbt アーティファクトのパス。これは、ローカルディレクトリパス（. や ./target など）または Cloud Storage URI 接頭辞（gs://my-bucket/dbt-artifacts/ など）にできます。dbt プロジェクトのルート（target/ サブディレクトリは自動的に検出されます）または manifest.json を含むディレクトリを直接指定できます。デフォルトは . です。Cloud Storage URI が指定されている場合、呼び出し元は入力バケットに対する読み取りアクセス権（roles/storage.objectViewer または roles/storage.objectAdmin）を持っている必要があります。
- --async: 処理中のオペレーションの完了を待たずに、直ちにコマンドを終了します。
- --entry-group=ENTRY_GROUP: dbt エントリを受け取るエントリグループの短い ID。プロジェクトとロケーションにすでに存在している必要があります（デフォルトは dbt-metadata-ingestion）。
- --aspects-only: この dbt 実行で検出されたメタデータのみを更新し、エントリグループの残りの部分は変更しません。エントリが作成、削除、再ペアレント化されることはありません。この実行で dbt アーティファクトがなかったアスペクトは、前の実行で与えられた値を保持します。これは、定期的な繰り返し取り込みに使用します。取り込みを再実行するをご覧ください。
- --validate-only: JSON を作成してアップロードし、メタデータジョブを検証しますが、実際には取り込みません。
ステータスが Created になっていることを確認します。

REST

REST API を使用して dbt メタデータをインポートするには:

dbt アーティファクトを生成し、Knowledge Catalog JSON インポートファイル（dbt_metadata.jsonl）に変換します。
変換されたファイルを Cloud Storage ステージングバケット（gs://BUCKET_NAME/PATH/）にアップロードします。

projects.locations.metadataJobs.create メソッドを呼び出します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

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

PROJECT_ID: エントリグループが配置されている Google Cloud プロジェクト ID。
LOCATION: エントリグループのリージョン（例: us-central1）。
JOB_ID: メタデータジョブの固有識別子。
BUCKET_NAME/PATH: dbt_metadata.jsonl がアップロードされた Cloud Storage URI 接頭辞。
ENTRY_GROUP: 宛先エントリグループの短い ID。

インポートジョブのステータスを追跡するには、projects.locations.metadataJobs.get メソッドを使用します。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

ジョブを作成すると、Knowledge Catalog は構成に従って初回実行をスケジュール設定するか、手動で開始できます。

取り込みを再実行する

最初のインポートの後、ほとんどの実行では、すでに存在するリソースのメタデータを更新するだけで済みます。これらの実行には --aspects-only を使用します。dbt 実行で検出されたもののみが更新され、エントリグループ内の他のものはそのまま残されるため、任意のスケジュールで、複数のジョブから繰り返し実行しても安全です。

エントリのセットが変更された場合は、完全な取り込みを実行します（--aspects-only は省略）。

エントリグループへの最初の取り込み。
dbt リソースが追加、名前変更、削除された。
エントリの表示名、説明、ラベルが変更された場合。
エントリ階層が変更されます。

フル実行では、ディスク上のアーティファクトからすべてのエントリの必要な側面が書き換えられるため、パイプラインで生成できる限り完全なアーティファクトセットから実行します。

定期的な更新には --aspects-only を実行します。

パイプラインが実行する dbt コマンド（dbt build、dbt test、dbt source freshness、または --select で絞り込んだ再ビルド）の後。
列が追加、削除、再入力、再記述された。
モデルの SQL が変更され、実行時に catalog.json も書き込まれました。
新しいテスト結果またはソースの鮮度。

--aspects-only はメタデータの追加と更新はできますが、削除はできません。

dbt メタデータを検索して表示する

コンソール

Google Cloud コンソールで、[Knowledge Catalog] の [検索] ページに移動します。

[検索] に移動
[フィルタ] パネルで、dbt アセットをフィルタします。
- [システム] セクションで、[インポートされたコンテキスト] を選択します。
- 表示された [マネージドコネクタ] サブセクションで、[dbt] を選択します。
検索フィールドに、キーワード検索または自然言語検索を使用してクエリを入力します。たとえば、キーワード検索を使用してすべての dbt アセットを表示するには、「system=DBT」または「system=DBT AND type=dbt-model」と入力します。
検索結果で、任意の dbt アセットをクリックしてエントリの詳細ページを開き、スキーマ、リネージ、技術的な側面を表示します。

gcloud

プロジェクト全体で dbt エントリを検索するには、gcloud dataplex entries search コマンドを使用します。
```
gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID
```
特定の dbt エントリタイプ（モデルやソースなど）でフィルタするには:
```
gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID
```
特定の dbt エントリの詳細と側面を表示するには、gcloud dataplex entries lookup コマンドを使用します。
```
gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL
```
次のように置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- LOCATION: エントリグループのロケーション（例: us-central1）。
- ENTRY_GROUP: 宛先エントリグループの短い ID（例: dbt-metadata-ingestion）。
- ENTRY_ID: dbt エントリの短い ID または相対リソース名。

REST

dbt エントリを検索するには、projects.locations:searchEntries メソッドを呼び出します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

特定の dbt リソースタイプでフィルタするには:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

特定のエントリの完全なメタデータ詳細とアスペクトを取得するには、projects.locations.entryGroups.entries.get メソッドを呼び出します。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

特定の dbt リソースの LLM コンテキストを取得するには、projects.locations:lookupContext API を使用します。
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'
```
次のように置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- LOCATION: エントリグループのロケーション（例: us-central1）。
- ENTRY_GROUP: 宛先エントリグループの短い ID（例: dbt-metadata-ingestion）。
- ENTRY_ID: dbt エントリの短い ID または相対リソース名。

リソースの検索の詳細については、Knowledge Catalog でリソースを検索するをご覧ください。クエリ式とフィルタの詳細については、Knowledge Catalog の検索構文をご覧ください。

制限事項

最近の dbt Core v1 バージョンをサポートします（バージョン 1.11 と 1.12 で検証済み）。dbt Core v2 と dbt Fusion は対象外です。
モデルのバージョニングを使用する dbt モデルは対象外です。
dbt Cloud はサポートされていません。
非常に大きいスキーマやネストが深いスキーマは切り捨てられます。1 つのアスペクトがアスペクトあたりのサイズ上限を超えることはないため、ネストが深いスキーマでは末尾のフィールドが失われる可能性があります。
--aspects-only はメタデータの追加と更新はできますが、削除はできません。dbt リソースを削除するには、完全な実行が必要です。
エントリリンクは対象外です。
この統合は、Data Lineage API とグラフの BigQuery リソースの dbt リネージイベントのみをサポートします。外部のサードパーティソースの dbt エントリ（ソース、シード、モデル）は、データリネージにキャプチャされません。
- Data Lineage API で dbt リネージイベントをすべて取り込むには、OpenLineage dbt 統合を使用します。次に、OpenLineage を Knowledge Catalog と統合して、dbt からデータリネージをインポートして可視化します。

次のステップ

コネクタジョブを管理する方法を学習する。

dbt Core からメタデータをインポートする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

IAM のロールと権限

API を有効にする

dbt の前提条件

Cloud Storage のロールについて

dbt 接続を構成する

コンソール

gcloud

必須フラグ

オプション フラグ

REST

取り込みを再実行する

dbt メタデータを検索して表示する

コンソール

gcloud

REST

制限事項

次のステップ

dbt Core からメタデータをインポートする

オプションフラグ