Macro dbt: una guida completa

Nell’analytics engineering, le dbt (data build tool) macro offrono un modo potente per scrivere logica SQL dinamica e riutilizzabile tramite blocchi di codice riutilizzabili. 

In questo tutorial esploreremo le basi delle macro dbt, come costruirle usando Jinja, le best practice per la manutenibilità e le applicazioni reali, il tutto con esempi di codice. 

Cosa sono le macro dbt?

Le macro dbt sono blocchi di codice riutilizzabili scritti usando il linguaggio di templating Jinja all’interno di dbt, che ti permette di generare SQL in modo dinamico. Aiutano a ridurre la ripetizione e a centralizzare la logica di trasformazione. 

Queste macro funzionano come le funzioni nei linguaggi di programmazione tradizionali.

Per esempio, se devi calcolare una metrica specifica in più modelli, una macro può incapsulare quel calcolo, rendendone più semplice la manutenzione e l’aggiornamento.

Le macro possono anche essere archiviate in pacchetti, come dbt-utils.

Perché usare le macro dbt?

Le macro portano diversi vantaggi, principalmente:

• Ridurre la ridondanza: puoi scrivere un blocco di logica una volta e riutilizzarlo ovunque.
• Coerenza: applicare la stessa logica di trasformazione tra i modelli senza duplicazione manuale.
• Flessibilità: le macro supportano parametri, rendendole adattabili a vari input.
• Condivisione tra progetti: macro ben progettate possono essere condivise come pacchetti.

Questi benefici portano a codebase più pulite, manutenibili e scalabili.

Concetti fondamentali delle macro dbt

Per aiutarti a capire come funzionano le macro in dbt, vediamo alcuni concetti chiave.

1. Riutilizzabilità

Le macro ti permettono di definire una porzione di logica SQL una volta e riutilizzarla in più modelli, test o persino in altre macro.

2. Motore di templating Jinja

L’integrazione di Jinja con dbt rende possibile inserire variabili, applicare condizioni e iterare su liste, tutto prima che il tuo SQL raggiunga il database. dbt compila questo template in SQL grezzo, rendendo le macro indipendenti dal database.

3. Introduzione di tecniche di programmazione

Le macro possono trasformare SQL in un framework programmabile. Consentono logica, cicli e condizioni—cose comuni che l’SQL standard non gestisce con la stessa flessibilità.

Come le funzioni, le macro in dbt possono accettare argomenti (parametri) e possono essere chiamate con input diversi per produrre output diversi. Aiutano a semplificare trasformazioni complesse suddividendole in unità più piccole e riutilizzabili. 

Creare macro con Jinja

Vediamo ora come possiamo costruire alcune macro per conto nostro.

Jinja è il motore di templating che alimenta le macro dbt, consentendoti di trattare l’SQL come testo dinamico e programmabile. 

Costrutti di template e delimitatori

Per usare Jinja, dovrai usare specifici costrutti di template e delimitatori.

Ecco alcuni costrutti e delimitatori comuni:

• Espressioni {{ }}: inseriscono espressioni.
• Istruzioni {% %}: eseguono istruzioni.
• Commenti {# #}: aggiungono commenti che vuoi che dbt ignori.

Nelle macro, {{ ... }} si usa per espressioni che devono produrre un valore (ad es. nomi di colonne o calcoli), mentre {% ... %} si usa per il flusso di controllo (loop, if/else, definizioni di macro). I commenti Jinja usano {# ... #} e vengono rimossi del tutto in fase di compilazione.

Ecco un esempio della sintassi usata per le istruzioni nelle macro:

{% macro your_macro_name(your_variable) %}
    select 'Hello, {{ your_variable}}' as greeting
{% endmacro %}Offerto da

Ecco un esempio di come usare le istruzioni per creare una macro:

{% macro greet(name) %}
    select 'Hello, {{ name }}' as greeting
{% endmacro %}Offerto da

Per eseguire la macro, usa questo:

dbt run-operation greet(name) --args 'Austin'Offerto da

Gestione delle variabili

Puoi passare variabili nelle macro o definirle all’interno. Filtri come upper o lower possono trasformare valori testuali.

Ecco un’implementazione della funzione upper per trasformare tutti i valori di testo in maiuscolo. 

{% macro to_upper_case(column_name) %}
    upper({{ column_name }})
{% endmacro %}Offerto da

Per implementarla, dovresti chiamare/fare riferimento alla macro appena creata nel tuo modello dbt.

Ecco un esempio di codice:

SELECT
    id,
    {{ to_upper_case('product_name') }} AS product_name_upper
FROM {{ source('public', 'orders') }}Offerto da

Strutture di controllo

Successivamente, in modo simile ai linguaggi di programmazione, le macro dbt possono offrire quanto segue:

• Istruzioni condizionali ({% if %} / {% endif %}):
• Cicli ({% for %} / {% endfor %}) 

Queste strutture ti permettono di costruire dinamicamente clausole SQL o generare più espressioni in base agli input.

Questo rende più semplice per le macro gestire compiti complessi di generazione SQL.

Gestione dei parametri ed error handling

Le macro possono validare gli input e generare errori in fase di compilazione per prevenire problemi in esecuzione.

I parametri sono definiti nella dichiarazione della macro usando le parentesi (), in modo simile alle definizioni di funzione nei linguaggi di programmazione.

Ecco un esempio di come includere 2 parametri:

{% macro my_macro(param1, param2) %}
    SELECT
        {{ param1 }},
        {{ param2 }}
    FROM my_table
{% endmacro %}Offerto da

Come puoi vedere, nella prima riga abbiamo incluso sia param1 che param2.

Per richiamare la macro in un modello dbt, dovresti usare le doppie graffe {{ }}. I parametri vengono passati come argomenti tra parentesi.

SELECT
    id,
    {{ my_macro('column_a', 'column_b') }}
FROM my_source_tableOfferto da

In questo caso, abbiamo specificato column_a e column_b come nostri parametri.

Guida alla configurazione per lavorare con le macro dbt

Prima di iniziare a creare e usare macro, predisponiamo un ambiente di lavoro così puoi seguire gli esempi in questo tutorial. 

Questo assicurerà che tu abbia dbt installato, un dataset di esempio caricato e la struttura di cartelle giusta per creare macro.

1. Installa dbt Core

Ti servirà dbt Core installato in locale. Se in questo tutorial usi Postgres, installa con questo comando:

pip install dbtOfferto da

Se il tuo progetto usa un data warehouse, esegui invece i relativi comandi:

pip install dbt-core dbt-postgres

pip install dbt-core dbt-snowflake

pip install dbt-core dbt-bigqueryOfferto da

2. Crea un progetto dbt

Prima di eseguire qualsiasi comando dbt, dobbiamo configurare un ambiente di progetto.

Naviga nella directory dei progetti desiderata.

Qui memorizzerai i file del progetto dbt. In questo caso, archivieremo tutti i file correlati in questa cartella del progetto dbt.

Per inizializzare un progetto dbt, dovrai eseguire:

dbt initOfferto da

cd ~/dbt-macros-tutorialOfferto da

Crea una struttura di cartelle in questo formato:

macros_tutorial/
  ├─ models/
  ├─ macros/
  ├─ tests/
  ├─ seeds/
  ├─ dbt_project.ymlOfferto da

3. Prepara il dataset di esempio

Useremo Python per generare un piccolo dataset di ordini da caricare in Postgres (o nel warehouse scelto).

import pandas as pd
import random
from datetime import datetime, timedelta
from sqlalchemy import create_engine

# Create sample orders dataframe
random.seed(42)
num_rows = 20
start_date = datetime(2025, 1, 1)

data = []
for i in range(1, num_rows + 1):
    order_date = start_date + timedelta(days=random.randint(0, 30))
    ship_date = order_date + timedelta(days=random.randint(1, 10))
    data.append({
        'order_id': i,
        'customer_id': random.randint(100, 105),
        'order_date': order_date.date(),
        'ship_date': ship_date.date(),
        'status': random.choice(['pending', 'shipped', 'delivered']),
        'revenue': round(random.uniform(50, 500), 2),
        'cost': round(random.uniform(20, 400), 2)
    })

df = pd.DataFrame(data)

# Load into Postgres
engine = create_engine('postgresql://user:password@localhost:5432/dbt_demo')
df.to_sql('orders', engine, if_exists='replace', index=False)Offerto da

Nota: aggiorna la stringa di connessione per il tuo database.

4. Crea una sorgente in dbt

Aggiungi quanto segue in models/src_orders.yml:

version: 2
sources:
  - name: public
schema: public

    tables:
      - name: ordersOfferto da

5. Testa la connessione e la sorgente

dbt debug

dbt run-operation list_relations --args '{"schema_name": "public"}'Offerto da

Ora sei pronto per iniziare a scrivere macro che operano su questo dataset.

Come scrivere e usare le macro dbt

Adesso proviamo a scrivere alcune macro per conto nostro.

Definire le macro

Posiziona le definizioni delle macro in file .sql nella directory macros/.

Quando assegni i nomi, assicurati di dare a ogni macro un nome descrittivo che ne rifletta lo scopo e usa parametri per renderla flessibile. Aggiungere un breve docstring in cima aiuta i colleghi a capirne l’intento.

Ecco un esempio:

    -- macros/my_macro.sql
    {% macro cents_to_dollars(column_name, precision=2) %}
        ({{ column_name }} / 100.0)::numeric(18, {{ precision }})
    {% endmacro %}Offerto da

Richiamare le macro nei modelli

Chiami le macro all’interno dei modelli con {{ macro_name(arg1, arg2) }}. Possono essere usate nelle clausole SELECT, nei filtri WHERE o anche in interi blocchi CTE, permettendoti di inserire pattern SQL riutilizzabili ovunque.

Ecco un esempio:

    -- models/my_model.sql
    SELECT
        order_id,
        {{ cents_to_dollars('amount_in_cents') }} AS amount_in_dollars,
        {{ cents_to_dollars('tax_in_cents', precision=4) }} AS tax_in_dollars
    FROM {{ ref('raw_orders') }}Offerto da

Richiamare le macro dalla CLI

Per attività operative al di fuori della build dei modelli, usa questo formato/sintassi:

dbt run-operation macro_name --args '{"param": "value"}'Offerto da

Questo ti permette di eseguire SQL di utilità come creazione di schemi o pulizia dati senza costruire un modello.

Ecco un esempio di comando:

dbt run-operation greet --args '{"name": "Austin"}'Offerto da

Usare macro dai pacchetti

Le macro possono anche provenire da pacchetti in dbt, come dbt-utils.

Quando installi un pacchetto tramite packages.yml, le sue macro diventano disponibili immediatamente. Per farlo, dovrai eseguire dbt deps.

Puoi poi richiamare le nuove macro aggiunte con questo formato: package_name.macro_name.

Organizzazione dei file delle macro

Per una migliore organizzazione, ordina e separa le macro per funzionalità per migliorare la manutenibilità. 

Prova a raggruppare le macro correlate in file separati (ad es. date_utils.sql, string_utils.sql) per la manutenibilità. Questo rende più facile trovare e aggiornare la logica nel tempo.

Esempi di macro dbt in pratica

Ecco alcuni esempi di macro in casi d’uso più pratici:

Macro di confronto date

Mettiamo che tu voglia creare una funzione che userai spesso per confrontare date.

In questo caso, puoi usare una macro per calcolare la differenza in giorni tra due campi data gestendo le differenze tra dialetti SQL.

Inizia creando un nuovo file qui: macros/date_utils.sql.

Poi usa il seguente codice:

{% macro days_between(start_col, end_col) %}
    {#-- Handle different warehouses --#}
    {% if target.type in ['postgres', 'redshift'] %}
        (DATE_PART('day', {{ end_col }}::timestamp - {{ start_col }}::timestamp))
    {% elif target.type in ['snowflake'] %}
        DATEDIFF('day', {{ start_col }}, {{ end_col }})
    {% elif target.type in ['bigquery'] %}
        DATE_DIFF(CAST({{ end_col }} AS DATE), CAST({{ start_col }} AS DATE), DAY)
    {% else %}
        -- Fallback to ANSI-ish expression; may need adjustment per engine
        CAST({{ end_col }} AS DATE) - CAST({{ start_col }} AS DATE)
    {% endif %}
{% endmacro %}Offerto da

Ora useremo questa nuova macro days_between in un modello.

with src as (
  select * from {{ source('public', 'orders') }}
)
select
  order_id,
  customer_id,
  order_date,
  ship_date,
  {{ days_between('order_date', 'ship_date') }} as days_to_ship
from srcOfferto da

Macro generate_schema_name personalizzata

Per impostazione predefinita, dbt usa una macro di default chiamata generate_schema_name. Questa macro è usata per specificare il nome dello schema in cui deve essere costruito un modello.

Puoi anche sovrascrivere il default di dbt per controllare lo schema usato per ambiente.

Puoi includere questo file nella posizione: macros/generate_schema_name.sql.

`sql
{% macro generate_schema_name(custom_schema_name, node) -%}
    {# Policy:
       - prod:    ANALYTICS
       - nonprod: dev_analytics, ci_analytics, etc.
    #}
    {%- if target.name == 'prod' -%}
        {{ custom_schema_name | trim }}
    {%- else -%}
        {{ (target.name ~ '_' ~ custom_schema_name) | lower | replace(' ', '_') }}
    {%- endif -%}
{%- endmacro %}Offerto da

Come aiuta: su dev, i modelli finiscono nell’ambiente dev_analytics (isolamento). Su prod, finiscono in analytics. Questo crea deployment prevedibili e senza collisioni.

Eseguire SQL fuori da un modello

Puoi anche eseguire comandi SQL al di fuori dei modelli per operazioni come pulizia tabelle o aggiornamenti di metadati senza creare modelli.

Puoi scrivere una macro che esegue SQL grezzo e poi eseguirla tramite dbt run-operation.

Questo è utile per DDL (drop/creazione tabelle) o aggiornamenti di metadati che non rientrano in un modello.

Ecco la macro:

{% macro cleanup_temp_tables() %}
    {% set sql %}
        drop table if exists {{ target.schema }}.temp_table;
        delete from {{ target.schema }}.audit_log where event_type = 'test';
    {% endset %}
    {{ run_query(sql) }}
{% endmacro %}Offerto da

Poi esegui questa operazione nel terminale:

dbt run-operation cleanup_temp_tablesOfferto da

Questo ti permetterà di eseguire macro senza includerle nei modelli.

Esempio di macro parametrica

Possiamo anche creare una macro altamente parametrica, come una funzione. 

In questo esempio, filtreremo i record in base a uno status fornito, quando i valori sono passati. Questo usa istruzioni if e do per creare la logica.

{% macro where_orders(status=None, min_date=None, max_date=None) %}
  {%- set clauses = [] -%}
  {%- if status is not none -%}
    {%- do clauses.append("status = '" ~ status ~ "'") -%}
  {%- endif -%}
  {%- if min_date is not none -%}
    {%- do clauses.append("order_date >= '" ~ min_date ~ "'") -%}
  {%- endif -%}
  {%- if max_date is not none -%}
    {%- do clauses.append("order_date < '" ~ max_date ~ "'") -%}
  {%- endif -%}
  {%- if clauses | length > 0 -%}
    where {{ clauses | join(' and ') }}
  {%- endif -%}
{% endmacro %}Offerto da

Ora applichiamo questa macro in un modello:

with src as (
  select * from {{ ref('orders') }}
)
select *
from src
{{ where_orders(status='shipped', min_date='2025-01-05') }}Offerto da

Questa macro incorpora logica per quando un argomento è omesso; quel criterio viene ignorato. Questo mantiene pulita la logica opzionale.

Best practice per le macro dbt

Progettare ottime macro non significa solo far compilare l’SQL. Le migliori macro sono individuabili, ben documentate, prevedibili, testabili e facili da deprecare o estendere. 

Ecco alcune best practice da seguire:

1. Convenzioni di naming e design dei parametri

Come per SQL e i linguaggi di programmazione, vanno seguite convenzioni di naming per garantire leggibilità.

Ecco alcuni suggerimenti per i nomi:

• Sii esplicito e orientato all’azione. Preferisci verbi o intenti chiari (ad es. generate_select_list, where_orders) a nomi vaghi come helper.
• Mantieni i nomi stabili e in minuscolo. Usa snake_case e prefissi stabili per dominio, ad es. date_*, string_*, test_*, admin_*.

2. Strategie di documentazione

Dovresti sviluppare abitudini per documentare ciò che crei. La documentazione va fatta nei luoghi in cui gli sviluppatori guardano. 

Per esempio, combina docstring inline + un macros.yml (o schema.yml) con descrizioni ed esempi.

I contenuti della documentazione possono includere:

• Scopo e output atteso (1–2 frasi)
• Tabella dei parametri con default e valori consentiti
• Breve esempio di invocazione in un modello e con run-operation
• Note sul comportamento cross‑database

Esempio di snippet di un file di config:

version: 2
macros:
  - name: days_between
    description: |
      Return day difference between two date expressions, normalized across warehouses.
    arguments:
      - name: start_col
        type: string
        description: Column/expression for the start date
      - name: end_col
        type: string
        description: Column/expression for the end date
    docs:
      show: trueOfferto da

3. Organizzazione del codice

Anche il tuo codice dovrà essere ben organizzato, soprattutto quando devi gestire un gran numero di macro nella tua directory.

Prova a strutturare per dominio per facilitarne l’uso. Ecco alcuni esempi:

• macros/date_utils.sql
• macros/string_utils.sql
• macros/testing/ (test personalizzati)
• macros/admin/ (DDL, housekeeping)
• macros/compat/ (shim per warehouse)

4. Mantieni le macro piccole e con uno scopo singolo

Una macro dovrebbe fare una cosa bene. Se noti che una macro cresce troppo o gestisce logiche non correlate, suddividila in macro più piccole. Questo migliora il riuso e rende i test più semplici.

5. Testa le macro con dati rappresentativi

Usa modelli di test dedicati o un ambiente di staging per validare il comportamento delle macro. 

Per esempio:

• Crea un piccolo seed dataset che copra i casi limite.
• Scrivi un modello di test che richiami la macro con parametri diversi.
• Usa dbt run e ispeziona l’SQL compilato per verificarne la correttezza.

Consiglio pro: abbina le macro a test personalizzati con dbt test per verificare che gli output rispettino i vincoli attesi.

Casi d’uso comuni e applicazioni

Le macro dbt sono versatili e le loro applicazioni si estendono a molti flussi di lavoro quotidiani di analytics engineering. 

Ecco alcuni esempi più ampi e dettagliati:

• Standardizzare le trasformazioni dati: le macro possono garantire che le stesse convenzioni di naming, trimming, gestione dei null e cast di tipo siano applicate a più modelli. Ad esempio, puoi creare una macro standardize_customer_name per pulire e formattare i nomi in modo identico in tutti i mart.
• Supportare query cross‑database: i warehouse hanno sottili differenze di dialetto SQL. Le macro possono astrarre tali differenze—ad esempio usando DATEDIFF su Snowflake e DATE_DIFF su BigQuery. Questo rende i tuoi modelli portabili.
• Automatizzare i controlli di qualità: scrivi macro riutilizzabili che generano test sui dati, come controllare ID duplicati, colonne critiche nulle o valori fuori range. Possono essere richiamate in più modelli di test.
• Semplificare pattern SQL ripetitivi: CTE comuni, campi calcolati o clausole di filtro possono essere parametrizzati nelle macro. Per esempio, una macro per costruire clausole WHERE dinamiche in base a filtri opzionali evita il copia‑incolla di logiche complesse.

Tecniche avanzate e ottimizzazione delle prestazioni

Le macro dbt possono essere usate anche in applicazioni più avanzate. Vediamo di seguito due approcci comuni.

Pattern ricorsivi e di meta‑programmazione

Le macro possono chiamare altre macro, iterare sulla metadata, o generare dinamicamente frammenti SQL basandosi sull’ispezione degli schemi. 

Questo ti permette di:

• Creare automaticamente modelli di staging per ogni tabella sorgente.
• Generare query di pivot/unpivot senza digitare manualmente ogni colonna.
• Costruire query sensibili all’ambiente iterando su variabili di configurazione.

Strategie di ottimizzazione delle prestazioni

Puoi anche fare ulteriori ottimizzazioni per migliorare le prestazioni:

• Riduci la complessità delle query includendo selettivamente solo le colonne o le join necessarie.
• Adatta le materializzazioni o le strategie SQL in base al tipo di warehouse.

Integrazione con l’ecosistema dbt

Le macro sono pensate per far parte dell’ecosistema dbt, diventando ancora più potenti se abbinate a pacchetti, funzionalità cloud e strumenti esterni.

Gestione dei pacchetti

Molti pacchetti community di dbt come dbt-utils, dbt-date e dbt-expectations sono essenzialmente raccolte di macro altamente riutilizzabili. 

Questi pacchetti offrono trasformazioni, test e helper preconfezionati senza reinventare la ruota. 

Compatibilità con dbt Cloud e strumenti per sviluppatori

Le macro funzionano senza problemi negli ambienti dbt Cloud, il che significa che la tua logica SQL dinamica si comporta allo stesso modo sia in locale sia in un job pianificato nel cloud. 

Si integrano anche bene con il controllo versione, le pipeline CI/CD e i processi di code review, assicurando che gli aggiornamenti alle macro siano testati e distribuiti in modo coerente.

Strategie di implementazione nel mondo reale

Passare da script SQL tradizionali a un workflow dbt basato su macro richiede sia cambiamenti tecnici sia adozione culturale.

Migrazione e change management

Durante la migrazione, inizia identificando pattern SQL ripetuti tra i modelli. Poi rifattorizzali in macro in modo incrementale, validando che l’SQL compilato corrisponda alla vecchia logica. 

Usa feature flag (var()) per attivare/disattivare la nuova logica delle macro durante il rollout, riducendo al minimo le interruzioni. Soprattutto, informa gli stakeholder dei cambiamenti per evitare di rompere query a valle.

Governance e strategie di deployment

Per la governance, inizia stabilendo chiare convenzioni di naming, standard dei parametri e requisiti di documentazione per tutte le macro.

Poi revisiona le modifiche alle macro nelle pull request proprio come gli aggiornamenti ai modelli, assicurandoti che rispettino standard di performance e compatibilità. 

In produzione, monitora i log dei job per le query generate dalle macro per verificare che vengano eseguite come previsto. Per progetti ricchi di macro, imposta dashboard di osservabilità per tracciare i tempi di compilazione e le prestazioni delle query per tipo di macro.

Conclusione

Le macro dbt sono una componente chiave di produttività e manutenibilità nei moderni team di analytics engineering. Usare i modelli dbt insieme alle macro può portare a risultati migliori per le operazioni di pulizia dei dati.

Vuoi saperne di più su dbt? Il nostro corso Introduction to dbt e il dbt Tutorial potrebbero esserti utili.