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

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

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

データエンジニア、分析エンジニア、データスチュワードにとって、メタデータの一元化はエンタープライズデータ検出とガバナンスに不可欠です。チームがデータ変換に dbt を使用すると、運用、セマンティック、リネージの貴重なメタデータが生成されますが、多くの場合、dbt エコシステム内にサイロ化されたままになります。

この情報を一元化されたカタログに統合するには、dbt Core、dbt Cloud、MetricFlow から Knowledge Catalog（以前の Dataplex Universal Catalog）にメタデータをインポートします。

dbt Core は、Oracle や PostgreSQL などのストレージシステムではなく変換エンジンとして動作するため、メタデータをインポートするとさまざまなユースケースが可能になります。Oracle または PostgreSQL のメタデータをインポートして「どのような生データがあるか？」という質問に答え、dbt Core のメタデータをインポートして「データはどのように変換され、信頼性はどの程度か、ビジネスにとってどのような意味があるか？」という質問に答えます。

このドキュメントでは、Google Cloud CLI コマンドと dbt アーティファクトファイルを使用してメタデータをインポートする方法について説明します。

dbt 統合を実行すると、次のメタデータがキャプチャされます。

テクニカルメタデータ: 主要なリソース（ソース、シード、モデル）とその技術的なプロパティ（列名、データ型、行数）を調べて、エンタープライズデータを検出します。
ビジネスメタデータとセマンティックメタデータ: dbt MetricFlow を活用したビジネス定義とロジック（セマンティックモデル、指標、保存されたクエリなど）を探索して、BI ツールと AI エージェントのコンテキストを提供します。
運用メタデータとデータ品質メタデータ: タイミング、成功または失敗のステータス、データの更新速度、テスト結果などの実行メタデータを調べて、パイプラインの健全性をモニタリングし、データの問題をトラブルシューティングします。
リネージと関係メタデータ: 変換グラフ（DAG）と dbt リソース間の依存関係、物理変換ブロック、結合キーと動的結合、親子関係を追跡してリンクする物理リネージを探索することで、ダウンストリームの影響分析と根本原因の追跡を可能にします。
使用状況のメタデータ: dbt の外部でデータがどのように使用されるかをマッピングするエクスポージャーでキャプチャされたメタデータを調べて、ダウンストリームアプリケーションが変換されたデータをどのように使用するかに関する問題をトラブルシューティングします。

制限事項

dbt Core v1（バージョン 1.11 と 1.12 で検証済み）、dbt Core v2、dbt Fusion をサポートしています。
gcloud CLI バージョン 586.0.0 以降では、dbt と BigQuery の統合がサポートされています。CLI をインストールまたは更新するには、Google Cloud CLI CLI をインストールするをご覧ください。
dbt Cloud に直接接続することはありません。dbt Cloud ジョブからメタデータをインポートするには、まずジョブのアーティファクトを取得します。dbt Cloud の実行からメタデータをインポートするをご覧ください。
非常に大きなスキーマや深くネストされたスキーマは切り捨てられます。1 つのアスペクトがアスペクトあたりのサイズ上限を超えることはないため、深くネストされたスキーマでは末尾のフィールドが失われる可能性があります。
--aspects-only はメタデータの追加と更新はできますが、削除はできません。dbt リソースを削除するには、完全な実行が必要です。
この統合は、Data Lineage API とグラフの BigQuery リソースの dbt リネージイベントのみをサポートします。外部のサードパーティソースの dbt エントリ（ソース、シード、モデル）は、データリネージにキャプチャされません。
- Data Lineage API で dbt リネージイベントをすべて取り込むには、OpenLineage dbt 統合を使用します。次に、OpenLineage を Knowledge Catalog と統合して、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 エントリグループオーナー（roles/dataplex.entryGroupOwner）を付与します。また、dbt モデルが書き込む BigQuery テーブルを保持する各プロジェクトに Dataplex エントリオーナー（roles/dataplex.entryOwner）を付与します。カスタムロールの場合、エントリリンクの権限は dataplex.entryGroups.useReferenceEntryLink、dataplex.entryGroups.useSchemaJoinEntryLink、dataplex.entryLinks.reference です。
または、プロジェクトに対する 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）。

プロジェクトで IAM アクセスを管理するのに必要な権限がある場合は、次の gcloud コマンドを実行して、これらのロールを自分のユーザーアカウントに付与できます。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

