dbt manifest.json の読み解き — プロジェクト構造の静的メタを正しく掴む

manifest.json は、dbt プロジェクトの“静的メタデータ”をすべて束ねた成果物です。モデルやソース、テスト、マクロ、依存関係が一枚にまとまります。生成は target/manifest.json。dbt compile、run、test、docs generate など、プロジェクトを解析する多くのコマンドで更新されます。

本稿では、公式ドキュメントに沿って変化が少ないキーを中心に読み解きます。日々の運用に役立つチェック方法と、Analytics Engineer 試験で狙われやすい観点を整理します。

manifest.json の位置づけと全体像

manifest.json は、dbt がプロジェクトを静的解析した結果です。各ノード（models、seeds、snapshots、analyses、tests など）や sources、macros、exposures の定義と、それらの依存関係が含まれます。実行結果そのものではなく、実行“前提”のメタです。

生成タイミングは安定しており、dbt がパーサを走らせるコマンドで target/manifest.json が更新されます。CI ではこのファイルを成果物として保存し、差分レビューや系譜の健全性チェックに活用できます。

• 場所: target/manifest.json
• 主なトップレベル: nodes, sources, macros, exposures, parent_map, child_map, metadata
• 静的メタ: 実行成否や行数は含まれない（それは run_results.json 側）
• 安定して使えるキー: resource_type, name, original_file_path, fqn, config, description, columns, depends_on

dbt と manifest.json の関係（静的メタ → 実行）

manifest.json（抜粋・トップレベル）のイメージ

{
  "metadata": {
    "dbt_version": "1.x.y",
    "generated_at": "2026-04-18T10:00:00Z",
    "project_id": "..."
  },
  "nodes": { "model.my_pkg.my_model": { "resource_type": "model", "name": "my_model", "config": { "materialized": "view" } } },
  "sources": { "source.my_pkg.my_src.my_tbl": { "source_name": "my_src", "name": "my_tbl" } },
  "macros": { "macro.my_pkg.some_macro": { "path": "macros/some.sql" } },
  "exposures": { },
  "parent_map": { "model.my_pkg.my_model": ["source.my_pkg.my_src.my_tbl"] },
  "child_map": { "source.my_pkg.my_src.my_tbl": ["model.my_pkg.my_model"] }
}

トップレベル構造の要点と使いどころ

試験でも問われやすいのがトップレベルの読み分けです。nodes にはモデル・シード・スナップショット・分析・テストなど“構築対象”の多くが入り、sources はデータソース専用、macros は Jinja マクロ、exposures は BI ダッシュボードなどの外部公開物を表します。parent_map / child_map は依存グラフの逆引き・正引きに便利です。

metadata はバージョンや生成時刻などのコンテキストで、アーティファクト間の整合性確認に用います。

• nodes: resource_type 単位で混在（model/test/seed/snapshot/analysis）
• sources: ソーステーブル（database/schema/name、freshness 設定は別アーティファクトと併用）
• macros: 呼び出し可能なマクロの定義（実行結果は持たない）
• exposures: 上流の dbt ノードと外部可視化の結びつき
• parent_map / child_map: 依存の双方向参照（選択器の裏付け確認に有用）
• metadata: dbt_version、generated_at、project_id など

トップレベルを列挙して存在確認（jq の例）

jq -r 'keys[]' target/manifest.json
# 出力例:
# metadata
# nodes
# sources
# macros
# exposures
# parent_map
# child_map

nodes を深掘り：モデル属性と安定キー

nodes の各要素はユニークキー（例: model.pkg_name.model_name）で引けます。resource_type は model/seed/snapshot/test/analysis など。多くの実務チェックと試験問題は、config、depends_on、relation_name（コンパイル後の物理名）、original_file_path、fqn、columns、tags、description あたりを理解していれば解けます。

config.materialized は最頻出。view/table/incremental/ephemeral 等の区別は、コストや依存解決に直結します。columns 配下の description や tests の紐づきはドキュメント品質の要。

• resource_type: ノード種別（model, seed, snapshot, test 等）
• name / alias / relation_name: 論理名・別名・物理名
• database / schema: 接続先の論理スキーマ情報
• config: materialized, tags, partitioning 等（アダプタ依存は慎重に）
• depends_on.nodes: 直接の依存ノード配列
• original_file_path / package_name / path: 由来トレース

モデルノードの抜粋（重要フィールド）

