Cheat Sheet — Analytics Engineering con dbt

Quando un progetto dbt cresce, i problemi arrivano sempre dagli stessi punti: naming incerto, test deboli, modelli troppo pesanti, lineage poco chiaro e metriche definite in più posti. Cheat Sheet - Analytics Engineering con dbt raccoglie le regole pratiche da controllare prima che il debito diventi operativo.

Una scena da cui partire

Usa questa pagina come checklist di manutenzione. Torna qui quando devi revisionare un modello, preparare una PR, scegliere una materialization o capire se un mart è davvero pronto per essere riusato.

• Contesto: Quale regola serve sotto pressione?
• Metodo: Quale eccezione non devi dimenticare?
• Applicazione: Quale checklist useresti domani in un progetto reale?

I quattro comandi che userai ogni giorno

dbt build                    # run + test + seed + snapshot, tutto insieme
dbt build --select state:modified+ --defer --state ./target/   # CI: solo modificati
dbt docs generate            # genera documentazione e lineage graph
dbt source freshness         # verifica che i dati sorgente siano aggiornati

La matrice delle materializzazioni

Strategia	Quando	Comando/config
view	Staging, modelli <1M righe	+materialized: view
table	Intermediate, marts <100M righe	+materialized: table
incremental	Event stream >100M righe, append-only	materialized='incremental' + is_incremental()
ephemeral	CTE leggere, mai referenziate direttamente	+materialized: ephemeral
snapshot	SCD Type-2, stato cliente nel tempo	snapshots/ folder, strategy: timestamp o check

La checklist di code review (PR template)

## dbt PR Checklist
- [ ] Naming: dal nome si capiscono layer, dominio e granularità?
- [ ] Layer: staging non ha JOIN, marts non hanno CASE WHEN di business
- [ ] Granularità: una riga di questo modello rappresenta esattamente cosa?
- [ ] Test: unique + not_null su PK, accepted_values su enum, relationships su FK
- [ ] Documentazione: YAML con description per ogni colonna
- [ ] Performance: filtri sulle date? incremental dove serve? niente SELECT *?
- [ ] DAG: la PR non introduce cicli o dipendenze nascoste?
- [ ] Owner: chi risponde se questo modello si rompe in produzione?

Pattern Jinja da ricordare

-- Filtro condizionale per incremental
{% if is_incremental() %}
WHERE event_time > (SELECT MAX(event_time) FROM {{ this }})
{% endif %}

-- Adattare logica all'ambiente
{% if target.name == 'prod' %}
WHERE is_test = FALSE
{% endif %}

-- Ciclare su una lista
{% for country in ['IT', 'FR', 'DE'] %}
SUM(CASE WHEN country = '{{ country }}' THEN revenue END) AS revenue_{{ country }},
{% endfor %}

Gerarchia decisionale per l’ottimizzazione

1. Riduci i dati letti (filtri date, colonne specifiche) — impatto 10-100x
2. Pre-aggrega prima dei JOIN — impatto 2-10x
3. Sfrutta indici/clustering del warehouse — impatto 2-5x
4. Scegli la materialization giusta — impatto variabile

Il flusso di deployment

feature branch → PR → CI (dbt build --select state:modified+) → review → merge
→ staging build → validazione 24h → production build → monitoraggio

Se qualcosa si rompe: Git revert + dbt run in produzione, oppure time-travel del warehouse, oppure blue-green swap.

Caso concreto: da dashboard rotta a fix in 3 passi

Un team marketing crea marketing_output, una tabella letta dal board. Funziona per due mesi, poi nessuno sa più che cosa contiene. Ecco cosa correggere:

Problema	Correzione	Comando/Config
Nome generico	mrt_marketing__channel_efficiency_daily	Rinomina file e modello
Granularità implicita	Documenta: una riga = giorno × canale	YAML description
Nessun test	Aggiungi not_null, unique, relationships, accepted_values	models/marts/marketing.yml
Metrica solo in BI	Sposta la definizione nel semantic layer	metrics: channel_efficiency
Nessun owner	Aggiungi meta: { owner: "@marketing-data" }	YAML meta field

