AI per data engineering, mapping e documentazione

Nel binario dei sistemi LLM, una delle applicazioni più concrete e meno spettacolari è questa: aiutare il data engineering a sapere cosa gira in produzione. Perché il lavoro sporco di questa disciplina non è addestrare modelli, è appunto sapere cosa gira: quale tabella alimenta quale dashboard, quale colonna significa davvero revenue, chi ha cambiato uno schema giovedì sera rompendo tre pipeline. Mapping e documentazione sono il sistema nervoso della piattaforma dati, e sono anche le attività che tutti rimandano perché costano tempo e non producono metriche vistose. L’AI generativa cambia l’economia di questo lavoro: produce bozze di mapping, descrizioni di colonne, contratti dati e runbook in minuti anziché giorni. Il problema si sposta dalla scrittura alla verifica, perché una documentazione plausibile ma sbagliata è peggio di nessuna documentazione.

Il principio guida

Questa lezione usa l’AI per generare mapping, descrizioni e contratti dati come bozze veloci, con il vincolo che ogni coppia passa da controlli SQL e ogni rilascio da un gate deterministico firmato da umani.

La sequenza di lavoro

Ecco il flusso completo, dall’input al rilascio.

1. Passa al modello schemi, righe campione anonimizzate, statistiche di cardinalità e vincoli noti, mai intere tabelle con dati personali.
2. Chiedi coppie in formato strutturato con trasformazione esplicita, confidenza e motivo, ordinate per rischio di verifica.
3. Verifica ogni coppia con query di controllo su match, nullità e cardinalità, segmentando per le dimensioni di business.
4. Genera descrizioni con unità di misura, fusi orari e definizioni condizionali, scrivendo segnaposto onesti dove il metadato tace.
5. Traduci il contratto in test eseguibili in integrazione continua e classifica ogni diff come bloccante, warning o informativo.
6. Rilascia solo con matrice di mapping firmata, contratto attivo, runbook di rollback e monitoraggio di copertura e falsi allarmi.

Perché mapping e documentazione marciscono sempre

Ogni data team conosce la dinamica: la pipeline nasce documentata, poi arrivano urgenze, migrazioni, colonne aggiunte “solo per questa campagna” e mai rimosse. Dopo sei mesi nessuno sa più se user_id nella tabella eventi coincida con id nella tabella utenti, se i timestamp siano in UTC o in ora locale, se quel campo status abbia tre o sette valori possibili. Il costo non è estetico: ogni ambiguità diventa un bug a valle, una dashboard che mente, un modello addestrato su una colonna con semantica diversa da quella creduta.

Il mapping è il punto più fragile. Collegare due schemi richiede di capire tipi, cardinalità, distribuzioni e semantica di business, non solo nomi simili. customer_code e client_id potrebbero essere la stessa chiave con nomi diversi, oppure due identificatori diversi che coincidono nel 98% dei casi e divergono proprio sui clienti enterprise che contano di più. L’AI è brava a proporre candidati — confronta nomi, tipi, campioni di valori, descrizioni — ma non conosce le convenzioni locali. Non sa che in azienda “cliente attivo” esclude i trial mentre nel CRM li include, a meno che qualcuno glielo dica.

La documentazione marcisce per un motivo economico preciso: scriverla costa subito, il beneficio arriva dopo e va a qualcun altro, tipicamente il collega che farà onboarding tra sei mesi. L’AI abbatte il costo di prima stesura quasi a zero, quindi rimuove la scusa principale. Quello che resta è il costo di verifica, che va progettato: chi conferma che la descrizione generata sia corretta, con quale evidenza, e cosa succede quando schema e documentazione divergono.

Cosa delegare all’AI e cosa tenere sotto controllo umano

La regola operativa è separare generazione da decisione. L’AI genera candidati, l’umano con contesto di dominio decide. Concretamente: l’AI propone mapping tra colonne, bozze di descrizioni, scheletri di contratti dati e di test di qualità; il data engineer conferma tipi, chiavi, vincoli e semantica; il domain owner conferma il significato di business.

Attività	Ruolo dell’AI	Controllo umano obbligatorio
Proposta di mapping tra schemi	Candidati ordinati per confidenza con motivazione	Verifica su cardinalità, null rate, valori distinti
Descrizione di tabelle e colonne	Bozza da DDL + statistiche + campioni	Firma del domain owner sulla semantica
Generazione di test di qualità	Scheletro di test da vincoli dichiarati	Soglie e severità decise dal team
Contratti dati e changelog	Prima stesura da diff di schema	Approvazione prima del deploy
Runbook e lineage narrative	Sintesi da metadati e log incidenti	Verifica contro incidenti reali

Il confine si sposta quando il rischio sale. Un mapping proposto per una tabella di staging usa e getta può passare con un controllo automatico; lo stesso mapping verso la tabella che alimenta la fatturazione richiede review umana e test bloccanti. Definire in anticipo queste fasce — cosa passa da solo, cosa richiede approvazione, cosa è vietato automatizzare — è la parte di governance che distingue un workflow maturo da un esperimento.

Come far proporre mapping all’AI senza farsi ingannare

Un buon prompt di mapping non contiene solo i due schemi. Contiene DDL sorgente e target, una decina di righe campione anonimizzate per tabella, le statistiche che contano — conteggio righe, percentuale di null, numero di valori distinti per le colonne candidate a chiave — e i vincoli noti, come chiavi primarie ed esterne già dichiarate. Senza questi elementi il modello mappa per assonanza di nomi, che è esattamente il modo in cui nascono i bug silenziosi.

La risposta va chiesta in formato strutturato: per ogni coppia proposta, colonna sorgente, colonna target, tipo di trasformazione necessaria (cast, trim, upper, conversione timezone, lookup), livello di confidenza e motivo. La confidenza non è una garanzia, serve a ordinare il lavoro di verifica: prima le coppie dubbie ad alto impatto, poi il resto. Le trasformazioni vanno richieste esplicite perché un mapping “ovvio” tipo stringa verso data nasconde sempre una decisione sul formato.

La verifica è SQL, non lettura. Ogni coppia candidata diventa una query di controllo: quanti valori della sorgente non trovano corrispondenza nel target, qual è il tasso di null dopo il join, la cardinalità è quella attesa uno-a-molti o emergono duplicati imprevisti. La copertura del mapping è la quota di valori sorgente mappati, corretta per il tasso di null a target. Può sembrare ottima al 99% finché non scopri che l’1% mancante sono tutti i clienti a maggior fatturato: il loro codice contiene un prefisso legacy che la regola di trasformazione non gestiva. Per questo i controlli vanno sempre segmentati per le dimensioni di business rilevanti, non solo calcolati in aggregato.

-- Verifica di un mapping candidato: cliente sorgente -> dimensione cliente
-- Commenti in italiano: ogni controllo risponde a una domanda precisa.
SELECT
    COUNT(*) AS righe_sorgente, -- quante righe stiamo mappando
    COUNT(c.client_id) AS match_trovati, -- quante trovano il target
    -- Tasso di match: sotto 0.995 su chiavi business si blocca il rilascio
    ROUND(COUNT(c.client_id) * 1.0 / NULLIF(COUNT(*), 0), 4) AS tasso_match,
    COUNT(DISTINCT s.customer_code) AS distinti_sorgente, -- cardinalita' attesa
    COUNT(DISTINCT c.client_id) AS distinti_target
FROM staging_clienti s
LEFT JOIN dim_cliente c
    -- La regola proposta dall'AI: normalizza spazi e maiuscole prima del join
    ON TRIM(UPPER(s.customer_code)) = TRIM(UPPER(c.client_id))
WHERE s.customer_code IS NOT NULL;

Se il tasso di match è basso, il passo successivo non è forzare la regola ma campionare i non-matchati: dieci righe lette a occhio rivelano più della millesima iterazione sul prompt. Pattern tipici sono prefissi legacy, zeri iniziali persi in un passaggio per Excel, codici riciclati dopo una migrazione CRM.

Generare documentazione che resta vera

La documentazione generata una volta e mai aggiornata è decorazione. Quella utile vive accanto al codice e viene rigenerata o verificata a ogni cambio di schema. Lo stack moderno lo permette: descrittori di colonne nel DDL o in file YAML versionati, generatori di docs da dbt o da cataloghi come DataHub e OpenMetadata, test che falliscono quando la realtà diverge dalla descrizione.

Il flusso pratico è questo: l’AI legge DDL, statistiche di profilazione e qualche riga campione e produce una prima stesura di descrizione per tabella e colonna, più i test di qualità suggeriti. Il data engineer corregge la semantica — cosa significa “attivo”, in che timezone è il timestamp, qual è l’unità di misura — e il domain owner conferma. Da lì in poi descrizione e test viaggiano insieme: se un test fallisce, o è rotto il dato o è obsoleta la descrizione, e in entrambi i casi c’è qualcosa da sistemare.

