Salta al contenuto principale

06 - Modern data stack: un'architettura minima con DuckDB e dbt

Un'architettura dati minima eseguita davvero: Parquet, DuckDB, dbt con test, pubblicazione protetta e timer di sistema, più i segnali per aggiungere altro.

Cosa ne pensi di questo articolo?

06 - Modern data stack: un'architettura minima con DuckDB e dbt
Data Engineering 2027Foto:Egor KomarovPexels

In Breve

Un'architettura dati minima eseguita davvero: Parquet, DuckDB, dbt con test, pubblicazione protetta e timer di sistema, più i segnali per aggiungere altro.

Quanto serve per mettere in piedi una pipeline dati affidabile? Meno di quanto dicono molte architetture di riferimento: file Parquet, DuckDB per interrogarli, dbt per trasformare e testare, e un pianificatore. Qui costruisci quell'architettura minima su un solo computer, la fai girare, e la metti alla prova con un caricamento difettoso per vedere che cosa la ferma. Poi vedi quando smette di bastare e che cosa aggiungere, un pezzo alla volta.

Prerequisiti. SQL e riga di comando; gli articoli precedenti della serie aiutano ma non sono obbligatori.

Che cosa significa "minimo"

Un'architettura minima non è quella con meno strumenti, ma quella in cui ogni pezzo risolve un problema che hai già. Il punto di partenza è un problema concreto: ogni notte arrivano file di ordini da un gestionale, e al mattino qualcuno vuole una tabella dei ricavi per giorno e paese di cui fidarsi. Ne discendono cinque compiti, e per ciascuno scelgo lo strumento più semplice che lo svolge.

  • conservare i dati grezzi senza modificarli: file Parquet, una cartella per giorno;
  • interrogarli e trasformarli: DuckDB, che legge direttamente quei file;
  • decidere se il risultato è affidabile: i test di dbt, eseguiti prima di pubblicare;
  • pubblicare il risultato: un file Parquet che i consumatori leggono;
  • far partire tutto ogni notte: un timer di sistema, finché non serve altro.

L'ordine qui conta: i dati grezzi vengono prima perché sono l'unica cosa irrecuperabile, la pubblicazione viene dopo i test perché è l'unica cosa che vedono gli altri. Sono tutti pezzi che gli articoli precedenti della serie trattano uno per uno (DuckDB, DuckDB con Polars, i formati di tabella, lakeFS); qui li compongo.

Versioni, licenze e una novità su dbt

Gli strumenti usati, alla data di consultazione 2026-11-13: DuckDB 2.0.0 (MIT), dbt Core 1.12.7 con l'adattatore dbt-duckdb 1.11.1, tutti installati con pip in ambienti virtuali. Prima di copiare i comandi leggi una novità: pip install dbt installa oggi dbt v2, una riscrittura in Rust descritta nella documentazione come l'esperienza corrente, il cui codice sorgente è sotto Apache 2.0 mentre la distribuzione che installi è rilasciata con una licenza di prodotto di dbt, presentata come gratuita da usare. La versione 1 (Python) continua a esistere nel ramo 1.latest. In questo articolo ho usato dbt Core 1.12.7, la versione 1, perché l'adattatore dbt-duckdb dichiara nel suo README di puntare a dbt-core dalla 1.8 in poi; se lavori con la v2, verifica prima che l'adattatore per DuckDB sia supportato.

Il punto pratico è che "dbt" non indica più un solo prodotto: scrivi nel progetto quale versione usi e blocca la versione nei requisiti. Lo stesso vale per qualunque pezzo dello stack, e la lezione sulla licenza di lakeFS nell'articolo precedente è dello stesso tipo.

Il livello grezzo: file immutabili, uno per giorno

Lo script crea 5 giorni di ordini (20.000 righe al giorno) e un'anagrafica di 2.000 clienti, con valori derivati dall'indice di riga tramite hash() perché siano uguali a ogni esecuzione. La struttura è raw/ordini/giorno=2026-11-0N/ordini.parquet: la cartella si chiama come la colonna di partizione, così DuckDB la legge da sola. Una regola da copiare: un caricamento aggiunge una cartella nuova e non modifica mai le vecchie.

import pathlib, shutil
import duckdb

