dbt var() とプロジェクト変数: 実行時パラメータ設計ガイド（Analytics Engineer向け）

dbt の var() は、Jinja コンパイル時に参照される実行時パラメータです。モデルやマクロの分岐、しきい値、日付境界などを柔軟に切り替えるのに使います。

本稿では、試験対策（dbt Analytics Engineer）と実務の両面から、変数の優先順位・設計原則・具体実装・検証方法・運用までを整理します。

var() の基本と優先順位

var('name', default) は Jinja コンパイル時に解決される変数参照です。default を指定しない場合、その変数が見つからなければコンパイルエラーになります。default を指定すると未設定時でもビルドが継続し、明示的な初期値で動作します。

変数の設定は主に dbt_project.yml の vars と CLI の --vars で行います。どちらにも同名キーがある場合は CLI が優先されます。パッケージが var() を参照している場合は、ルートプロジェクトの dbt_project.yml でそのパッケージ用の名前空間配下に値を与えると上書きできます。

• 解決タイミング: コンパイル時（SQL 生成前）
• 主な設定場所: dbt_project.yml の vars、CLI の --vars
• 未定義時の挙動: default 指定なし→コンパイルエラー、あり→default 採用
• 優先順位（高→低）: CLI --vars > ルートプロジェクトの dbt_project.yml vars > var() の default
• パッケージ変数: ルートの dbt_project.yml でパッケージ名をキーとする名前空間配下に設定して上書き

設計原則: 実行時パラメータの決め方

変数は“最小限かつ明確”が基本です。実行時パラメータ化するものは、再デプロイなしで頻繁に変えたい閾値やスイッチに限定します。変数が多すぎるとテスト行列が爆発します。

型と命名は将来の保守性に直結します。真偽値・日付・数値・列挙などの型を明示し、default はテスト可能で安全な最小権限の値に設定します。

• 集中管理: 既定値は dbt_project.yml の vars に集約し、変更履歴をレビュー可能にする
• 明示的 default: var() には必ず default を与え、未設定時の挙動を一定化する
• 命名規則: フラグは is_/use_、閾値は *_threshold、日付は *_date といった語彙で統一
• 型の一貫性: 真偽値は true/false（文字列でなく）、日付は 'YYYY-MM-DD' などに正規化
• テスト戦略: 重要変数は CI で主要な組合せ（例: use_new_logic true/false）を最低 1 本ずつ検証
• 責務分離: 機密値は var ではなく env_var で参照（資格情報は profiles.yml へ）

実装例: dbt_project.yml と Jinja による利用

以下は、既定値を dbt_project.yml に定義し、モデル内で var() を使って条件分岐・日付境界を切り替える最小例です。CI では CLI --vars で一時的に上書きします。

日付リテラルを SQL に埋め込む際は、方言に合わせてクォート・キャストを適切に行います（Snowflake なら TO_DATE、Databricks なら DATE() など）。

• dbt_project.yml に既定値を配置
• モデルで var() を参照し default も指定
• CI/CD で --vars により上書き

dbt_project.yml・モデル・CLI の連携例

# dbt_project.yml（抜粋）\nname: my_project\nversion: 1.0.0\nconfig-version: 2\n\nvars:\n  start_date: '2021-01-01'\n  use_new_logic: false\n\nmodels:\n  my_project: {+materialized: table}\n\n---\n-- models/fct_orders.sql（抜粋）\n{{ config(materialized='table') }}\n\nwith src as (\n  select * from {{ ref('stg_orders') }}\n  {% if var('use_new_logic', false) %}\n    where updated_at >= '{{ var('start_date', '1900-01-01') }}'\n  {% endif %}\n)\n\nselect * from src\n\n---\n# 一時的に上書き（CI など）\n# Linux/macOS の例（シェルでクォートに注意）\ndbt build --vars "{use_new_logic: true, start_date: '2024-01-01'}"

パッケージ変数と名前空間の上書き

外部パッケージ（例: dbt-utils 等）が var() を参照している場合、ルートプロジェクトの dbt_project.yml にパッケージ名の名前空間を作り、配下にキーを定義することで動作を上書きできます。

この仕組みはパッケージの既定動作を安全に変更する標準的手段です。上書きの有無を README に記録し、バージョンアップ時に差分をレビューできるようにします。

• 名前空間のキーは packages.yml のパッケージ名と一致させる
• プロジェクトの vars と値が競合する場合は、参照側（パッケージ内 var() 呼び出し）が見る名前空間にだけ影響する
• 不要な上書きは削除し、diff で追えるよう最小限に保つ

パッケージ変数の上書き例（dbt_project.yml）

vars:\n  some_package:\n    enable_feature: true\n    threshold: 10

検証・ガードと型の注意点

重要な変数は、コンパイル時に許容値チェックを行うと安全です。想定外の値が混入した際に早期失敗し、誤った SQL の実行を防げます。dbt では exceptions.raise_compiler_error を用いて明示的に失敗させられます。

Jinja の真偽判定は Python に準じるため、"false" のような非空文字列は真と評価されます。真偽値は必ず boolean 型で与え、CLI でも true/false を YAML として解釈されるよう適切にクォートしてください。

• 列挙型の検証: 許容値セットに含まれるかチェック
• 真偽値は boolean で渡す（文字列は不可）
• 数値の比較では文字列キャストに注意（必要に応じて |int, |float で明示変換）
• デバッグ: {{ log('var x=' ~ var('x', 'n/a'), info=True) }} でビルドログへ出力

コンパイル時ガードのマクロ例

{% macro require_valid_choice(var_name, allowed) %}\n  {% set value = var(var_name, none) %}\n  {% if value is none or value not in allowed %}\n    {{ exceptions.raise_compiler_error(var_name ~ ' must be one of ' ~ (allowed | join(', ')) ~ ', but was: ' ~ (value|string)) }}\n  {% endif %}\n{% endmacro %}\n\n-- 利用例（モデル先頭など）\n{{ require_valid_choice('region', ['us', 'eu', 'ap']) }}

運用: 環境別の上書きと CI/CD

環境（dev/stg/prod）ごとの動作差分は、基本は接続プロファイルや target で吸収し、ビジネスロジック上の可変部分のみ var で切り替えます。CI では --vars で主要な組合せを検証します。

下図は var の解決フローのイメージです。CLI があればそれが最優先、なければ dbt_project.yml、最後に default が使われ、コンパイル結果の SQL に反映されます。

• CI: 主要フラグの true/false で最低 1 本ずつ dbt build を実行
• 運用: 定常値は dbt_project.yml、デプロイ時の一時変更は --vars
• 監査: 変数の変更は PR でレビューし、CHANGELOG に影響範囲を記録

var の解決フロー（優先順位と反映経路）

GitHub Actions での例（主要フラグを 2 通り検証）

jobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v5\n        with: { python-version: '3.11' }\n      - run: pip install dbt-core dbt-snowflake\n      - name: Build (use_new_logic=false)\n        run: dbt build --vars "{use_new_logic: false, start_date: '2021-01-01'}"\n      - name: Build (use_new_logic=true)\n        run: dbt build --vars "{use_new_logic: true, start_date: '2024-01-01'}"

問題で確認

よくある質問