dbt の Jinja2: その概要と存在理由

dbt米国 神社2、Python テンプレート エンジン、プログラム可能性を追加します。 SQLに。二重中括弧の間に収まるものすべて {{ }} は神社の表現であり、その間にあるものはすべて {% %} it is 制御ステートメント (if、for、set)。

ウェアハウスで各モデルを実行する前に、dbt コンパイル 純粋な SQL の Jinja テンプレート。 フォルダー内にコンパイルされた SQL が表示されます。 target/compiled/ それぞれの後に dbt run.

変数: var() および env_var()

dbt は、SQL コード内の変数にアクセスするための 2 つの関数を提供します。

var(): プロジェクト変数

-- In dbt_project.yml puoi definire variabili globali:
# dbt_project.yml
vars:
  start_date: '2024-01-01'
  lookback_days: 30
  payment_methods: ['credit_card', 'paypal', 'bank_transfer']

-- Usale nei modelli con var():
SELECT *
FROM {{ ref('stg_orders') }}
WHERE created_at >= '{{ var("start_date") }}'::date

-- Puoi sovrascrivere una variabile da CLI:
-- dbt run --vars '{"start_date": "2025-01-01", "lookback_days": 7}'

env_var(): 環境変数

-- Accedi alle variabili d'ambiente del sistema
SELECT *
FROM {{ source('raw', 'events') }}
WHERE environment = '{{ env_var("DBT_ENVIRONMENT", "development") }}'
-- Il secondo parametro è il valore di default (opzionale)

-- Nei profiles.yml per le credenziali (prattica consigliata):
# profiles.yml
my_profile:
  outputs:
    prod:
      type: snowflake
      account: "{{ env_var('SNOWFLAKE_ACCOUNT') }}"
      password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"

テンプレートの if/else 条件

Jinja 条件ステートメントを使用すると、異なる動作をするモデルを作成できます コンテキスト (環境、変数、具体化のタイプ) に基づく: 

-- models/marts/finance/orders_with_taxes.sql
-- Logica di calcolo tasse diversa per paese

SELECT
    order_id,
    customer_id,
    total_amount,

    {% if var("target_market") == "US" %}
    total_amount * 0.08 AS tax_amount,     -- aliquota USA semplificata
    {% elif var("target_market") == "IT" %}
    total_amount * 0.22 AS tax_amount,     -- IVA italiana
    {% else %}
    total_amount * 0.20 AS tax_amount,     -- aliquota default EU
    {% endif %}

    total_amount + tax_amount AS total_with_tax

FROM {{ ref('stg_orders') }}
WHERE status = 'completed'

is_incremental(): 基本パターン

組み込みマクロ is_incremental() インクリメンタル モデルで追加するために使用されます。 モデルがインクリメンタル モードで実行されている場合のみ時間フィルター (完全リフレッシュではありません): 

-- models/marts/events_daily.sql
{{ config(materialized='incremental', unique_key='event_date') }}

SELECT
    DATE_TRUNC('day', event_timestamp) AS event_date,
    event_type,
    COUNT(*) AS event_count,
    COUNT(DISTINCT user_id) AS unique_users
FROM {{ ref('stg_events') }}

-- Questo blocco viene incluso SOLO nelle esecuzioni incrementali
{% if is_incremental() %}
WHERE event_timestamp > (SELECT MAX(event_date) FROM {{ this }})
{% endif %}

GROUP BY 1, 2

ループの対象: 動的 SQL 生成

Jinja ループは、コピー＆ペーストを行わずに反復的な SQL を生成する場合に非常に強力です。 

-- Genera colonne per i giorni della settimana dinamicamente
SELECT
    customer_id,
    order_date,

    {% for day_num in range(1, 8) %}
    SUM(CASE WHEN DAYOFWEEK(order_date) = {{ day_num }}
             THEN total_amount
             ELSE 0 END) AS revenue_day_{{ day_num }}
    {% if not loop.last %},{% endif %}
    {% endfor %}

FROM {{ ref('stg_orders') }}
GROUP BY 1, 2
-- Pivot di metriche da una lista di variabile
{% set metrics = ['revenue', 'order_count', 'avg_order_value'] %}

SELECT
    month,
    region,
    {% for metric in metrics %}
    SUM(CASE WHEN metric_name = '{{ metric }}' THEN metric_value END) AS {{ metric }}
    {%- if not loop.last %},{% endif %}
    {% endfor %}
FROM {{ ref('metrics_unpivoted') }}
GROUP BY 1, 2

マクロ: 再利用可能な SQL 関数

マクロは dbt のコード再利用メカニズムです: パラメータを取る Jinja 関数 そしてSQLを返します。彼らはディレクトリに入ります macros/.

単純なマクロ: Null 値のクリーンアップ

-- macros/utils/safe_divide.sql
-- Divisione sicura che evita division by zero

{% macro safe_divide(numerator, denominator, default_value=0) %}
    CASE
        WHEN {{ denominator }} = 0 OR {{ denominator }} IS NULL
        THEN {{ default_value }}
        ELSE {{ numerator }} / {{ denominator }}
    END
{% endmacro %}

-- Utilizzo nel modello:
SELECT
    customer_id,
    total_revenue,
    order_count,
    {{ safe_divide('total_revenue', 'order_count') }} AS avg_order_value
