Jinja2 w dbt: co to jest i dlaczego istnieje

dbt USA Jinja2, silnik szablonów Pythona, aby zwiększyć programowalność do SQL'a. Wszystko, co mieści się w podwójnych nawiasach klamrowych {{ }} to wyrażenie Jinja, wszystko pomiędzy {% %} to jest instrukcja sterująca (jeśli, dla, ustawiona).

Przed uruchomieniem każdego modelu w magazynie dbt skompilować szablon Jinja w czystym SQL. Skompilowany kod SQL można zobaczyć w folderze target/compiled/ po każdym dbt run.

Zmienne: var() i env_var()

dbt udostępnia dwie funkcje dostępu do zmiennych w kodzie SQL:

var(): Zmienne projektu

-- 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(): Zmienne środowiskowe

-- 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') }}"

warunki if/else w szablonach

Instrukcje warunkowe Jinja umożliwiają pisanie modeli, które zachowują się inaczej w oparciu o kontekst (środowisko, zmienne, rodzaj materializacji): 

-- 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_inkrementalny(): Podstawowy wzorzec

Wbudowane makro is_incremental() jest używany w modelach przyrostowych do dodawania filtr czasowy tylko wtedy, gdy model jest uruchamiany w trybie przyrostowym (nie w pełnym odświeżeniu): 

-- 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

Pętla dla: Dynamiczne generowanie SQL

Pętle Jinja są bardzo wydajne w generowaniu powtarzalnego kodu SQL bez wklejania kopii: 

-- 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

Makra: funkcje SQL wielokrotnego użytku

Makra to mechanizm ponownego wykorzystania kodu w dbt: funkcje Jinja, które przyjmują parametry i zwróć SQL. Wchodzą do katalogu macros/.

Proste makro: czyszczenie wartości 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') }}

Zaawansowane makro: dynamiczna generacja 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']) }}

Makro z run_query(): Wysyłanie zapytań do magazynu w makrach

-- 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: Biblioteka standardowa

narzędzia dbt jest to najczęściej używany pakiet w ekosystemie dbt. Zawiera typowe makra, które każdy projekt prawdopodobnie wymyśliłby od nowa: 

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

# Installa con:
# dbt deps

Najczęściej używane makra 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'
) }}

Najlepsze praktyki dotyczące makr

Wytyczne dotyczące makr jakości

  • USA if execute w przypadku makr wykonujących zapytania: pojawia się DAG analizowany kilka razy i nie wszystkie fazy wymagają faktycznego wykonania
  • Makra dokumentu w taki sam sposób jak szablony — wygeneruje dbt dokumentacja również dla makr z dokumentacją Jinja
  • Preferuj pakiety skonsolidowane (dbt-utils, dbt-oczekiwania) do wynalezienie koła na nowo — są testowane przez tysiące projektów
  • Dbaj o prostotę makr: jeśli makro jest trudne do odczytania, prawdopodobnie lepiej jest go podzielić lub wyrazić logikę jako jawny SQL w szablonie

Anty-wzorzec: przeprojektowane makra

Najczęstszym błędem jest używanie makr do wszystkiego. Makra dodają warstwy pośrednio, które sprawia, że kod jest mniej czytelny. Użyj ich, aby uzyskać naprawdę logikę wielokrotnego użytku (3+ zastosowań w projekcie). W przypadku języka SQL użytego raz lub dwa razy kod jawny to bardziej łatwe w utrzymaniu.

Wnioski i dalsze kroki

Dzięki Jinja i makrom dbt przestaje być prostym programem uruchamiającym SQL i staje się frameworkiem programowalnej transformacji. Zmienne sprawiają, że modele można dostosować do środowiska, tj pętle eliminują powtórzenia, makra zawierają logikę wielokrotnego użytku.

Następny artykuł porusza kluczowy temat dotyczący wydajności w środowisku produkcyjnym: materializacje. Kiedy używać widoków, tabel, modeli przyrostowych i migawek — i jak wybrać odpowiednią strategię dla każdego zbioru danych.

Poprzedni artykuł ← Konfiguracja rdzenia dbt
Następny w serii dbt Materializacje: Tabela, Widok, Przyrostowe →