# Estratto di schema.yml stile dbt: descrizioni + test viaggiano insieme.
# L'AI produce la bozza, il team firma semantica e soglie.
models:
  - name: dim_cliente
    description: "Anagrafica clienti deduplicata, una riga per cliente. Sorgente: CRM, snapshot giornaliero."
    columns:
      - name: client_id
        description: "Chiave primaria, codice CRM normalizzato in maiuscolo senza spazi."
        tests:
          - unique # fallisce se la deduplica si rompe
          - not_null # fallisce se la chiave manca: blocco deploy
      - name: segmento
        description: "Segmento commerciale. Valori ammessi: enterprise, smb, trial. I trial sono esclusi dal fatturato."
        tests:
          - accepted_values:
              values: ['enterprise', 'smb', 'trial']

Il dettaglio che fa la differenza sono le unità di misura, i fusi orari e le definizioni condizionali scritte per esteso. “Revenue in euro, IVA esclusa, snapshot giornaliero alle 06:00 UTC” previene una classe intera di dispute tra team. Quando l’AI genera queste righe, va istruita a non inventare: se l’unità non è deducibile dai metadati, deve scrivere unita_misura: sconosciuta — da confermare invece di tirare a indovinare. Un segnaposto onesto vale più di una certezza falsa.

Contratti dati: dove la bozza dell’AI incontra il blocco del deploy

Il contratto dati è l’accordo esplicito tra chi produce una tabella e chi la consuma: schema, tipi, vincoli, freschezza attesa, semantica. Senza contratto, ogni cambio di schema a monte è un incidente a valle scoperto il lunedì mattina. Con un contratto testuale generato dall’AI e verificato in CI, il cambio schema rompe la build prima di rompere la dashboard.

Far scrivere la prima stesura all’AI è efficiente: gli passi il DDL attuale, il diff rispetto alla versione precedente e la lista dei consumer noti, e chiedi un contratto con clausole verificabili — non prosa, ma asserzioni. Ogni clausola deve tradursi in un test eseguibile: riga per chiave, freschezza massima 26 ore, nessun valore fuori lista. Le clausole non verificabili come “dati di alta qualità” vanno riscritte o eliminate, perché danno un’illusione di protezione senza protezione reale.

# Controllo di contratto eseguibile in CI: fallisce la build se violato.
# Ogni asserzione corrisponde a una clausola del contratto dati.
import pandas as pd

def verifica_contratto(df: pd.DataFrame) -> list[str]:
    """Restituisce la lista delle violazioni; lista vuota = contratto rispettato."""
    violazioni = []
    # Clausola 1: la chiave primaria non ammette duplicati ne' null
    if df["client_id"].isna().any():
        violazioni.append("client_id contiene NULL")
    if df["client_id"].duplicated().any():
        violazioni.append("client_id contiene duplicati")
    # Clausola 2: dominio chiuso sul segmento
    ammessi = {"enterprise", "smb", "trial"}
    fuori = set(df["segmento"].dropna().unique()) - ammessi
    if fuori:
        violazioni.append(f"segmento con valori imprevisti: {fuori}")
    # Clausola 3: freschezza dello snapshot
    ritardo_ore = (pd.Timestamp.now(tz="UTC") - df["snapshot_ts"].max()).total_seconds() / 3600
    if ritardo_ore > 26:  # soglia decisa dal team, non dal modello
        violazioni.append(f"snapshot vecchio di {ritardo_ore:.1f} ore")
    return violazioni

La validazione che blocca il rilascio è sempre una combinazione di controlli automatici e una firma umana sui cambi breaking: rimozione di colonne, cambi di tipo, ridefinizioni semantiche. L’AI può classificare un diff come breaking o non-breaking, ma la decisione di procedere con un breaking change resta del producer insieme ai consumer impattati. Automatizzare anche quella firma significa scoprire l’impatto dai ticket di protesta.

Lineage e runbook: la memoria che serve durante l’incidente

Alle tre di notte, quando la dashboard del fatturato è vuota, nessuno legge un saggio sulla piattaforma dati. Servono due cose: da dove viene questo numero, passo per passo, e cosa faccio adesso. Il lineage risponde alla prima domanda, il runbook alla seconda, e l’AI può tenere aggiornati entrambi se alimentata dai metadati giusti.

Il lineage narrativo si genera dal grafo delle dipendenze — quello che dbt, Airflow o il catalogo già conoscono — tradotto in prosa leggibile: questa dashboard legge queste tre tabelle, che derivano da queste sorgenti, con queste trasformazioni in mezzo. Il valore dell’AI sta nella traduzione, non nell’invenzione: deve attenersi al grafo reale e segnalare i tratti incerti, come una tabella scritta da un job esterno all’orchestratore che il lineage automatico non vede. Un lineage che omette un passaggio è una mappa con un ponte mancante.

I runbook generati dall’AI funzionano se ancorati agli incidenti passati: sintomi osservati, query diagnostiche che hanno aiutato davvero, fix che hanno funzionato e quelli che hanno peggiorato le cose. La struttura che regge è sintomo, diagnosi in ordine di probabilità, comandi pronti da copiare, criteri di escalation. Il controllo di qualità è brutale e semplice: al prossimo incidente, il runbook ha ridotto il tempo di risoluzione oppure no. Se dopo due incidenti nessuno l’ha aperto, va riscritto, non pubblicizzato.

La validazione tecnica che deve bloccare il rilascio

Non tutti i controlli sono uguali: alcuni segnalano, altri fermano tutto. La distinzione va decisa prima, non durante l’incidente, e scritta in un posto che la CI legge davvero. Un modello di severità pragmatico ha tre fasce: i controlli bloccanti fermano il deploy — chiavi duplicate, colonne rimosse, violazioni di vincoli referenziali sulle tabelle critiche; i controlli di warning richiedono un ack motivato — calo di volumi oltre soglia, deriva distribuzionale sospetta; i controlli informativi alimentano dashboard senza fermare nessuno.

Per le tabelle critiche, il gate minimo prima del rilascio combina cinque verifiche: lo schema corrisponde al contratto, i test di unicità e non-nullità sulle chiavi passano, i volumi sono entro una banda storica ragionevole, la freschezza rispetta l’SLA, e un confronto riga-per-riga su un campione tra vecchia e nuova versione del mapping non mostra divergenze inspiegate. La banda sui volumi merita attenzione: una soglia tipo ±15% rispetto alla mediana mobile a sette giorni cattura i crolli senza bloccarsi ogni lunedì per la stagionalità settimanale. Chi imposta soglie senza guardare la storia della tabella colleziona falsi allarmi finché il team non inizia a ignorarli tutti, compresi quelli veri.

Il ruolo dell’AI in questo quadro è di assistente al gate, non di gate: riassume i risultati dei test in un report leggibile, suggerisce se un fallimento sembra sistematico o rumore, propone la query di approfondimento. Ma l’esito pass-fail resta determinato da regole deterministiche versionate, non da un giudizio probabilistico. Affidare a un modello la decisione “si può rilasciare” significa introdurre nel punto più delicato della pipeline esattamente la componente meno riproducibile.

Quando il metodo non funziona: limiti, privacy e costi

L’AI applicata a mapping e documentazione ha modi di fallire specifici che vanno conosciuti prima di fidarsi. Il primo è l’allucinazione di semantica: descrizioni sicure e dettagliate di colonne che il modello non può davvero conoscere, come una colonna flag_vip descritta come “indica clienti VIP” quando in realtà indica un vecchio programma fedeltà dismesso. Il secondo è il mapping per assonanza su domini diversi: due colonne amount mappate tra loro quando una è in centesimi e l’altra in euro, con un fattore 100 di errore che nessun test di tipo intercetterà. Il terzo è la deriva silenziosa: documentazione corretta al giorno uno che nessuno rigenera, finché non mente con autorevolezza.

La privacy è il vincolo che morde prima degli altri. Schemi, campioni di righe e statistiche inviati a un modello esterno possono contenere dati personali o comunque sensibili: email nei valori campione, codici fiscali nelle chiavi, note libere con nomi di clienti. Le contromisure sono ordinarie ingegneria — anonimizzazione e mascheramento prima dell’invio, campionamento ragionato invece di dump integrali, preferenza per modelli deployati nel perimetro aziendale quando si lavora su schemi core — ma vanno applicate sistematicamente, non a discrezione del singolo. Una regola semplice: nessun valore grezzo di colonna identificativa esce dal perimetro; solo hash, pattern o statistiche aggregate.

Poi c’è il conto economico. Generare documentazione per migliaia di tabelle con chiamate a modelli grandi costa, e rigenerarla a ogni commit senza strategia costa molto di più. La pratica sensata è rigenerare solo i diff — descrivere ciò che è cambiato — tenere in cache le descrizioni stabili e riservare i modelli costosi alla prima stesura, usando controlli deterministici per la sorveglianza continua. Misurare il costo per tabella documentata e confrontarlo con il tempo di onboarding risparmiato o gli incidenti evitati trasforma la discussione da entusiasmo a decisione.

