Jinja の基礎: dbt で最低限押さえる文法

dbt は Jinja2 を使って SQL をテンプレート化し、コンパイル時に最終的な SQL を生成します。つまり Jinja は「実行前に展開されるルール」であり、正しく理解すればモデル定義が簡潔かつ再利用可能になります。

本稿では、Analytics Engineer 試験と日常運用の両方で必須となる Jinja の最小限文法と dbt 固有コンテキスト（ref, source, var, env_var, config, マクロ）を、誤りやすいポイントとともに整理します。

Jinja はどこで動くか: dbt の評価タイミング

dbt はモデルを実行する前に Jinja を評価し、最終的な SQL を生成します。依存関係の解決（ref/source）やマクロ展開はこの段階で行われます。Jinja 自体はデータベースで動くのではなく、dbt（ローカルないし実行環境）で処理されます。

評価タイミングは大きく「パース/コンパイル中」と「実行時のマクロ呼び出し」に分かれます。データベース接続が必要な run_query は実行時にのみ安全に呼び出せます。一方で、ref/source/var/env_var/config はモデルやマクロのテンプレート内で一般的に利用されます。

• Jinja はコンパイルフェーズで SQL に展開される（DB 上で解釈されない）
• ref は依存グラフとスキーマ名テーブル名の解決を担う
• run_query はマクロ内など実行時にのみ使用し、パースのみの文脈では避ける

dbt における Jinja の評価と実行の流れ

最小例: ref と Jinja 展開のイメージ

-- models/orders_enriched.sql
select
  o.id,
  o.customer_id,
  c.segment
from {{ ref('stg_orders') }} as o
left join {{ ref('dim_customers') }} as c
  on o.customer_id = c.customer_id;

基本記法: 変数、式、フィルタの最短セット

Jinja の区切りは3種類だけ押さえれば十分です。{{ }} は値（式/変数）の出力、{% %} は制御構文（if, for, set など）、{# #} はコメントです。dbt ではこれらが SQL 内に混在します。

フィルタはパイプ記法で値を加工します。default, lower, upper, join, replace あたりが頻出です。数値・文字列の扱いでは引用符の有無に注意し、特に識別子（カラム名など）を生成するときは安全性と可読性を意識します。

• 値の出力: {{ expression }}
• 制御構文: {% if %}, {% for %}, {% set %}
• コメント: {# コメント #}
• よく使うフィルタ: |default('x'), |lower, |upper, |join(', ')

区切りの役割ミニ図

フィルタと set の例

{% set cols = ['id', 'customer_id', 'order_ts'] %}
select {{ cols | map('lower') | join(', ') }}
from {{ ref('stg_orders') }};

制御構文: if/for と繰り返しで SQL を整える

環境やターゲットに応じて列や条件を切り替えるときに if は有効です。配列やマップを回す for は選択列や CASE 文の量産に向いています。テンプレート化は可読性を落とさない範囲で行い、長いロジックはマクロに切り出します。

ループ内のカンマ区切りや末尾カンマに注意しましょう。join フィルタで安全に区切るか、loop.last を用いて制御します。

• 環境依存のブランチは target.name を参照
• ループの区切りは join で安定化
• 長いロジックはマクロへ切り出し

for で列リストを組み立てるイメージ

for と loop.last の例

{% set dims = ['country', 'city', 'zip'] %}
select
  customer_id,
  {% for d in dims %}
  {{ d }}{% if not loop.last %},{% endif %}
  {% endfor %}
from {{ ref('dim_customers') }};

dbt 固有関数: ref, source, var, env_var, config の使い分け

ref はモデル間依存を張りつつ、適切なスキーマ・識別子を解決します。source は外部テーブル参照のために使い、catalog.yml の宣言と一致させます。var は dbt_project.yml やコマンドラインで渡した変数を取得し、env_var は OS 環境変数を参照します。config はマテリアライゼーションやタグなどモデル設定に使います。

Analytics Engineer 試験では、ref と source の区別、var/env_var の優先度、config の適用範囲（モデル内 vs プロジェクト設定）が頻出です。

• ref は依存解決＋スキーマ/識別子の可搬性を担保
• source は外部テーブル。catalog で宣言必須
• var は dbt 変数、env_var は OS の環境変数
• config はモデル単位の設定（materialized, tags など）

ref と source の関係イメージ

ref, source, var, env_var, config の実例

-- models/fct_orders.sql
{{ config(materialized='table', tags=['finance']) }}

with src as (
  select * from {{ source('raw', 'orders') }}
), stg as (
  select * from {{ ref('stg_orders') }} where order_date >= {{ var('from_date', "'1970-01-01'") }}
)
select * from stg
where {{ 'true' if env_var('ALLOW_ALL', 'false') == 'true' else 'total_amount > 0' }};

マクロの作成・再利用とパッケージ

繰り返し現れる SQL 断片は macros ディレクトリにマクロとして切り出し、呼び出し側で引数を渡します。マクロは Jinja のテンプレートであり、呼び出し時に展開されます。複数プロジェクトで共有するならパッケージ化し、packages.yml から導入します。

run_query はマクロ内で補助的な問い合わせを行いたい場合に限定して使います。モデル本体の SQL 生成を run_query の結果に依存させると、コンパイル・キャッシュ・並列実行で予期せぬ挙動になる可能性があるため、設計としては避けます。

• マクロは macros/ 配下に .sql ファイルで作成
• 呼び出しは {{ my_macro(arg=...) }} 形式
• 共有はパッケージ化し、命名空間で衝突回避

プロジェクト構造の最小例

マクロ定義と呼び出し

-- macros/utils.sql
{% macro coalesce_zero(expr) %}
coalesce({{ expr }}, 0)
{% endmacro %}

-- models/fct_orders.sql（一部）
select {{ coalesce_zero('total_amount') }} as total_amount
from {{ ref('stg_orders') }};

落とし穴と検証: 依存、識別子、安全なテンプレート

ref/source を使わずにハードコードしたスキーマ・テーブル名は、環境差分やリネームで壊れます。必ず ref/source を通し、識別子はアダプタが適切にクオートします。識別子やリテラルの動的生成では、文字列クオートの整合性に注意します。

Jinja のロジックをテストで担保するには、dbt test と unit tests（利用可能な場合）を組み合わせます。テンプレート展開が意図通りかは、dbt compile で生成 SQL を確認するのが最短です。

• スキーマ・テーブル名のハードコード禁止。ref/source で移植性を担保
• 文字列と識別子のクオートを混同しない
• dbt compile で生成 SQL を目視確認

安全な参照と危険な参照

良い: {{ ref('stg_orders') }} -> コンパイル時に解決
悪い: raw_schema.stg_orders -> 環境で破綻

run_query はマクロ内の補助用途に限定

-- macros/get_max_order_date.sql
{% macro get_max_order_date() %}
  {% set res = run_query("select max(order_date) as d from " ~ ref('stg_orders')) %}
  {% if res is not none and res.columns and res.rows %}
    {{ return(res.rows[0][0]) }}
  {% else %}
    {{ return("'1970-01-01'") }}
  {% endif %}
{% endmacro %}

-- 悪手: モデル本体の where に直接 run_query 結果を依存させない

問題で確認

よくある質問