raw = pathlib.Path("mva/raw")
shutil.rmtree(raw, ignore_errors=True)
con = duckdb.connect()

# anagrafica clienti: 2.000 righe, sempre uguali
(raw / "clienti").mkdir(parents=True)
pathlib.Path("mva/out").mkdir(exist_ok=True)      # dbt-duckdb non crea la cartella dei file esterni
con.execute(f"""
    COPY (SELECT i AS cliente_id,
                 (['IT','DE','FR','ES','NL'])[1 + (hash(i) % 5)::INT] AS paese
          FROM range(2000) t(i)) TO '{raw}/clienti/clienti.parquet' (FORMAT parquet)""")

# ordini: un file per giorno, come li lascerebbe un job di ingestione notturno
for giorno in range(1, 6):
    cartella = raw / "ordini" / f"giorno=2026-11-0{giorno}"
    cartella.mkdir(parents=True)
    con.execute(f"""
        COPY (SELECT {giorno} * 100000 + i AS order_id,
                     (hash(i * {giorno}) % 2000)::INT AS cliente_id,
                     round(((hash(i + {giorno} * 7) % 20000) / 100.0)::DOUBLE, 2) + 1 AS importo
              FROM range(20000) t(i)) TO '{cartella}/ordini.parquet' (FORMAT parquet)""")

n = con.execute(f"SELECT count(*), count(DISTINCT order_id) FROM read_parquet('{raw}/ordini/*/*.parquet')").fetchall()[0]
print("file di ordini:", len(list(raw.glob("ordini/*/*.parquet"))), "| righe:", n[0], "| order_id distinti:", n[1])
print("clienti:", con.execute(f"SELECT count(*) FROM '{raw}/clienti/clienti.parquet'").fetchall()[0][0])

# Output:
# file di ordini: 5 | righe: 100000 | order_id distinti: 100000
# clienti: 2000

Le righe sono 100.000 e gli order_id distinti sono 100.000: i test di unicità che scriverai dopo partono da questo fatto. La cartella out/ per i file pubblicati si crea qui perché dbt-duckdb non la crea da sé: lo ha scoperto l'esecuzione, con un errore di file non trovato al primo tentativo.

Il progetto dbt: tre modelli e sei test

Il progetto è piccolo. Due modelli di staging (stg_ordini e stg_clienti) sono viste che leggono i Parquet con read_parquet e danno nomi e tipi puliti. Il modello finale ricavi_giornalieri unisce ordini e clienti e calcola gli ordini e i ricavi per giorno e paese; è dichiarato con materialized='external' e un location, che con l'adattatore dbt-duckdb scrive il risultato come file Parquet invece che come tabella nel database. I test stanno nel file YAML.

{{ config(materialized='external', location='out/ricavi_giornalieri.parquet') }}

select
    o.giorno,
    c.paese,
    count(*)                 as ordini,
    round(sum(o.importo), 2) as ricavi
from {{ ref('stg_ordini') }} o
join {{ ref('stg_clienti') }} c using (cliente_id)
group by o.giorno, c.paese

Il modello è una query SQL con un'intestazione di configurazione: ref('stg_ordini') dice a dbt da quali modelli dipende e quindi in che ordine eseguirli, e using (cliente_id) unisce le due tabelle sulla chiave. I test descrivono invece le regole sui dati e vivono accanto ai modelli, in un file YAML:

version: 2
models:
  - name: stg_ordini
    columns:
      - name: order_id
        data_tests: [not_null, unique]
      - name: cliente_id
        data_tests:
          - not_null
          - relationships:
              arguments: {to: ref('stg_clienti'), field: cliente_id}
      - name: importo
        data_tests: [not_null]
  - name: stg_clienti
    columns:
      - name: paese
        data_tests:
          - accepted_values: {arguments: {values: ['IT', 'DE', 'FR', 'ES', 'NL']}}

I test dicono che cosa significa "affidabile": l'identificativo dell'ordine c'è ed è unico, il cliente c'è ed esiste nell'anagrafica (relationships), l'importo c'è, il paese è fra i cinque ammessi. Nota la sintassi di relationships: gli argomenti stanno sotto la chiave arguments. Il mio primo tentativo li scriveva in linea, e dbt ha risposto con un avviso di deprecazione (MissingArgumentsPropertyInGenericTestDeprecation); la forma corretta è quella del file.

