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

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

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

Knowledge Catalog（旧称 Dataplex Universal Catalog）を使用すると、Google Cloud CLI と dbt アーティファクトファイルを使用して、dbt Core、dbt Cloud、MetricFlow から運用メタデータ、セマンティックメタデータ、リネージメタデータをインポートできます。変換メタデータを dbt エコシステムにサイロ化するのではなく、一元化することで、データエンジニア、アナリティクスエンジニア、データスチュワードがエンタープライズデータを検出して管理できるようにします。

インポートされたメタデータとユースケース

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

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 と Knowledge Catalog の統合がサポートされています。CLI をインストールまたは更新するには、Google Cloud 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 からメタデータをインポートする前に、次のタスクを完了します。

必要なロールと権限を付与します。
Dataplex 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）: 入力アーティファクトバケットに対する Storage オブジェクト閲覧者（roles/storage.objectViewer）または Storage オブジェクト管理者（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）に対するストレージオブジェクト閲覧者（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 を有効にする

Dataplex 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 コマンドは、ジョブの準備中にこれらの入力ファイルを読み取ります。gcloud コマンドを実行する呼び出し元には、Cloud Storage を使用する場合、読み取りアクセス権（roles/storage.objectViewer または roles/storage.objectAdmin）が必要です。Knowledge Catalog サービスエージェントは、入力アーティファクトバケットにアクセスする必要はありません。
出力（Knowledge Catalog インポートステージングバケット）: gcloud コマンドが変換されたメタデータインポートファイル（dbt_metadata.jsonl）をアップロードし、取り込み中に Knowledge Catalog インポートジョブが読み取る Cloud Storage バケット URI 接頭辞（gs://my-staging-bucket/dbt-imports/ など）。この 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 Administrative 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 リリーストラックの場合: [Generate docs on run] オプションを選択する代わりに、dbt docs generate --no-compile をジョブコマンドとして追加します。[Generate docs on run] チェックボックスをオンにすると、--no-compile なしで dbt docs generate が実行されます。これにより、dbt の前提条件で説明されているように、dbt build のテスト結果が上書きされます。コマンドステップが失敗すると、ジョブも失敗します。一方、チェックボックスステップではジョブは失敗しません。

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

詳細については、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 Administrative API を使用してアーティファクトをダウンロードする

dbt Administrative 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 が必要です。dbt Google Cloud コンソールの実行 URL から実行 ID をコピーするか、ターミナルまたはワークフロースクリプトから 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 コンソールで、[Account settings] > [Webhooks] に移動し、[Create webhook]（または [Create new webhook]）をクリックします。Webhook サブスクリプションを構成します。
- イベント: [実行完了]（job.run.completed）を選択します。これは、実行が完了し、アーティファクトがダウンロード可能になった後にのみトリガーされます。
- ジョブ: モニタリングする dbt Cloud デプロイジョブを選択します。
- エンドポイント: 実行するサービス（Cloud Run サービスや Cloud Run 関数など）の HTTPS URL を入力します。
dbt Cloud に表示される Webhook シークレットトークンを保存します。サービスは、このシークレットを使用して Authorization ヘッダーを検証します。このヘッダーには、リクエスト本文の HMAC-SHA256 署名が含まれています。
サービスで、JSON ペイロードから data.runId を読み取り、前述のように Administrative API を使用して実行のアーティファクトをダウンロードし、gcloud 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 メタデータインポートジョブをトリガーします。このジョブは、Knowledge Catalog サービスエージェントに、--storage-uri からステージングされたメタデータを読み取り、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 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: 1 つのリソースが別のリソースに依存している、別のリソースを記述している、または別のリソースを使用している。これには、ノード間の 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 をビルドしてアップロードし、メタデータジョブを検証しますが、実際には取り込みません。
ステータスが [作成済み] になっていることを確認します。

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 Administrative API を使用してアーティファクトをダウンロードする

実行 ID を取得する

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

dbt 接続を構成する

コンソール

gcloud

必須フラグ

オプション フラグ

REST

取り込みを再実行する

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

コンソール

gcloud

REST

次のステップ

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

オプションフラグ