dbt の graph context を使いこなす：Jinja で DAG 情報を安全に参照する

dbt では Jinja コンテキストに graph という読み取り専用オブジェクトがあり、プロジェクト内のノード（models、sources、seeds、snapshots、tests など）や依存関係を参照できます。これにより、タグに基づく一括設定や、DAG の検査・可視化系のマクロを実装できます。

一方で、graph は依存関係を新たに作るものではありません。DAG のエッジを作るのは ref と source です。Analytics Engineer 試験でも頻出の論点なので、正しい使い分けと安全な実装パターンを押さえましょう。

graph context の基本と位置づけ

graph は dbt のパース後に得られるプロジェクト全体の DAG 表現です。Jinja から読み取り専用で参照でき、各ノードの種類（resource_type）、名前、タグ、設定値、依存先（depends_on）などにアクセスできます。モデルの SQL、マクロ、スナップショット、テストなど一般的な Jinja コンテキストで利用可能です。

重要なのは、graph は依存関係を作成しない点です。DAG のエッジを作るのは ref、source（および test の内部など）であり、graph はあくまで“見る専用”。この前提を外さなければ、プロジェクト全体の健全性チェックやメタデータ駆動のガードレール実装に強力です。

• 読み取り専用：graph を変更しても DAG は変わらない
• 依存関係の作成は ref と source が担う
• 実行時データベース状態ではなく、dbt が解釈したプロジェクトの静的情報
• 大規模プロジェクトではフィルタリングして対象を絞るのが実務的

DAG と graph 参照の関係（概念図）

例: graph を使って下流モデルを列挙するマクロ（run-operation 用）

{% macro show_children(model_name) %}
  {# 対象モデルのノードを取得 #}
  {% set target = (graph.nodes.values()
      | selectattr('resource_type', 'equalto', 'model')
      | selectattr('name', 'equalto', model_name)
      | list | first) %}
  {% if not target %}
    {{ exceptions.raise_compiler_error('Model not found: ' ~ model_name) }}
  {% endif %}

  {% set children = [] %}
  {% for n in graph.nodes.values() if n.resource_type == 'model' %}
    {% if target.unique_id in n.depends_on.nodes %}
      {% do children.append(n.name) %}
    {% endif %}
  {% endfor %}

  {{ log('children(' ~ model_name ~ '): ' ~ (children | join(', ')), info=True) }}
{% endmacro %}

{# 使い方:
   dbt run-operation show_children --args '{"model_name": "stg_orders"}'
#}

ノード情報の読み方：よく使う属性とフィルタ

graph.nodes は辞書（unique_id → ノード）で、values() からノードの配列的アクセスができます。実務では resource_type でまず絞り込み（model、source、seed、snapshot、test など）、さらに name、package_name、tags、config（materialized、schema、post-hook 等）で必要な対象に限定します。

依存関係は node.depends_on.nodes に unique_id の配列として格納されます。上流（parents）は自ノードの depends_on、下流（children）は全ノードを走査して自分の unique_id を depends_on.nodes に含むノードを拾う、という要領です。

• resource_type で基本の絞り込み
• name / package_name / fqn / original_file_path で位置や由来を特定
• tags と config で運用ポリシーの検査（例：タグ mart には必ず not_null テスト）
• depends_on.nodes による親子関係の把握（unique_id ベース）

Jinja と組み合わせる実用パターン

Jinja の selectattr、map、rejectattr、unique、list などのフィルタと組み合わせると、宣言的にノード集合を扱えます。例えばタグでの制御、特定フォルダ配下モデルの集計、マテリアライゼーション別の統計などが簡潔に書けます。

大規模プロジェクトでは、まず対象集合を最小化してから集計・検査を行うのがコツです。無条件に graph.nodes.values() を全走査するマクロは、パース時間を押し上げる原因になり得ます。

• タグで絞る: graph.nodes.values() | selectattr('tags', 'contains', 'pii')
• 特定の素材タイプ: selectattr('resource_type','equalto','seed')
• マテリアライゼーション別集計: node.config.materialized を map して count
• 子孫探索: 再帰は避け、段階的に +selection を使う方が実務的（コマンド側と併用）

実務ユースケース：ガードレールと可観測性

graph を用いたルールチェックは現場で効きます。例として、mart タグのモデルに必須テストが無い場合にビルドを失敗させる、staging 層から mart 層へ直結していないかを検査する、などが挙げられます。

また、運用ダッシュボード向けに、モデル数・テスト数・タグ別の分布などを run-operation で吐き出し、CI のアーティファクトとして保存するパターンも安定的に運用できます。

• タグ準拠チェック: mart は not_null/unique を必須に
• 階層逸脱検知: raw→staging→intermediate→mart の層構造の維持
• ビルド対象の説明可能性向上: DAG の親子リストを成果物に同梱
• CI での軽量可観測性: run-operation で JSON サマリを出力

制約と落とし穴：公式挙動に沿った使い方

graph は dbt が解釈したプロジェクトの静的情報であり、データベースの実体や行数などの実行時情報は含みません。スキーマ内の実在オブジェクト照会は adapter 経由の情報取得（get_relation 等）を使い、graph と混同しないようにします。

依存関係は ref・source でのみ作成されます。graph を見て判断しても DAG は変わらないため、実行順序や並列性に影響を与えたい場合は ref/source の利用、もしくは selection 記法（+、@、state:modified 等）で制御します。

• graph は読み取り専用。変更やエッジ追加は不可
• 実行制御は ref/source と selection で行い、graph は検査用途に限定
• adapter 呼び出しは execute ガードを忘れない（graph 参照自体は安全）
• パフォーマンス配慮：必要最小限の絞り込みで走査回数を削減

試験対策：Analytics Engineer で問われやすいポイント

試験では、依存関係を作る手段とそうでない手段の区別、graph の位置づけ、Jinja コンテキストの代表的な変数（this、target、var、env_var など）の使い分けがよく問われます。graph は DAG の introspection 用であり、実行順序を左右しない、という一言で説明できるようにしておきましょう。

加えて、depends_on による親子関係の把握や、resource_type/tag を用いた集合操作の基礎を押さえておくと、シナリオ問題にも対応しやすくなります。

• DAG のエッジを作るのは ref と source
• graph は参照専用。秩序付けやマテリアライズには影響しない
• this は現在ノード、target は接続情報、var/env_var は設定値の取り込み
• 集合操作は selectattr/map/unique を使って簡潔に書く

問題で確認

よくある質問