Una esecuzione completa

Il comando dbt build esegue modelli e test in ordine di dipendenza. Il listato lo lancia e ripulisce l'uscita di dbt da orari, tempi e numerazione, che cambiano a ogni esecuzione, poi controlla il risultato per conto proprio: il ricavo totale del file pubblicato deve coincidere con la somma degli importi nei file grezzi.

import duckdb
from dbtlib import dbt

codice, righe = dbt("build")
print("exit code di dbt build:", codice)
print("\n".join(righe))

# controllo incrociato: il ricavo del mart deve coincidere con la somma dei file grezzi
mart = duckdb.sql("SELECT count(*), round(sum(ricavi), 2) FROM 'mva/out/ricavi_giornalieri.parquet'").fetchall()[0]
grezzo = duckdb.sql("SELECT round(sum(importo), 2) FROM read_parquet('mva/raw/ordini/*/*.parquet')").fetchall()[0][0]
print("righe del mart:", mart[0], "| ricavi nel mart:", mart[1], "| somma nei file grezzi:", grezzo)

# Output:
# exit code di dbt build: 0
# Done. PASS=9 WARN=0 ERROR=0 SKIP=0 NO-OP=0 REUSED=0 TOTAL=9
# OK created sql external model main.ricavi_giornalieri  .. [OK]
# OK created sql view model main.stg_clienti  .. [OK]
# OK created sql view model main.stg_ordini  .. [OK]
# PASS accepted_values_stg_clienti_paese__IT__DE__FR__ES__NL  .. [PASS]
# PASS not_null_stg_ordini_cliente_id  .. [PASS]
# PASS not_null_stg_ordini_importo  .. [PASS]
# PASS not_null_stg_ordini_order_id  .. [PASS]
# PASS relationships_stg_ordini_cliente_id__cliente_id__ref_stg_clienti_ .. [PASS]
# PASS unique_stg_ordini_order_id  .. [PASS]
# righe del mart: 25 | ricavi nel mart: 10132463.4 | somma nei file grezzi: 10132463.4

Sono nove nodi tra viste, test e modello esterno, tutti passati, e il mart ha 25 righe: 5 giorni per 5 paesi. La somma dei ricavi (10.132.463,40) coincide con quella dei file grezzi, che è la verifica indipendente: un join sbagliato che perdesse o duplicasse ordini l'avrebbe rotta. I test di dbt controllano i dati in ingresso; il controllo incrociato controlla il risultato.

Il cancello: che cosa succede con dati cattivi

Una pipeline si giudica da come si comporta quando i dati sono sbagliati. Il listato aggiunge una cartella per un sesto giorno con tre righe difettose: un order_id già esistente, un cliente nullo, un cliente che non c'è nell'anagrafica. Poi rilancia dbt build e verifica un fatto che a un lettore può sfuggire: il file pubblicato è rimasto identico, byte per byte, confrontando una impronta SHA-256 prima e dopo. Alla fine il difetto viene ripulito.

import hashlib, pathlib, shutil
import duckdb
from dbtlib import dbt

mart = pathlib.Path("mva/out/ricavi_giornalieri.parquet")
impronta = lambda: hashlib.sha256(mart.read_bytes()).hexdigest()[:12]
prima = impronta()

# un caricamento difettoso: un order_id gia' visto, un cliente nullo, un cliente che non esiste
cattivo = pathlib.Path("mva/raw/ordini/giorno=2026-11-06")
cattivo.mkdir()
duckdb.sql(f"""COPY (SELECT * FROM (VALUES (100000, 5, 10.0), (600001, NULL, 20.0), (600002, 99999, 30.0))
                t(order_id, cliente_id, importo)) TO '{cattivo}/ordini.parquet' (FORMAT parquet)""")
try:
    codice, righe = dbt("build")
    print("exit code di dbt build:", codice)
    print("\n".join(r for r in righe if not r.startswith("PASS ")))
    print("il mart e' rimasto quello di prima:", impronta() == prima)
finally:
    shutil.rmtree(cattivo)                      # ripulisco il caricamento difettoso