La differenza non è estetica. È operativa: il modello diventa difendibile, trovabile, e riparabile in minuti invece che in ore.

Anti-pattern da evitare sempre

• Staging che fa JOIN → la logica va in intermediate
• Marts che contengono CASE WHEN di business → la logica va in intermediate
• SELECT * su tabelle partizionate senza filtro data → è un warning di performance
• Modello chiamato final, v2, new → il nome deve descrivere il contenuto, non lo stato
• Metrica calcolata in 3 dashboard diverse → va nel semantic layer
• Snapshot eseguiti una volta al giorno con dati che cambiano più spesso → perdi cambiamenti intra-day

Lab rapido: verifica lo stato del tuo progetto

Livello base: Prendi tre modelli dbt a caso. Riesci a dire layer, dominio e granularità di ciascuno in 10 secondi? Se no, il naming e la documentazione vanno migliorati.

Livello intermedio: Esegui dbt test su tutto il progetto. Quanti test falliscono? Quanti modelli non hanno alcun test? Aggiungi almeno not_null sui primi 5 modelli senza test.

Livello research-grade: Trova una metrica duplicata in BI (es. “conversion rate” calcolato in Tableau E in Looker con logiche diverse). Progetta il percorso per portarla in un unico modello intermediate o semantic layer.

Riepilogo operativo

Un buon progetto dbt non è solo query che girano. È struttura chiara, quality verificabile, metriche riusabili, ownership esplicita e deploy prevedibile. Quando hai dubbi, torna a questa checklist. Se nome, granularità, test, lineage e owner sono chiari, il progetto resta gestibile anche con 500 modelli e 20 contributori.

Problema reale

Nel dominio di analytics engineering, Cheat Sheet - Analytics Engineering con dbt serve a risolvere questo problema: trasformare dati grezzi in modelli testati, documentati e riusabili dal business. La lezione non va trattata come teoria isolata, ma come un modo per migliorare una scelta concreta con dati, assunzioni esplicite e controlli minimi.

Obiettivo operativo: Comprendere il problema analitico e il contesto decisionale; Applicare esempi, metriche e controlli a casi reali. Se alla fine non sai indicare quale decisione cambia, quale dato osservi e quale errore vuoi evitare, la lezione non è ancora diventata competenza applicata.

Modello concettuale

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

Il modello concettuale è intenzionalmente semplice: decisione, dato, controllo, azione. Ogni approfondimento tecnico deve rafforzare almeno uno di questi quattro punti.

Formalizzazione rigorosa

Per rendere Cheat Sheet - Analytics Engineering con dbt analizzabile, definisci prima l’unità di lavoro: source, model, test, mart, metrica o esposizione. Poi collega questa unità a una metrica osservabile: freshness, lineage, test coverage, costo modello e fiducia stakeholder. Infine dichiara la decisione attesa: modello dbt, semantic layer, contratto, test o pipeline di release.

Elemento	Specifica richiesta
Unità di analisi	source, model, test, mart, metrica o esposizione
Segnale principale	freshness, lineage, test coverage, costo modello e fiducia stakeholder
Baseline	Periodo precedente, gruppo comparabile, benchmark o scenario controfattuale
Decisione	modello dbt, semantic layer, contratto, test o pipeline di release
Rischio	Scambiare un numero disponibile per una prova sufficiente

La formalizzazione e solida quando un altro analista può riprodurre la logica, criticare le assunzioni e ottenere la stessa decisione partendo dagli stessi dati.

Esempio o caso studio

Prima di mergiare una PR dbt, la cheat sheet guida una review rapida: naming coerente, source dichiarate, test minimi, materialization giustificata, lineage leggibile e impatto su dashboard note. Il valore è evitare che una piccola modifica diventi debito tecnico permanente.

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à

Lab / esercizio

Livello base

Scrivi una scheda di una pagina per Cheat Sheet - Analytics Engineering con dbt: decisione da supportare, metrica primaria, baseline, rischio principale e azione se il segnale e confermato.

Livello intermedio

Costruisci una tabella con tre segmenti, periodi o scenari. Per ciascuno indica cosa cambia, quale spiegazione alternativa e plausibile e quale controllo useresti prima di raccomandare un azione.

Livello research-grade

Prepara un decision memo: ipotesi, dati richiesti, criteri di esclusione, controlli di qualità, soglia decisionale, rischio residuo e piano di monitoraggio dopo la decisione.

Dataset e materiali consigliati

Usa dbt, warehouse, sorgenti CRM, eventi, marts, semantic layer e lineage. Se non hai accesso a dati reali, crea un dataset sintetico con almeno 200 righe, una dimensione temporale, una dimensione segmento e una metrica di outcome.

Errore tipico da evitare

L’errore più comune e usare Cheat Sheet - Analytics Engineering con dbt come etichetta invece che come processo. Succede quando il team mostra un grafico senza decisione, una metrica senza baseline, o una conclusione senza indicare quale assunzione potrebbe invalidarla.

La domanda di controllo è: se questo risultato fosse instabile, quale scelta sbaglierei? Se la risposta non è concreta, manca ancora il collegamento tra analisi e azione.

Quiz o checkpoint

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 operativo

Cheat Sheet - Analytics Engineering con dbt diventa utile quando produce una decisione più chiara, non quando aggiunge terminologia. Usa il framework problema, modello, formalizzazione, esempio, lab e checkpoint per trasformare la lezione in pratica verificabile. Categoria: Sintesi Operativa. Difficoltà: advanced. Tempo stimato: 10 min.

Approfondimento di pratica

Per consolidare Cheat Sheet - Analytics Engineering con dbt, trattala come una piccola prova di lavoro dentro un progetto dbt o semantic layer in cui una metrica deve diventare affidabile per altri team. Non basta dire di aver capito la lezione: devi produrre un modello dati testato, documentato e accompagnato da ownership chiara. Questo passaggio serve a rendere la conoscenza trasferibile, perché obbliga a separare contesto, misura, azione e limite.

Esempio operativo

Parti da una domanda semplice: quale scelta diventerebbe migliore se applicassi bene questa lezione? Nel modulo analytics engineering, la risposta deve sempre collegare un problema reale a un output osservabile. Se stai studiando una lezione di tipo Sintesi Operativa, costruisci un esempio con tre righe: il contesto in cui nasce la domanda, il dato o il modello che useresti per leggerla, e la decisione che prenderesti dopo aver controllato i rischi.

Un esempio valido non deve essere grande. Può essere una tabella con una baseline e due segmenti, una query che verifica una definizione, un disegno di esperimento, un controllo su un modello o un memo di dieci righe. La qualità non dipende dalla complessità tecnica, ma dalla tracciabilità del ragionamento: chi legge deve capire perché hai scelto quella metrica, quale alternativa hai scartato e quale evidenza ti farebbe cambiare idea.

Checkpoint di lavoro

• Scrivi la decisione che questa lezione dovrebbe migliorare, usando un verbo operativo: allocare, fermare, correggere, lanciare, misurare, priorizzare o investigare.
• Definisci il segnale principale e almeno un guardrail. Il segnale dice dove guardi; il guardrail evita che una scelta localmente buona rovini il sistema.
• Aggiungi una baseline. Senza baseline non sai se il numero e alto, basso, stabile, anomalo o solo raccontato male.
• Esplicita il rischio più probabile: trasformare dati instabili in una tabella elegante ma non governabile. Scrivilo prima della raccomandazione, non dopo.
• Chiudi con un output consegnabile: dashboard, query, schema, memo, esperimento, notebook o checklist. Deve essere qualcosa che un reviewer possa aprire e criticare.

Riepilogo di padronanza

Hai davvero assimilato Cheat Sheet - Analytics Engineering con dbt quando riesci a usarla in tre modi: spiegare il concetto senza gergo inutile, applicarlo a un caso piccolo ma realistico, e difendere una raccomandazione includendo limiti e prossimi controlli. Se manca uno di questi tre elementi, torna al modello concettuale e riduci l’ambizione dell’esempio. Meglio una prova piccola ma rigorosa di un grande progetto che non rende verificabile la decisione.