dbt fundamentals and project structure

Questa lezione appartiene al binario ml-tabellare: parliamo di tabelle, di come si organizzano in un progetto e di come si collegano tra loro. L’obiettivo è capire perché la struttura delle cartelle non è burocrazia, ma il primo strumento di fiducia sui dati.

L’idea in una frase

La struttura di un progetto dbt assegna a ogni file un posto fisso tra fonti, trasformazioni e modelli di consumo, così ogni metrica ha un lignaggio tracciabile e un responsabile riconoscibile. Detto altrimenti: se sai dove sta ogni cosa, sai anche chi risponde di ogni numero.

Come si costruisce, passo dopo passo

1. Dichiara ogni sorgente una sola volta in YAML, con nome, database e test di freschezza.
2. Metti le pulizie senza logica di business nei modelli di staging, uno per sorgente.
3. Sposta le regole condivise nei modelli intermediate e i tavoli finali nei marts, uno per dominio di consumo.
4. Collega fonti e modelli solo con source() e ref(), mai con nomi di tabelle scritti a mano.
5. Separa gli ambienti di sviluppo e produzione, così i test girano su schemi isolati e la produzione cambia solo al merge.

Come è fatto un progetto dbt

Un progetto dbt ben strutturato rende le decisioni data-driven più solide. Ogni file ha un posto fisso. La struttura tipica è questa:

my_dbt_project/
├── dbt_project.yml          ← configurazione principale
├── packages.yml             ← dipendenze esterne
├── profiles.yml             ← connessioni ai warehouse
├── models/
│   ├── staging/             ← dati grezzi puliti
│   ├── intermediate/        ← trasformazioni business
│   └── marts/               ← modelli per consumo business
├── seeds/                   ← dati statici CSV
├── snapshots/               ← storicizzazione dati
├── tests/                   ← test SQL
├── macros/                  ← funzioni riusabili
├── analyses/                ← query ad-hoc
└── docs/                    ← documentazione opzionale

Il file dbt_project.yml definisce le configurazioni globali, inclusa la materializzazione dei modelli.

Una view è leggera e non persiste i dati. Una table è materializzata e più veloce da leggere. Una materializzazione incremental aggiorna solo le righe nuove nelle grandi tabelle. Una ephemeral resta una CTE inline e non viene mai materializzata.

Le funzioni source() e ref() collegano rispettivamente le fonti e i modelli. Da qui nascono lignaggio automatico, esecuzione ordinata e test di freschezza, perché dbt sa esattamente cosa dipende da cosa.

Comandi e ambienti

Il workflow ruota attorno a pochi comandi.

dbt run esegue i modelli. dbt test lancia i test. dbt docs generate produce documentazione e lignaggio. dbt build combina run, test, seed e snapshot in un’unica passata.

In integrazione continua si usa un comando mirato come dbt build --select state:modified+ --defer --state ./target/, che ricostruisce solo i modelli modificati e quelli a valle.

Il motore di tutto questo è Jinja. Jinja porta in dbt cicli, condizioni e variabili e permette di scrivere modelli parametrici e ambienti differenziati.

L’errore che svuota la struttura

Il rischio più comune è usare la struttura come etichetta vuota: cartelle perfette, ma nessuno sa quale numero decide cosa. Se i grafici non portano a una decisione e le metriche non hanno una baseline, la struttura è solo scenografia.

La domanda di controllo è semplice: se il risultato fosse instabile, quale scelta sbaglieresti? Se la struttura non ti aiuta a rispondere, va semplificata.

Verdetto: sorgenti dichiarate una volta sola, staging senza logica di business, un mart per dominio di consumo; se un nuovo arrivato non trova un file in un minuto, la struttura va semplificata.

La convenzione che ha fatto scuola

dbt Labs, nata nel 2016 come Fishtown Analytics, ha codificato la struttura standard dei progetti nelle sue guide pubbliche e nei corsi: staging per le pulizie senza logica di business, modelli intermedi per le regole condivise, mart per i tavoli di consumo. Quella convenzione, con sorgenti dichiarate una volta sola e dipendenze tracciate dal lignaggio, è diventata il riferimento adottato dai team che usano dbt in produzione. È la prova che la struttura delle cartelle non è burocrazia: è il meccanismo che permette a un team in crescita di fidarsi dei numeri.

Domande per metterti alla prova

1. Dove dichiareresti una nuova sorgente e quali informazioni minime includeresti?
2. Cosa va in un modello di staging e cosa deve restarne fuori?
3. Perché le dipendenze tra modelli passano da riferimenti dichiarati e non da nomi di tabelle scritti a mano?
4. Come isoli i test di sviluppo dalla produzione in un progetto dbt?