# Output:
# exit code di dbt build: 1
# Done. PASS=5 WARN=0 ERROR=3 SKIP=1 NO-OP=0 REUSED=0 TOTAL=9
# FAIL 1 not_null_stg_ordini_cliente_id  .. [FAIL 1]
# FAIL 1 relationships_stg_ordini_cliente_id__cliente_id__ref_stg_clienti_ [FAIL 1]
# FAIL 1 unique_stg_ordini_order_id  .. [FAIL 1]
# OK created sql view model main.stg_clienti  .. [OK]
# OK created sql view model main.stg_ordini  .. [OK]
# SKIP relation main.ricavi_giornalieri  .. [SKIP]
# il mart e' rimasto quello di prima: True

Tre test falliscono (cliente nullo, relazione con l'anagrafica, unicità dell'identificativo), dbt esce con codice 1 e il modello ricavi_giornalieri viene saltato: SKIP. dbt conta i test falliti come ERROR nel riepilogo. È il comportamento che vuoi: i consumatori continuano a leggere il file di ieri, corretto ma datato, invece del file di oggi, aggiornato ma sbagliato. Un file vecchio e giusto è quasi sempre meglio di uno nuovo e sbagliato, e quasi sempre è meglio che qualcuno sappia della differenza: serve un avviso sul fallimento, che il timer da solo non dà.

Farlo partire ogni notte

Per un solo job giornaliero non serve un orchestratore: un'unit di systemd con il suo timer basta. La documentazione di systemd specifica che con Type=oneshot si possono dare più righe ExecStart=, eseguite in sequenza, e che Persistent=true fa recuperare un'esecuzione perduta se la macchina era spenta. Attenzione ai commenti: in un'unit file un commento va su una riga sua e non in coda a un valore. Sono due file, il servizio e il timer; non li ho installati, sono schemi da adattare.

# /etc/systemd/system/pipeline-dati.service  (schema da adattare, non eseguito: non ho installato nessuna unit)
[Unit]
Description=Pipeline dati notturna (ingestione e dbt build)

[Service]
Type=oneshot
User=pipeline
WorkingDirectory=/opt/pipeline
# se un comando fallisce, systemd segna l'unit come fallita e i successivi non partono
ExecStart=/opt/pipeline/venv/bin/python ingestione.py
ExecStart=/opt/pipeline/venv-dbt/bin/dbt build --profiles-dir . --no-version-check

Il servizio descrive che cosa eseguire: prima l'ingestione, poi dbt build, uno dopo l'altro, e se il primo fallisce il secondo non parte. Il timer descrive quando:

# /etc/systemd/system/pipeline-dati.timer
[Unit]
Description=Esegue la pipeline dati ogni notte

[Timer]
OnCalendar=*-*-* 02:00:00
# se la macchina era spenta alle 02:00, recupera all'avvio
Persistent=true

[Install]
WantedBy=timers.target

Il blocco seguente controlla l'unica parte verificabile senza installare nulla, l'espressione di OnCalendar, chiedendo a systemd-analyze calendar di interpretarla:

import subprocess

# systemd-analyze calendar interpreta l'espressione di OnCalendar senza avviare nulla
r = subprocess.run(["systemd-analyze", "calendar", "*-*-* 02:00:00"], capture_output=True, text=True)
print(r.stdout.splitlines()[0])

# Output:
# Normalized form: *-*-* 02:00:00

