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 のロールと権限

ナレッジカタログコネクタジョブを作成して管理するには、ナレッジカタログと 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.）に付与する必要があります。

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

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 ファイルが保存され、アクセス可能になったら、gcloud alpha dataplex dbt metadata-jobs create コマンドを使用して次の操作を行うことができます。

入力アーティファクトを読み取る: 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 メタデータインポートジョブをトリガーします。

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）が、ナレッジカタログサービスエージェントには読み取りアクセス権（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] になっていることを確認します。
ジョブを作成すると、Knowledge Catalog は構成に従って初回実行をスケジュール設定します。また、手動で開始することもできます。

取り込みを再実行する

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

エントリのセットが変更された場合は、完全な取り込みを実行します（--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 メタデータをフィルタします。
検索フィールドを使用して検索クエリを実行できます。キーワード検索または自然言語検索を実行できます。たとえば、キーワード検索ですべての dbt アセットを表示するには、「system=DBT」と入力します。

リソースの検索の詳細については、Knowledge Catalog でリソースを検索するをご覧ください。検索フィールドで使用できる式の詳細については、Knowledge Catalog の検索構文をご覧ください。
LookupContext API を使用して、特定の dbt リソースの LLM コンテキストを取得することもできます。

制限事項

最近の 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 からデータリネージをインポートして可視化します。

次のステップ

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