FROM {{ ref('customer_summary') }}

高度なマクロ: 動的 UNION ALL 生成

-- macros/union_relations.sql
-- Crea UNION ALL da una lista di ref()

{% macro union_all_tables(relations) %}
    {% for relation in relations %}
        SELECT
            '{{ relation }}' AS source_table,
            *
        FROM {{ ref(relation) }}
        {% if not loop.last %}UNION ALL{% endif %}
    {% endfor %}
{% endmacro %}

-- Utilizzo:
-- {{ union_all_tables(['events_jan', 'events_feb', 'events_mar']) }}

run_query() を使用したマクロ: マクロでのウェアハウスのクエリ

-- macros/get_column_values.sql
-- Recupera valori distinti da una colonna per uso in loop

{% macro get_column_values(table, column) %}
    {% set query %}
        SELECT DISTINCT {{ column }}
        FROM {{ ref(table) }}
        ORDER BY 1
    {% endset %}

    {% set results = run_query(query) %}

    {% if execute %}           -- execute è False durante la fase di parsing
        {% set values = results.columns[0].values() %}
        {% do return(values) %}
    {% else %}
        {% do return([]) %}
    {% endif %}
{% endmacro %}

-- Utilizzo per un pivot dinamico:
{% set regions = get_column_values('stg_orders', 'region') %}

SELECT
    order_date,
    {% for region in regions %}
    SUM(CASE WHEN region = '{{ region }}' THEN revenue END) AS revenue_{{ region | lower | replace(' ', '_') }}
    {%- if not loop.last %},{% endif %}
    {% endfor %}
FROM {{ ref('orders_daily') }}
GROUP BY 1

dbt-utils: 標準ライブラリ

dbt-utils これは、dbt エコシステムで最もよく使用されるパッケージです。 これは、どのプロジェクトでもおそらく最初から再発明するであろう一般的なマクロを提供します。 

# packages.yml
packages:
  - package: dbt-labs/dbt_utils
    version: 1.3.0

# Installa con:
# dbt deps

最もよく使用される dbt-utils マクロ

-- 1. generate_surrogate_key: chiave surrogata da più colonne (hash MD5)
SELECT
    {{ dbt_utils.generate_surrogate_key(['order_id', 'customer_id']) }} AS sk,
    order_id,
    customer_id
FROM {{ ref('stg_orders') }}

-- 2. unpivot: trasforma colonne in righe (simile a UNPIVOT SQL)
{{ dbt_utils.unpivot(
    relation=ref('orders_pivoted'),
    cast_to='float',
    exclude=['order_date', 'customer_id'],
    field_name='metric_name',
    value_name='metric_value'
) }}

-- 3. date_spine: genera una sequenza di date continua (per riempire i gap)
WITH date_spine AS (
    {{ dbt_utils.date_spine(
        datepart="day",
        start_date="cast('2024-01-01' as date)",
        end_date="current_date"
    ) }}
),
orders AS (
    SELECT DATE_TRUNC('day', created_at) AS order_date, SUM(amount) AS revenue
    FROM {{ ref('stg_orders') }}
    GROUP BY 1
)
-- LEFT JOIN per avere 0 anche nei giorni senza ordini
SELECT
    d.date_day,
    COALESCE(o.revenue, 0) AS revenue
FROM date_spine d
LEFT JOIN orders o ON d.date_day = o.order_date

-- 4. pivot: trasforma righe in colonne
{{ dbt_utils.pivot(
    column='status',
    values=['completed', 'pending', 'cancelled'],
    agg='count',
    then_value='order_id'
) }}

マクロのベストプラクティス

品質マクロのガイドライン

  • アメリカ合衆国 if execute クエリを実行するマクロの場合: DAG が付属します 数回解析され、すべてのフェーズで実際の実行が必要になるわけではありません
  • ドキュメントマクロ テンプレートと同じ方法 - dbt が生成します Jinja docstring を使用したマクロのドキュメントも
  • 統合パッケージを好む (dbt-utils、dbt-expectations) から 車輪の再発明 — 何千ものプロジェクトによってテストされています
  • マクロをシンプルにする: マクロが読みにくい場合は、 おそらく、それを分割するか、テンプレート内でロジックを明示的な SQL として表現する方がよいでしょう。

アンチパターン: 過剰に設計されたマクロ

最もよくある間違いは、あらゆるものにマクロを使用することです。マクロはレイヤーを追加します 間接的にコードを読みにくくします。真に再利用可能なロジックに使用します。 (プロジェクト内で 3 つ以上の使用)。 1 回または 2 回使用される SQL の場合、明示的なコードは次のとおりです。 よりメンテナンス性が高くなります。

結論と次のステップ

Jinja とマクロを使用すると、dbt は単純な SQL ランナーではなくなり、フレームワークになります プログラム可能な変換の。変数によりモデルが環境に適応できるようになります。 ループは繰り返しを排除し、マクロは再利用可能なロジックをカプセル化します。

次の記事では、本番環境でのパフォーマンスに関する重要なトピックについて説明します。 物質化。ビュー、テーブル、増分モデル、スナップショットをいつ使用するか - 各データセットに適切な戦略を選択する方法についても説明します。

前の記事 ← dbt コアのセットアップ
シリーズの次は dbt マテリアライゼーション: テーブル、ビュー、インクリメンタル →