Il servizio dichiara un utente senza privilegi e una cartella di lavoro, per non scrivere dove non deve. Il fallimento di un comando fa fallire l'unit: l'avviso lo configuri a parte (una riga OnFailure= verso un'altra unit che invia la notifica, per esempio), perché il timer non scrive a nessuno. Un orchestratore serve quando i job diventano più d'uno e dipendono l'uno dall'altro.

Quando aggiungere un orchestratore, un formato di tabella, un versionamento

La risposta onesta è "quando ti serve la cosa che ti dà", non prima. Un orchestratore come Apache Airflow (3.4.0, Apache-2.0 su PyPI) o Kestra (edizione open source Apache-2.0, documentazione alla versione 2.0) porta ripetizione dei tentativi, dipendenze fra job, un'interfaccia che mostra che cosa è fallito e quando; costa un servizio in più da tenere vivo e aggiornare. Un formato di tabella come Iceberg o Delta porta commit atomici e viaggio nel tempo sulla tabella pubblicata. Un sistema come lakeFS porta rami e merge su tutto il lago, con la licenza e la gestione che l'articolo dedicato spiega.

Questo è l'elenco dei segnali che dicono "adesso serve", con il pezzo corrispondente, ma ogni voce è indipendente dalle altre:

  • più job con dipendenze o tentativi da ripetere: un orchestratore;
  • consumatori che leggono mentre scrivi e vedono file a metà: un formato di tabella;
  • bisogno di provare una trasformazione su una copia dei dati di produzione: rami, per esempio con lakeFS;
  • più processi che scrivono insieme sullo stesso database DuckDB: il vincolo del singolo scrittore descritto nell'articolo su DuckDB;
  • flussi continui o volumi che non entrano in una macchina: un altro motore, fuori da questa architettura.

Parti dal segnale che hai davvero e risolvilo con lo strumento più piccolo possibile. Per il secondo puoi provare prima a scrivere il file in una cartella temporanea e a rinominarlo a fine scrittura, prima di adottare un formato di tabella. Gli ultimi due sono limiti veri di questa architettura: se li incontri, ne hai superato il campo.

Che cosa non ho misurato

In questo articolo non c'è nessuna cifra di costo, di latenza o di quota di mercato: non le ho misurate e non le ho trovate in una fonte primaria. Il dato che puoi misurare tu, con gli stessi script, è il tempo di una esecuzione completa sul tuo hardware e sui tuoi volumi. Per il costo di un servizio gestito vale il listino del fornitore al giorno in cui decidi, non questo articolo.

Che cosa sai fare adesso

Sai montare una pipeline giornaliera con dati grezzi immutabili, trasformazioni e test in dbt, pubblicazione in Parquet e pianificazione con systemd; sai dimostrare che un caricamento difettoso non intacca il file pubblicato; sai quali segnali dicono che è ora di aggiungere un orchestratore, un formato di tabella o il versionamento; e sai che la v2 di dbt cambia la distribuzione e la licenza rispetto alla v1 usata qui.

Domande frequenti

Serve Airflow per una pipeline giornaliera?

Non per un job solo: un timer di sistema esegue il comando e dbt si ferma da sé quando un test fallisce. Airflow o Kestra servono quando i job sono più d'uno, hanno dipendenze o richiedono tentativi ripetuti e una interfaccia di controllo.

dbt funziona con DuckDB?

Sì, con l'adattatore dbt-duckdb: nell'articolo ho eseguito dbt Core 1.12.7 con dbt-duckdb 1.11.1 e DuckDB 2.0.0. Con dbt v2, oggi installato di default da pip install dbt, verifica il supporto dell'adattatore prima di passare.

Come mi accorgo che il caricamento notturno è fallito?

Il servizio systemd risulta fallito e dbt esce con codice 1, ma nessuno viene avvisato da solo. Aggiungi una notifica, per esempio con OnFailure= verso un'altra unit, e controlla anche la data dell'ultimo file pubblicato.

Questa architettura regge milioni di righe?

Nei test di questa serie ho usato da 100 mila a 20 milioni di righe su un computer con 12 thread logici e 30 GB di RAM, senza problemi. Oltre non ho misurato: il limite dipende da memoria, disco e concorrenza di scrittura, e va misurato sui tuoi dati.

Fonti

Gli script di ingestione, la build di dbt, il cancello e il controllo di OnCalendar sono stati eseguiti con Python 3.14.4, DuckDB 2.0.0, dbt Core 1.12.7 e dbt-duckdb 1.11.1, due volte con uscita identica dopo la normalizzazione descritta. I due file di unit systemd non sono stati installati né eseguiti. Dei file del progetto dbt i listati mostrano il modello finale ricavi_giornalieri e il file YAML dei test; i due modelli di staging (stg_ordini.sql e stg_clienti.sql), dbt_project.yml, profiles.yml e il modulo di appoggio dbtlib che gli script importano non sono mostrati e vanno creati da te.

Prova Questi Strumenti

Strumenti gratuiti correlati a questo argomento.

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti