dbt fundamentals and 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.

Phase	What to clarify	Output
Question	Which real choice needs improvement?	Decision to make
Measure	Which observable signal represents the problem?	Metric or source data
Control	Which baseline makes the result interpretable?	Credible comparison
Action	What changes after the analysis?	Next operational step

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

Observed evidence	Cautious interpretation	Recommended action
The number improves	Could be a real effect or normal variation	Look for comparison and segment
One segment changes more than others	The aggregated average hides a difference	Separate cohorts or use cases
Cost grows along with the result	Impact must be read on the margin	Estimate trade-offs and sustainability

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. Which concrete decision should this lesson improve?
2. Which unit of analysis makes the problem measurable?
3. Which baseline would you use to avoid a naive reading?
4. Which typical mistake could change the conclusion?
5. Which output would you deliver to a non-technical stakeholder?

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.

Quality control

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.

Operational example

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.

Work checkpoint

• 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

Mastery summary

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.