dbt アーティファクト徹底理解: manifest.json / run_results.json / catalog.json

dbt は実行ごとに JSON アーティファクトを target/ 配下に生成します。なかでも manifest.json、run_results.json、catalog.json は可観測性・ドキュメント・CI 連携の中心です。

本稿は dbt docs(https://docs.getdbt.com/)に沿って、試験で問われやすい観点と現場での運用ノウハウをまとめます。バージョン差異に依存しやすい細目は注意書きを添え、安定的に通用する読み方を優先します。

全体像: いつ・何が・なぜ生成されるか

dbt はコマンドの実行後、target/ に複数の JSON を出力します。実行計画とリネージは manifest.json、実行結果は run_results.json、テーブル/カラムの型や統計は catalog.json が担います。これらは可視化(dbt docs)、品質監視(CI、SLA 検証)、データカタログ連携の基礎データになります。

覚えるコアは次の3点: 1) manifest はグラフ(依存関係とノード定義)、2) run_results は各ノードの実行ステータスと所要時間、3) catalog は生成環境のスキーマ情報。いずれも JSON で、generated_at と metadata を持つのが通例です。

• 出力先は通常 target/(profiles.yml の target 名とは別概念)
• docs generate 実行で catalog.json と manifest.json を再出力
• CI では run_results.json を合格判定やレポートに用いる

アーティファクトの生成と活用フロー(概念図)

最小限の生成チェック(シェル)

dbt run --select my_model
ls -1 target | grep -E 'manifest|run_results|catalog'
# docs 情報を最新化
dbt docs generate

manifest.json: モデルの真実とリネージの源泉

manifest.json はプロジェクトのグラフを表現します。各ノード(model, seed, snapshot, test, exposure, source, macro など)のメタデータ、ファイルパス、materialized、depends_on、および child_map/parent_map が含まれます。試験では「影響範囲の特定」と「選択子の評価」に結び付けて理解しておくと得点源です。

フィールドはバージョンで増減しますが、nodes, sources, child_map/parent_map, generated_at, metadata は安定的に登場します。adapter やパッケージの差異は metadata に含まれることが多く、移植性評価に使えます。

• depends_on.nodes は上流参照、child_map/parent_map はグローバルな依存関係インデックス
• description, config.materialized, database/schema/alias はドキュメント/命名規約と直結
• exposures は BI やダッシュボードの末端までトレース可能にする

依存関係の方向(上流→下流)

manifest.json から影響範囲を列挙(Python)

import json
from collections import deque

with open('target/manifest.json') as f:
    mf = json.load(f)

child_map = mf.get('child_map', {})
start = 'model.my_project.fct_orders'

visited, q = set([start]), deque([start])

while q:
    n = q.popleft()
    for c in child_map.get(n, []):
        if c not in visited:
            visited.add(c)
            q.append(c)

print('\n'.join(sorted(visited)))  # fct_orders の下流に影響するノード一覧

run_results.json: 実行成否とパフォーマンスの単一情報源

run_results.json は直近のコマンド(run/test/build 等)に関する結果を格納します。各 result には status(success, error, skipped など)、execution_time、timing(compile/execute の内訳)、failures(test の失敗件数など)を含みます。CI ではここを機械判定に使い、SLA 監視では遅延やフレークの兆候を検出します。

注意点として、run_results は“直近実行”のスナップショットです。履歴分析をするなら毎回収集・保管(オブジェクトストレージや DWH へ COPY)する運用が必要です。

• invocation_id は実行単位の相関キーとして重要
• model/test ごとの execution_time を集計して回帰遅延を検知
• status=error の result に message や adapter_response が付与されることがある

CI における合否判定の流れ

run_results.json を要約(Python)

import json, sys
from collections import Counter

with open('target/run_results.json') as f:
    rr = json.load(f)

status = Counter(r.get('status', 'unknown') for r in rr.get('results', []))
mean_time = sum(r.get('execution_time', 0.0) for r in rr.get('results', [])) / max(1, len(rr.get('results', [])))

print('status summary:', dict(status))
print('mean execution_time(sec):', round(mean_time, 2))

errors = [r for r in rr.get('results', []) if r.get('status') == 'error']
if errors:
    print('ERROR DETAILS:')
    for e in errors:
        node = e.get('unique_id')
        msg = e.get('message', '')
        print(f'- {node}: {msg[:200]}')
    sys.exit(1)

catalog.json: 型・カラム統計でドキュメントを強化

catalog.json は dbt docs generate により作成され、データベース上の実体(モデル、ソース)のカラムごとの型やコメント、場合により統計情報(例えば行数推定)を含みます。これを manifest と突き合わせると、論理定義と物理実装の差異検知が可能になります。

アダプタにより data_type 名称や統計の粒度は変わります。試験では「catalog は docs generate によって生成される」「列情報と型を提供する」点を確実に押さえてください。

• 列レベルのドキュメント整備や型逸脱検出(例: 期待は INT だが実体は STRING)
• BI ツールやデータカタログへの同期元として利用
• manifest.nodes[unique_id] と catalog.nodes[unique_id] をキーに結合可能

manifest × catalog の突合イメージ

manifest.nodes[model.fct_orders] ----join on unique_id---- catalog.nodes[model.fct_orders]
         | logical config                                 | physical columns/types

catalog と manifest を突合し、型差異を検出(Python)

import json

with open('target/manifest.json') as f: mf = json.load(f)
with open('target/catalog.json') as f: cg = json.load(f)

m_nodes = mf.get('nodes', {})
c_nodes = cg.get('nodes', {})

for uid, m in m_nodes.items():
    if not uid.startswith('model.'):  # モデルに限定
        continue
    c = c_nodes.get(uid)
    if not c:
        continue
    m_cols = (m.get('columns') or {}).keys()
    c_cols = (c.get('columns') or {}).keys()
    missing = set(m_cols) - set(c_cols)
    if missing:
        print(f'[WARN] not in catalog: {uid} -> {sorted(missing)}')

実務パターン: CI/CD・リネージ可視化・監査連携

アーティファクトは“保管して活かす”が基本です。CI で run_results を収集し、S3/GCS へ保存してから DWH にロードすると、ジョブ安定性や回帰遅延のトレンドが取れます。manifest は Pull Request ごとの差分比較で影響範囲レビューを自動化できます。catalog はデータ辞書の更新トリガに利用します。

dbt Cloud/OSS どちらでもパターンは同じですが、保管と参照の運用設計(命名、保持期間、メタデータ付与)が品質を左右します。

• CI: dbt build → run_results を収集 → 失敗時はログ抜粋をコメント
• リネージ差分: 旧 manifest と新 manifest の child_map を比較
• 監査: generated_at, invocation_id, adapter_type を監査テーブルに格納

CI でのアーティファクト保管パイプライン

GitHub Actions 例(YAML 抜粋)

jobs:
  dbt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - run: pip install dbt-core dbt-bigquery
      - run: dbt deps && dbt build --fail-fast
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dbt-target
          path: target/*.json

試験対策: よく出る観点と落とし穴

Analytics Engineer 試験では、アーティファクトの生成タイミングと用途の切り分けが頻出です。特に「catalog は docs generate」「run_results は直近実行のみ」「manifest はリネージの情報源」の3点を即答できるようにしましょう。

また、unique_id の安定性、depends_on と child_map の違い、invocation_id の用途を言語化できると加点につながります。バージョン固有の細目よりも、ファイル間の役割分担を優先して覚えるのが安全です。

• manifest: グラフとノード定義(選択子・影響範囲)
• run_results: 実行結果のスナップショット(CI/SLA)
• catalog: 物理スキーマと統計(ドキュメント/監査)

覚え方ミニマップ

manifest = グラフ
run_results = 成否/時間
catalog = 型/カラム
→ 役割で暗記し、生成タイミングで確証を取る

unique_id から人間可読名へ(Python)

import json
mf = json.load(open('target/manifest.json'))
uid = 'model.my_project.fct_orders'
node = mf['nodes'][uid]
print(node.get('name'), node.get('original_file_path'))

問題で確認

よくある質問