dbt fundamentals e project structure

La struttura di un progetto dbt va letta come un passaggio decisionale, non come una definizione isolata. Collega domanda, dato, controllo e azione, così il lavoro tecnico resta ancorato a una scelta verificabile anche quando lavori sotto incertezza. Capire dove vanno le source, i modelli e gli ambienti significa decidere in anticipo di chi sarà la fiducia in quei numeri.

Il problema che la struttura risolve

In analytics engineering il nodo centrale è trasformare dati grezzi in modelli affidabili, testati e documentati, che il business possa usare con fiducia. Senza una struttura chiara ogni nuova metrica diventa una query isolata, difficile da mantenere e poco trasparente per chi la eredita. Prendere decisioni sotto incertezza richiede quindi un progetto dbt costruito con metodo, che renda esplicite le fonti, le trasformazioni e le dipendenze invece di lasciarle implicite nel codice di qualcuno.

Un modello in quattro fasi

Il ragionamento si articola in quattro domande che precedono la scrittura del codice.

Fase	Cosa chiarire	Output
Domanda	Quale scelta reale deve migliorare?	Decisione da prendere
Misura	Quale segnale osservabile rappresenta il problema?	Metrica o dato sorgente
Controllo	Quale baseline rende il risultato interpretabile?	Confronto credibile
Azione	Che cosa cambia dopo l’analisi?	Prossimo passo operativo

Lo schema tiene il focus sulla decisione concreta ed evita che la struttura diventi fine a se stessa.

Come rendere concreto il modello

Per passare dal modello alla pratica conviene definire l’unità di lavoro e i segnali da monitorare. L’unità di analisi è una source, un model, un test, un mart, una metrica o un’esposizione. Il segnale principale è di solito freshness, lineage, copertura dei test, costo del modello o fiducia degli stakeholder. La baseline arriva da un periodo precedente, da un gruppo comparabile, da un benchmark o da uno scenario controfattuale. La decisione attesa riguarda un modello dbt, un semantic layer, un contratto, un test o una pipeline di release. Il rischio sempre presente è scambiare un numero disponibile per una prova sufficiente. La formalizzazione deve garantire riproducibilità e lasciare spazio a chi vuole criticare le assunzioni.

Caso studio: integrare Stripe, HubSpot ed eventi

Immagina un progetto dbt che integra dati da Stripe, HubSpot e tracking eventi. La struttura iniziale parte dalla definizione delle source in YAML per ogni sistema, da modelli staging che puliscono e uniformano i dati, da un naming coerente con cartelle distinte per staging, intermediate e marts, e da ambienti separati per sviluppo e produzione. Questa organizzazione riduce la confusione e rende semplice aggiungere nuove metriche o segmenti senza rompere ciò che esiste già.

Evidenza osservata	Lettura prudente	Azione consigliata
Il numero migliora	Potrebbe essere effetto reale o variazione normale	Cercare confronto e segmento
Un segmento cambia più degli altri	La media aggregata nasconde una differenza	Separare coorti o casi d’uso
Il costo cresce insieme al risultato	L’impatto va letto sul margine	Stimare trade-off e sostenibilità

Esercizio guidato

Al livello base scrivi una scheda sintetica per un progetto dbt: definisci la decisione da supportare, la metrica principale, la baseline, il rischio principale e l’azione da prendere se il segnale è confermato. Al livello intermedio costruisci una tabella con tre segmenti o periodi, indicando per ciascuno cosa cambia, una possibile spiegazione alternativa e il controllo che adotteresti prima di raccomandare un’azione. Al livello research-grade prepara un decision memo dettagliato con ipotesi, dati necessari, criteri di esclusione, controlli di qualità, soglia decisionale, rischio residuo e piano di monitoraggio post-decisione. Lavora su un ambiente dbt con dati CRM, eventi e marts; se non li hai, costruisci un dataset sintetico di almeno 200 righe con una dimensione temporale, una dimensione segmento e una metrica di outcome.

