Report di Validazione Pipeline ETL

Deliverable D2.3: Report di Validazione Pipeline ETL

[TODO] Questo capitolo sarà completato dopo la piena implementazione e il testing (Task 2.3, M10-M12)

Metodologia di validazione

Criteri di accettazione

Le pipeline ETL devono soddisfare cinque classi di criteri di accettazione. L'integrità temporale è il requisito principale per il layer di fondazione territoriale, poiché tutte le pipeline attributo dipendono dalla correttezza del grafo silver.territories.

Integrità temporale (pipeline di fondazione)

• Obiettivo: tutti i record territoriali in silver.territories e nelle tabelle correlate portano timestamp valid_from/valid_to validi derivati dagli eventi di variazione ISTAT; non esistono finestre temporali sovrapposte per la stessa entità; ogni entità attualmente attiva ha valid_to IS NULL
• Metrica: conteggio delle violazioni di integrità in territories, territory_identifiers, territory_names, territory_containments
• Soglia: PASS se 0 violazioni; FAIL in caso di qualsiasi violazione

Copertura

• Obiettivo: tutti i comuni italiani (7.904 al 2024) rappresentati in silver.territories con almeno un record attivo
• Metrica: (territori_con_record_attivo / totale_comuni_istat) × 100
• Soglia: FAIL se <99%, WARNING se 99–99,9%, PASS se 100%

Accuratezza

• Obiettivo: tutti i record in silver.territory_attributes portano un territory_id valido che risolve a una riga in silver.territories
• Metrica: (record_con_territory_id_valido / totale_record) × 100
• Soglia: FAIL se <99,9%

Tempestività

• Obiettivo: le pipeline di acquisizione completano l'esecuzione entro le finestre di schedulazione definite
• Metrica: durata del flow run come riportata da Prefect
• Soglia: <24h per le pipeline di fondazione e prioritarie

Lineage

• Obiettivo: tracciabilità completa dall'URL sorgente → file Bronze → record Silver
• Metrica: % dei record Silver con fonte, anno_rif compilati e una voce corrispondente in bronze.ingestion_log
• Soglia: 100%

Pipeline di validazione

La suite Great Expectations per ogni pipeline viene eseguita come Flow 3 immediatamente dopo il flow di trasformazione. I risultati sono persistiti nel log del run Prefect. Un'aspettativa fallita blocca il Flow 4 (registrazione dei metadati) per evitare la registrazione di lineage per dati incompleti.

Validazione delle pipeline di fondazione

Verifiche di integrità temporale

Dopo l'esecuzione delle quattro pipeline di fondazione in sequenza, le seguenti asserzioni SQL devono restituire zero righe o zero conteggi.

-- (1) Nessun duplicato attivo per lo stesso type_code e id territorio
SELECT type_code, COUNT(*) AS duplicati
FROM silver.territories
WHERE valid_to IS NULL
GROUP BY type_code, id
HAVING COUNT(*) > 1;

-- (2) Nessuna inversione di date (valid_from successivo a valid_to)
SELECT id FROM silver.territories
WHERE valid_to IS NOT NULL AND valid_from > valid_to;

-- (3) Ogni territorio ha almeno un identificatore
SELECT t.id FROM silver.territories t
LEFT JOIN silver.territory_identifiers ti ON ti.territory_id = t.id
WHERE ti.id IS NULL;

-- (4) Ogni comune attivo è contenuto in una provincia
SELECT t.id FROM silver.territories t
WHERE t.type_code = 'COM'
  AND t.valid_to IS NULL
  AND NOT EXISTS (
    SELECT 1 FROM silver.territory_containments tc
    WHERE tc.territory_id = t.id AND tc.container_type_code = 'PRO'
  );

Verifica della copertura

SELECT
  COUNT(*)             AS comuni_attivi,
  7904                 AS baseline_istat_2024,
  ROUND(COUNT(*) * 100.0 / 7904, 2) AS copertura_pct
FROM silver.territories
WHERE type_code = 'COM'
  AND valid_to IS NULL;

Metrica	Obiettivo	Risultato	Stato
Comuni attivi	7.904	TBD	in attesa
Copertura	100%	TBD	in attesa
Violazioni temporali	0	TBD	in attesa
Identificatori orfani	0	TBD	in attesa
Violazioni contenimento	0	TBD	in attesa

Validazione delle correzioni territoriali