自動化された CI/CD パイプラインなどでサービスアカウントを使用してインポートを実行する場合は、次の gcloud コマンドを実行して、これらのロールをサービスアカウントに付与できます。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

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

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
USER_EMAIL: ユーザーアカウントのメールアドレス。
SERVICE_ACCOUNT_EMAIL: サービスアカウントのメールアドレス。
STAGING_BUCKET: 出力ステージング Cloud Storage バケットの名前（--storage-uri）。
PROJECT_NUMBER: Google Cloud プロジェクトの番号。

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

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 がインストールされているローカルターミナル、Cloud Shell、または自動化された CI/CD 環境で、dbt プロジェクトのルートディレクトリに移動し、単一のプロファイルとターゲットに対して次の dbt コマンドを順番に実行して、dbt メタデータアーティファクト JSON ファイルの完全なセットを生成します。

dbt Core 2.x と dbt Fusion の場合:
1. dbt source freshness
2. dbt build
3. dbt parse --write-catalog
  
  警告: dbt Core 2.x または dbt Fusion で dbt docs generate を使用しないでください。catalog.json は書き込まれず、テスト結果なしで run_results.json が上書きされます。dbt build --write-catalog はカタログも書き込まないため、別の dbt parse --write-catalog ステップを使用します。
dbt Core 1.x の場合（dbt parse がカタログを書き込まない場合）:
1. dbt source freshness
2. dbt build
3. 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 Cloud の実行からメタデータをインポートする

Knowledge Catalog は dbt Cloud に直接接続しません。dbt Cloud ジョブは dbt Core と同じアーティファクトファイルを生成するため、これらのアーティファクトファイルをローカルディレクトリまたは入力 Cloud Storage バケットに取得し、gcloud コマンドを実行することで、dbt Cloud からメタデータをインポートできます。

アーティファクトを取得する前に、完全なアーティファクトセットを生成するように dbt Cloud ジョブを構成します。アーティファクトファイルは、次のいずれかの方法で dbt Cloud ジョブ実行から取得できます。

dbt Cloud コンソールからアーティファクトをダウンロードする: 1 回限りのインポートまたは初期テストのために、dbt Cloud ユーザーインターフェースのジョブ実行の詳細ページからアーティファクトファイルを手動でダウンロードします。
dbt プラットフォーム CLI を使用してアーティファクトをダウンロードする: ローカルターミナルから dbt Cloud で dbt コマンドを実行し、開発中に生成されたアーティファクトをローカルプロジェクトディレクトリに自動的に保存します。
dbt 管理 API を使用してアーティファクトをダウンロードする: HTTP 経由で完了した実行からアーティファクトをプログラムで取得し、自動化されたスケジュール設定済みのパイプラインで使用します。

dbt Cloud ジョブを設定する

dbt Google Cloud コンソールで、メタデータアーティファクトの完全なセットを生成するようにジョブ設定を構成します。

[実行設定] セクションで、[ソースの更新を実行] を選択します。dbt Cloud は、ジョブコマンドの前に dbt source freshness を実行して sources.json を生成します。
[コマンド] セクションで、dbt build を追加します。
リリーストラックに基づいて catalog.json を生成するコマンドを追加します。
- dbt Core 2.x と dbt Fusion リリーストラックの場合: dbt parse --write-catalog をジョブコマンドとして追加します。
- dbt Core 1.x リリーストラックの場合: [実行時にドキュメントを生成する] オプションを選択する代わりに、dbt docs generate --no-compile をジョブコマンドとして追加します。[Generate docs on run] チェックボックスをオンにすると、--no-compile なしで dbt docs generate が実行され、dbt の前提条件で説明されているように、dbt build のテスト結果が上書きされます。コマンドステップが失敗するとジョブも失敗しますが、チェックボックスステップではジョブは失敗しません。

テストが失敗するなどして dbt build が失敗した場合、dbt Cloud はそれ以降のコマンドをスキップし、実行に catalog.json が含まれません。常に 1 つ生成するには、dbt build の前にカタログコマンドを追加します。カタログには、ビルド前のテーブルの説明が記載されます。

詳細については、dbt ドキュメントのジョブコマンドとリリーストラックをご覧ください。

dbt Google Cloud コンソールからアーティファクトをダウンロードする

dbtGoogle Cloud コンソールで完了した実行からアーティファクトを手動でダウンロードするには:

dbt Google Cloud コンソールで、完了したジョブ実行を開きます。
[アーティファクト] タブに移動して、生成されたアーティファクトファイルを表示します。
manifest.json、catalog.json、run_results.json、sources.json をローカルディレクトリにダウンロードします。
ローカルターミナルまたは Cloud Shell で、dbt 接続を構成するで説明されている gcloud インポートコマンドを実行し、--artifacts-path をダウンロードしたファイルを含むディレクトリに設定します。

詳細については、dbt ドキュメントの実行の可視性をご覧ください。

dbt プラットフォーム CLI を使用してアーティファクトをダウンロードする

dbt プラットフォーム CLI（以前の dbt Cloud CLI）は、ローカルターミナルから dbt Cloud プラットフォームで dbt コマンドを実行し、生成されたアーティファクトをローカル dbt プロジェクトの target/ ディレクトリに自動的にダウンロードします。

ローカルターミナルで、dbt プロジェクトのルートディレクトリに移動し、dbt の前提条件に記載されている 3 つのコマンドを実行します。
dbt 接続を構成するで説明されている gcloud インポートコマンドを実行し、--artifacts-path をプロジェクトルートまたは target/ ディレクトリに設定します。

CLI は、個人のデータウェアハウスの認証情報を使用して開発環境内で実行されるため、生成されたメタデータには、スケジュールされたジョブによって構築された本番環境テーブルではなく、開発スキーマが反映されます。テストまたは開発ワークフローには CLI を使用し、本番環境のインポートのスケジュール設定にはデプロイジョブを使用します。

詳細については、dbt ドキュメントの dbt プラットフォーム CLI をインストールするをご覧ください。

dbt 管理 API を使用してアーティファクトをダウンロードする

dbt 管理 API を使用すると、完了したジョブ実行からアーティファクトをプログラムで取得できます。List Run Artifacts エンドポイントは、実行によって生成されたファイルパスを返します。Retrieve Run Artifact エンドポイントは、次の URL から特定のアーティファクトファイルをダウンロードします。

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

ACCESS_URL は、dbt Cloud アカウントをホストするリージョンによって異なります。dbt Cloud サービストークンを使用してリクエストを認証します。詳細については、dbt ドキュメントの次のページをご覧ください。

ローカルターミナル、Cloud Shell、または自動化されたワークフロー環境から、manifest.json、catalog.json、run_results.json、sources.json をローカルディレクトリまたは Cloud Storage バケットにダウンロードし、そのパスに対して dbt 接続を構成するで説明されている gcloud コマンドを実行します。

デフォルトでは、step クエリパラメータを指定しない限り、アーティファクトエンドポイントは実行の最終ステップのアーティファクトを返します。dbt Cloud ジョブを設定するで説明されているようにジョブを構成する場合、最終ステップは dbt parse --write-catalog または dbt docs generate --no-compile です。このステップでは、catalog.json のみが書き込まれ、他の 3 つのアーティファクトはデフォルトのステップでそのまま残されます。

実行 ID を取得する

特定の実行のアーティファクトをダウンロードするには、その実行 ID が必要です。実行 ID は、dbt Google Cloud コンソールの実行 URL からコピーできます。また、ターミナルまたはワークフロースクリプトから API をクエリして、ジョブの最新の成功した実行を取得することもできます。

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

クエリパラメータでは、status=10 は Success ステータスの完了した実行をフィルタします。このエンドポイントをスケジュールに従ってポーリングして、最新の成功した実行を特定し、そのアーティファクトをダウンロードして、gcloud インポートコマンドを実行できます。

Webhook を使用してインポートをトリガーする

API をポーリングする代わりに、ジョブの実行が完了するたびに自動メタデータインポートをトリガーするように dbt Cloud Webhook を構成できます。Webhook は、指定した HTTP エンドポイントにペイロードを送信します。

dbt Google Cloud コンソールで、[アカウント設定] > [Webhook] に移動し、[Webhook を作成]（または [新しい Webhook を作成]）をクリックします。Webhook サブスクリプションを構成します。
- イベント: [実行完了]（job.run.completed）を選択します。これは、実行が完了し、アーティファクトをダウンロードできるようになってからのみトリガーされます。
- ジョブ: モニタリングする dbt Cloud デプロイジョブを選択します。
- エンドポイント: 実行するサービス（Cloud Run サービスや Cloud Run functions など）の HTTPS URL を入力します。
dbt Cloud に表示される Webhook シークレットトークンを保存します。サービスはこのシークレットを使用して、リクエスト本文の HMAC-SHA256 署名を含む Authorization ヘッダーを検証します。
サービスで、JSON ペイロードから data.runId を読み取り、前述のように Administrative API を使用して実行のアーティファクトをダウンロードし、gcloud alpha dataplex dbt metadata-jobs create コマンドを実行します。