L’errore tipico da evitare

Il rischio più comune è usare la struttura dbt come etichetta vuota, mostrando grafici senza decisione, metriche senza baseline o conclusioni che non dichiarano quali assunzioni potrebbero invalidarle. La domanda chiave è semplice: se il risultato fosse instabile, quale scelta sbaglierei? Se non c’è risposta, manca il collegamento tra analisi e azione.

Checkpoint

Prima di proseguire, verifica di saper rispondere a queste domande.

1. Quale decisione concreta dovrebbe migliorare questa lezione?
2. Quale unità di analisi rende il problema misurabile?
3. Quale baseline useresti per evitare una lettura ingenua?
4. Quale errore tipico potrebbe cambiare la conclusione?
5. Quale output consegneresti a uno stakeholder non tecnico?

Riepilogo del ragionamento

La struttura di un progetto dbt non è solo questione tecnica, è la disciplina con cui prendi decisioni sotto incertezza. Organizzare fonti, modelli, naming e ambienti con chiarezza trasforma dati grezzi in informazioni affidabili, riduce i rischi e fa crescere la fiducia. Il percorso problema, formalizzazione, esempi, esercizi e checkpoint serve a far diventare la conoscenza una pratica verificabile.

---

Come è fatto un progetto dbt

Un progetto dbt ben strutturato è la base per decisioni data-driven solide. 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 parzialmente le grandi tabelle; una ephemeral resta una CTE inline e non viene mai materializzata.

Le funzioni Jinja source() e ref() gestiscono rispettivamente le fonti dati e le dipendenze tra modelli. Da qui nascono il lineage automatico, l’esecuzione ordinata e i test di freschezza, perché dbt sa esattamente cosa dipende da cosa.

Il workflow ruota attorno a pochi comandi. dbt run esegue i modelli, dbt test lancia i test, dbt docs generate produce documentazione e lineage, e dbt build combina run, test, seed e snapshot in un’unica passata. In ambiente CI si usa spesso un comando più mirato, dbt build --select state:modified+ --defer --state ./target/, che costruisce solo i modelli modificati e quelli a valle.

In un caso reale un team di dati ha adottato dbt in otto settimane per integrare dati operativi e finanziari, e ne ha tratto decisioni più tempestive e di qualità migliore. Il motore di tutto questo è Jinja, che porta in dbt cicli, condizioni e variabili e permette di scrivere modelli parametrici e ambienti differenziati.

Controllo di qualità

Prima di affidarti a un modello dbt verifica completezza, duplicati, timezone, definizioni cambiate e segmenti esclusi. Molti errori non nascono dal modello ma dai dati di partenza, che non rappresentano il comportamento atteso.

Mettere alla prova la struttura

Per consolidare la competenza, tratta la struttura dbt come un piccolo progetto in cui una metrica deve diventare affidabile per altri team. L’obiettivo è consegnare un modello testato, documentato e con un’ownership chiara, tenendo separati contesto, misura, azione e limite.

Esempio operativo

Parti da una domanda semplice: quale decisione migliorerebbe se applicassi bene questa lezione? Poi costruisci un esempio in tre righe, una per il contesto, una per il dato o modello usato e una per la decisione presa dopo aver controllato i rischi. La qualità si misura sulla tracciabilità del ragionamento, non sulla complessità tecnica.

Checkpoint di lavoro

• Definisci la decisione da migliorare con un verbo operativo
• Identifica il segnale principale e almeno un guardrail
• Aggiungi una baseline per interpretare il segnale
• Esplicita il rischio più probabile
• Consegna un output che un reviewer possa aprire e criticare

Riepilogo di padronanza

Hai assimilato la lezione quando sai spiegarla senza gergo, applicarla a un caso realistico e difendere una raccomandazione con i suoi limiti e controlli. Se manca qualcosa, torna al modello concettuale e riduci l’ambizione dell’esempio.