Correzione	Chiave di ricerca (COD_CATASTO)	Esito atteso	Stato
Baranzate (MI) valid_to non aggiornato	A618	valid_to IS NULL	in attesa
Castegnero (VI) alias ADM	C056	nome alias presente in territory_names	in attesa

Validazione delle pipeline attributo

ADM Tabaccherie

Metrica	Obiettivo	Risultato	Stato
Copertura comunale	≥95%	TBD	in attesa
Fallimenti di risoluzione	0%	TBD	in attesa
Tempo di esecuzione	<24h	TBD	in attesa
Completezza lineage	100%	TBD	in attesa

I risultati delle pipeline attributo aggiuntive saranno aggiunti man mano che ciascuna pipeline raggiunge la produzione.

Benchmark di performance

[TODO] Misurazioni reali dopo l'esecuzione completa sui dati di produzione

Pipeline	Record elaborati	Tempo di esecuzione
variazioni-amministrative (ingestion)	~500K eventi	TBD
province-regioni (transform)	~120 entità	TBD
comuni (transform)	~8.000 comuni × finestre temporali	TBD
territory-corrections	~20 patch	TBD
ADM Tabaccherie	~8.000 comuni	TBD

Problemi identificati e risoluzioni

Problema #1: Instabilità dei codici comunali nelle riorganizzazioni provinciali

Descrizione: i comuni che hanno cambiato codice ISTAT a seguito di eventi di Assegnazione Provinciale (AP) non potevano essere risolti solo tramite codice, producendo record duplicati o mancanti nelle implementazioni naive. Soluzione: il flow di trasformazione dei comuni utilizza un algoritmo union-find per raggruppare tutte le varianti di codice dello stesso comune fisico sotto un unico territory_id stabile, identificato dal codice catastale Belfiore (COD_CATASTO), invariante rispetto alle riorganizzazioni provinciali. Tutti i codici ISTAT storici vengono conservati come voci in silver.territory_identifiers con i relativi intervalli valid_from/valid_to. Stato: Risolto

Problema #2: Timeout nello scraping del portale ADM

Descrizione: il portale JSF/PrimeFaces ADM andava in timeout dopo 10 minuti sulle pagine che elencavano molti comuni per provincia. Soluzione: timeout aumentato a 30 minuti; implementato retry con backoff esponenziale nella utility rate_limiter. Stato: Risolto

Raccomandazioni

Breve termine (prima della chiusura del Task 2.3)

1. Eseguire la pipeline di fondazione completa sui dati di produzione e registrare i risultati nelle tabelle di cui sopra.
2. Aggiungere un vincolo FK a livello di database su silver.territory_attributes.territory_id per applicare l'integrità referenziale al layer di storage e non solo al layer applicativo.
3. Configurare gli alert Prefect (email o Slack) sui fallimenti delle pipeline di fondazione, in modo che le regressioni di qualità dei dati vengano rilevate prima dell'esecuzione delle pipeline downstream.

Medio termine (fase di hardening del Task 2.3)

1. Estendere le suite Great Expectations Silver a tutte le pipeline attributo man mano che raggiungono la produzione.
2. Schedulare le verifiche automatiche di integrità temporale (le asserzioni SQL della sezione §2) come flow Prefect giornaliero.
3. Implementare l'acquisizione incrementale per i dataset SITUAS per evitare il re-download completo ad ogni run della pipeline.

Lungo termine

1. Esporre i risultati di validazione delle pipeline di fondazione in OpenMetadata come metriche di qualità del dataset, rendendo visibile lo stato di salute del grafo territoriale nel catalogo dati.
2. Integrare le verifiche di integrità temporale nella pipeline CI in modo che le regressioni nella logica di trasformazione vengano rilevate prima del deployment.

Conclusioni

[TODO] Riepilogo finale al completamento del testing

La strategia di validazione del Data Lake MAPS tratta l'integrità temporale come il gate di qualità principale. Poiché ogni pipeline attributo risolve infine gli identificatori sorgente in valori territory_id mantenuti dalla fondazione territoriale, la correttezza di quella fondazione — espressa attraverso catene valid_from/valid_to coerenti e gerarchie di contenimento complete — è la condizione necessaria per qualsiasi asserzione di qualità downstream. I criteri di accettazione e le asserzioni SQL definiti in questo capitolo saranno valutati sui dati di produzione man mano che ciascuna pipeline completa la fase di hardening del Task 2.3.