Webhook ハンドラを実装する際は、次の点を考慮してください。

dbt Cloud は、レスポンスを最大 10 秒間待機します。メタデータのインポートには数分かかるため、最初に HTTP レスポンスを返し、バックグラウンドでインポートを実行します（Cloud Run ジョブとして、または --async フラグを使用してなど）。
job.run.completed は失敗した実行でもトリガーされるため、テストが失敗した実行もインポートされます。job.run.errored に登録しないでください。実行のアーティファクトが使用可能になる前にトリガーされる可能性があります。

Webhook ペイロードと署名検証の詳細については、dbt ドキュメントのジョブの Webhook をご覧ください。

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 アーティファクトがなかったアスペクトは、前の実行で指定された値を保持します。これは、定期的な繰り返し取り込みに使用します。取り込みを再実行するをご覧ください。
- --include-entry-links: dbt 関係のエントリリンクを出力します。これはデフォルトで有効です。無効にするには、--no-include-entry-links を使用します。このコマンドは、次のエントリリンクタイプを出力します。
  - reference: あるリソースが別のリソースに依存している、別のリソースを記述している、別のリソースを使用している。これには、ノード間の dbt 依存関係、テストとそのテスト対象のリソース、セマンティックモデルまたは指標とその構築元となるリソース、ノードとその呼び出し元のプロジェクトマクロ、ノードとそのマテリアライズ先の BigQuery テーブルが含まれます。
  - schema-join: dbt relationships テストで宣言された結合可能な列。
- --skip-bigquery-link: reference リンク（dbt ノード → 物理 BigQuery テーブル）をスキップします。デフォルトでは、BigQuery データセットがインポート場所（--location）にあるマテリアライズされた各 dbt ノード（モデル、シード、スナップショット）に対して reference リンクが発行されます。dbt ソースは、BigQuery テーブルへの reference リンクを受け取りません。エントリリンクは同じリージョン内の @bigquery エントリのみを参照できるため、別のリージョンにあるデータセットは自動的にスキップされます。各データセットのリージョンを特定するために、コマンドは BigQuery API を呼び出します。そのため、呼び出し元にはこれらのデータセットに対する bigquery.datasets.get 権限が必要です。この権限がないと、コマンドは他のリージョンのデータセットをスキップできず、それらへのリンクを解決できません。BigQuery テーブルが Knowledge Catalog にカタログ登録されていない場合は、--skip-bigquery-link を使用します。
- --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 リソースが追加、名前変更、削除された。
エントリの表示名、説明、ラベルが変更された場合。
エントリ階層が変更されます。
dbt の依存関係が変更された場合（ref()、source()、テスト、マクロ呼び出しが追加または削除された場合など）。--aspects-only の実行では、エントリリンクは作成または更新されません。
--include-entry-links または --skip-bigquery-link を変更します。

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

定期的な更新には --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 または相対リソース名。

dbt エントリのエントリリンクを一覧表示するには、projects.locations:lookupEntryLinks メソッドを呼び出します。たとえば、dbt モデルがマテリアライズする BigQuery テーブルを取得するには:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

ENTRY_NAME は、dbt エントリの完全なリソース名です。結果はページ分けされ、1 ページあたり最大 10 個のリンクが表示されます。

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

次のステップ

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

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

制限事項

始める前に

IAM のロールと権限

API を有効にする

dbt の前提条件

Cloud Storage のロールについて

dbt Cloud の実行からメタデータをインポートする

dbt Cloud ジョブを設定する

dbt Google Cloud コンソールからアーティファクトをダウンロードする

dbt プラットフォーム CLI を使用してアーティファクトをダウンロードする

dbt 管理 API を使用してアーティファクトをダウンロードする

実行 ID を取得する

Webhook を使用してインポートをトリガーする

dbt 接続を構成する

コンソール

gcloud

必須フラグ

オプション フラグ

REST

取り込みを再実行する

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

コンソール

gcloud

REST

次のステップ

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

オプションフラグ