Una migrazione CRM dall’inizio alla fine

Il caso che mette insieme tutti i pezzi è la migrazione tra due CRM, lo scenario classico dove mapping e documentazione decidono se il cutover è un non-evento o una settimana di rollback. Il punto di partenza è l’inventario: tabelle e colonne sorgente, DDL target, statistiche di profilazione su entrambi i lati, lista dei consumer a valle con le loro query critiche. L’AI produce da questo materiale la matrice di mapping iniziale — per ogni campo target, campo sorgente candidato, trasformazione e confidenza — più la prima stesura del contratto dati e dei test.

Poi inizia il lavoro vero, che è verifica. I controlli di cardinalità rivelano vincoli diversi tra i due sistemi — per esempio più indirizzi per cliente da un lato contro uno solo dall’altro — e serve una regola di deduplica con priorità dichiarata. I campioni di non-match mostrano prefissi legacy e codici riciclati. Il confronto dei volumi segmentati per paese rivela le sorgenti dimenticate, come istanze separate mai menzionate. Nessuno di questi problemi è visibile nella matrice iniziale; tutti emergono dai controlli che la matrice ha ordinato per priorità.

Al cutover si arriva con artefatti precisi: matrice di mapping firmata con le eccezioni note, contratto dati attivo in CI, runbook di rollback con il punto di non ritorno dichiarato, lineage aggiornato che mostra ai consumer cosa è cambiato. Durante il parallelo pre-cutover, vecchia e nuova pipeline girano insieme e le discrepanze oltre soglia bloccano invece di stupire. L’AI in questa fase fa il lavoro di sintesi — report giornalieri di confronto, classificazione delle discrepanze, bozze di comunicazioni agli stakeholder — mentre le decisioni di procedere restano firmate da umani con nome e cognome.

Capire se il sistema regge: segnali da monitorare

Un programma di mapping e documentazione assistito dall’AI si valuta su quattro segnali, nessuno dei quali è “pagine di documentazione prodotte”. La copertura documentale — quota di tabelle critiche con descrizione verificata e owner dichiarato — misura l’ampiezza. Il tasso di incidenti causati da semantica fraintesa misura se la documentazione è vera o decorativa: deve scendere, altrimenti si sta producendo testo inutile. Il tempo di onboarding di un nuovo arrivato fino alla prima PR autonoma misura se la documentazione serve a qualcuno. Il tempo medio di diagnosi durante gli incidenti misura se lineage e runbook funzionano quando conta.

Due metriche di guardia completano il quadro: la quota di descrizioni rigenerate o confermate negli ultimi novanta giorni, che segnala documentazione viva contro documentazione fossile, e il tasso di falsi allarmi dei gate, che segnala soglie da ricalibrare prima che il team impari a bypassarle. Se la copertura sale ma gli incidenti semantici restano fermi, il problema è quasi sempre la verifica: descrizioni generate e mai lette da chi conosce il dominio. La correzione non è generare di più, è portare il domain owner nel flusso di firma, anche a costo di rallentare la produzione di pagine.

Riferimenti per approfondire: la documentazione di dbt su contratti e test è il punto di partenza operativo per rendere la documentazione eseguibile; OpenMetadata e DataHub mostrano come lineage e glossari si integrano nei cataloghi reali; le guide su great expectations e affini coprono la scrittura di controlli dichiarativi; per i vincoli di privacy sui dati inviati a modelli esterni, il riferimento resta il GDPR con le linee guida del Garante sulla minimizzazione. Da usare per verificare terminologia e limiti prima di disegnare workflow reali, non come ricette da copiare.

Verdetto: il modello propone mapping e testi, le regole deterministiche decidono il rilascio, gli umani firmano i cambi che rompono.

Il crollo di Knight Capital

Il primo agosto 2012 la società di trading Knight Capital perse 440 milioni di dollari in 45 minuti per un deploy manuale che riattivò codice obsoleto su alcuni server. Nessun gate automatico bloccò il rilascio incoerente e nessun controllo fermò le esecuzioni anomale. È il caso estremo di ciò che insegna questa lezione: il rilascio in produzione si governa con contratti verificati e controlli bloccanti, mai con la fiducia nel processo manuale.

Domande per chiudere la lezione

1. Cosa deve contenere un prompt di mapping perché il modello non mappi per assonanza di nomi?
2. Quale query rivela un mapping che perde proprio i clienti a maggior valore?
3. Quando una clausola del contratto dati merita di bloccare il deploy e quando basta un avviso?
4. Quali valori non escono mai dal perimetro verso un modello esterno?