Jinja2 v dbt: Co to je a proč existuje

dbt usa Jinja2, šablonovací jádro Pythonu, pro přidání programovatelnosti do SQL. Vše, co se vejde mezi dvojité složené závorky {{ }} je výraz Jinja, vše mezi tím {% %} to je kontrolní příkaz (if, for, set).

Před spuštěním každého modelu ve skladu, dbt kompilovat šablonu Jinja v čistém SQL. Zkompilovaný SQL můžete vidět ve složce target/compiled/ po každém dbt run.

Proměnné: var() a env_var()

dbt poskytuje dvě funkce pro přístup k proměnným v kódu SQL:

var(): Proměnné 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(): Proměnné prostředí

-- 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/others podmínky v šablonách

Podmíněné příkazy Jinja vám umožňují psát modely, které se chovají odlišně na základě kontextu (prostředí, proměnné, typ materializace): 

-- 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(): Základní vzor

Vestavěné makro is_incremental() používá se v přírůstkových modelech k přidání dočasný filtr pouze tehdy, když je model spuštěn v přírůstkovém režimu (není v plné aktualizaci): 

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

Smyčka pro: Dynamické generování SQL

Smyčky Jinja jsou velmi výkonné pro generování opakovaného SQL bez kopírování a vkládání: 

-- 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: Opakovaně použitelné funkce SQL

Makra jsou mechanismem opětovného použití kódu ve funkcích dbt: Jinja, které přebírají parametry a vrátí SQL. Jdou do adresáře macros/.

Jednoduché makro: Vyčištění nulové hodnoty

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

Pokročilé makro: Dynamická generace 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 s run_query(): Dotazování na sklad v makrech

-- 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: Standardní knihovna

dbt-utils je to nejpoužívanější balíček v ekosystému dbt. Poskytuje běžná makra, která by každý projekt pravděpodobně znovu objevil od nuly: 

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

# Installa con:
# dbt deps

Nejpoužívanější 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'
) }}

Doporučené postupy pro makra

Pokyny pro kvalitní makra

  • USA if execute pro makra, která provádějí dotazy: přichází DAG analyzován několikrát a ne všechny fáze vyžadují skutečné provedení
  • Makra dokumentů stejným způsobem jako šablony — dbt vygeneruje dokumentace také pro makra s dokumentačními řetězci Jinja
  • Preferujte konsolidované balíčky (dbt-utils, dbt-očekávání). znovuobjevení kola – jsou testovány tisíci projektů
  • Udržujte makra jednoduchá: pokud je makro obtížně čitelné, pravděpodobně je lepší to rozdělit nebo vyjádřit logiku jako explicitní SQL v šabloně

Anti-pattern: Přepracovaná makra

Nejčastější chybou je používání maker na vše. Makra přidávají vrstvy nepřímé směrování, které činí kód méně čitelným. Použijte je pro skutečně znovu použitelnou logiku (3+ použití v projektu). Pro SQL použitý jednou nebo dvakrát je explicitní kód udržitelnější.

Závěry a další kroky

S Jinja a makry přestává dbt být jednoduchým SQL běžcem a stává se frameworkem programovatelné transformace. Díky proměnným jsou modely přizpůsobitelné prostředí, tzn smyčky eliminují opakování, makra zapouzdřují znovu použitelnou logiku.

Další článek se zabývá zásadním tématem pro výkon ve výrobě: materializace. Kdy použít pohledy, tabulky, přírůstkové modely a snímky — a jak zvolit správnou strategii pro každou datovou sadu.

Předchozí článek ← Nastavení jádra dbt
Další v řadě dbt Materializace: Tabulka, Pohled, Přírůstkové →