{
  "nodes": {
    "model.jaffle_shop.orders": {
      "resource_type": "model",
      "name": "orders",
      "package_name": "jaffle_shop",
      "original_file_path": "models/orders.sql",
      "fqn": ["jaffle_shop", "models", "orders"],
      "database": "ANALYTICS",
      "schema": "DBT_DEV",
      "alias": null,
      "relation_name": "ANALYTICS.DBT_DEV.ORDERS",
      "config": { "materialized": "view", "tags": ["core"] },
      "description": "注文ファクトの基礎モデル",
      "columns": {
        "order_id": {"name": "order_id", "description": "主キー"},
        "customer_id": {"name": "customer_id", "description": "外部キー"}
      },
      "depends_on": { "nodes": ["source.jaffle_shop.raw.orders"] },
      "checksum": {"name": "sha256", "checksum": "..."}
    }
  }
}

依存グラフ：depends_on / parent_map / child_map の実践

系譜の基本は depends_on.nodes で上流を把握すること。parent_map と child_map は全体グラフを引き回すのに役立ちます。上流の再帰展開は parent_map を辿り、下流影響の評価は child_map を辿るのが効率的です。

選択子（selection）は公式仕様に準じますが、manifest.json 側で地道に確認すると誤解が減ります。たとえば +model_name 相当の拡張は child_map を再帰に辿ることで再現できます。

• 上流展開: parent_map[target] を再帰に辿る
• 下流展開: child_map[target] を再帰に辿る
• 境界の扱い: source.* は終端（通常はさらに上流なし）
• test ノード: 対象モデルにぶら下がるが、実行順は別管理
• グラフの安定キー: unique_id（例: model.pkg.name）を正準とする

上流と下流を列挙する簡易 jq（unique_id を起点）

# 上流（親）
uid="model.jaffle_shop.orders"
jq --arg uid "$uid" -r '.parent_map[$uid][]?' target/manifest.json

# 下流（子）
jq --arg uid "$uid" -r '.child_map[$uid][]?' target/manifest.json

# 直接依存（ノード内）
jq --arg uid "$uid" -r '.nodes[$uid].depends_on.nodes[]?' target/manifest.json

sources・tests・exposures の読み方

sources は上流データベースのテーブル・ビューを dbt 側で命名・文書化するための定義です。manifest.json では source.<pkg>.<source_name>.<name> という unique_id で現れ、database/schema/name、loader、description 等が確認できます。

tests は多くが nodes に resource_type: test として格納され、対象ノードやカラムへの参照が depends_on に入ります。exposures はダッシュボードの所有者、url、maturity、depends_on などの静的情報を持ち、利害関係者に伝えやすい形で上流依存を示すのに有用です。

• sources: 名付けと文書化、freshness は別アーティファクトと合わせて解釈
• tests: unique_id に test.* が含まれる、対象モデル/カラムを depends_on で特定
• exposures: 上流の dbt ノード列挙とメタ（owner, type, url, maturity）

source と test, exposure の抜粋

{
  "sources": {
    "source.jaffle_shop.raw.orders": {
      "source_name": "raw",
      "name": "orders",
      "database": "RAW",
      "schema": "JAFFLE",
      "loader": "ingestion_tool",
      "description": "生の注文テーブル"
    }
  },
  "nodes": {
    "test.jaffle_shop.not_null_orders_order_id": {
      "resource_type": "test",
      "name": "not_null",
      "depends_on": {"nodes": ["model.jaffle_shop.orders"]}
    }
  },
  "exposures": {
    "exposure.jaffle_shop.orders_dashboard": {
      "type": "dashboard",
      "name": "orders_dashboard",
      "owner": {"name": "BI Team", "email": "[email protected]"},
      "url": "https://bi.example.com/dash/123",
      "maturity": "high",
      "depends_on": ["model.jaffle_shop.orders"]
    }
  }
}

実務チェックリストと試験対策ポイント

実務では、manifest.json を定期的に収集し、materialization の逸脱検知、未文書カラムの棚卸し、未使用モデルの洗出し（下流ゼロ）を自動化すると効果的です。CI では manifest の差分を Pull Request に添付するとレビュー効率が上がります。

試験では、manifest.json が“静的メタ”であり、実行結果は run_results.json 側という区別、nodes/sources/macros/exposures の管轄、depends_on と parent_map/child_map の役割、config.materialized の影響を問う設問が定番です。バージョン差異に敏感なフィールドには依存しすぎず、resource_type、depends_on、config、relation_name のような安定キーを軸に覚えるのが安全です。

• materialized の一括検査: ビュー化のし忘れ/テーブル濫造を防ぐ
• 下流ゼロのモデル: 清掃候補（child_map[id] が空）
• 未記述カラム: columns[].description が空の比率を追う
• 実行結果は run_results.json、ソース健全性の数値は別アーティファクトと突合
• バージョン差は metadata.dbt_version で明示的に管理

全モデルの materialized を棚卸し（jq）

jq -r '
  .nodes
  | to_entries[]
  | select(.value.resource_type=="model")
  | [.key, (.value.config.materialized // "<unset>")]
  | @tsv
' target/manifest.json
# 出力: unique_id と materialized の対応

問題で確認

よくある質問