dbt Snapshot: un tutorial completo

dbt (data build tool) è uno strumento potente utilizzato da data analyst e data engineer per trasformare, testare e documentare i dati nel moderno data stack. 

Sebbene sia ampiamente noto per le sue capacità di modellazione, un’altra funzionalità fondamentale è lo snapshot di dbt, che ti permette di catturare dimensioni a lenta variazione (SCD) nel tuo data warehouse.

Questo tutorial fornirà una spiegazione approfondita degli snapshot di dbt, dei loro casi d’uso e dell’implementazione. Farò quanto segue:

• Definire cosa sono gli snapshot di dbt.
• Spiegare quando e perché usare gli snapshot.
• Implementare uno snapshot passo dopo passo.
• Visualizzare i dati dello snapshot.
• Condividere alcune best practice e sfide.

Per saperne di più su dbt, dai un’occhiata alla nostra guida Cos’è dbt? Un’introduzione pratica per i Data Engineer e al nostro corso Introduzione a dbt.  

Cosa sono gli Snapshot di dbt?

Uno snapshot di dbt è un meccanismo per tracciare le modifiche ai record nel tempo, soprattutto per le tabelle in cui le modifiche storiche non vengono mantenute di default. Gli snapshot sono usati principalmente per implementare le Slowly Changing Dimensions (SCD) di tipo 2. Memorizzano le versioni delle righe quando le colonne tracciate cambiano. 

Casi d’uso includono:

• Tracciare nel tempo i cambiamenti nei profili cliente.
• Monitorare i cambi di stato nei dati operativi.
• Registrare l’evoluzione degli attributi di dimensione per reportistica storica accurata.

Perché usare gli Snapshot di dbt? Benefici e casi d’uso

Gli snapshot di dbt sono preziosi perché fungono da registro delle modifiche ai dati nel tempo, abilitando l’analisi storica e la reportistica per la conformità.

Vantaggi

Ecco alcuni vantaggi che otterrai usando gli snapshot:

• Analisi dei trend: Comprendere come evolvono il comportamento, gli attributi o gli stati dei clienti.
• Audit e conformità: Dimostrare agli auditor o ai regolatori gli stati storici dei dati.
• Debug delle pipeline dati: Identificare quando un record è cambiato inaspettatamente per risalire ai problemi.

Casi d’uso comuni

Gli snapshot possono essere utili in alcune situazioni specifiche, come:

• Tracciare gli upgrade di membership nei programmi fedeltà.
• Registrare la cronologia dei prezzi dei prodotti nel retail.
• Catturare i cambi di reparto dei dipendenti nei sistemi HR.

Fondamenti architetturali

Gli snapshot si integrano perfettamente nell’ecosistema di dbt, sfruttandone la configurazione e la gestione delle esecuzioni per costruire in modo efficiente tabelle storiche.

Vediamo come esempio i tipi di modelli usati sui dati.

Esistono due modelli usati per i dati:

• Modelli standard: Trasformano i dati per creare tabelle dello stato attuale.
• Modelli di snapshot: Creano tabelle versionate per tracciare le modifiche storiche.

Questi due modelli differiscono per scopo, metodi di archiviazione e applicazioni.

Ecco un riepilogo delle differenze:

Come funzionano gli Snapshot di dbt

Gli snapshot seguono in genere un flusso strutturato che assicura che tutte le modifiche vengano catturate in modo sistematico, coinvolgendo i seguenti passaggi:

1. Configurazione: Definire strategia di snapshot, chiavi univoche e colonne per il rilevamento delle modifiche.
2. Esecuzione: Eseguire dbt snapshot per confrontare i dati attuali con gli snapshot esistenti.
3. Archiviazione: dbt inserisce nuovi record per le modifiche rilevate, aggiornando i timestamp di validità.

Ma come vengono tracciate le modifiche in dbt?

Tutte le modifiche sono registrate nella tabella di output dello snapshot.

Se viene rilevata una modifica, dbt aggiorna il campo dbt_valid_to per la versione precedente all’ora corrente e inserisce una nuova riga con il campo dbt_valid_from impostato all’ora corrente.

Strategie di Snapshot in dbt

Gli snapshot usano due strategie principali per rilevare le modifiche.

1. Strategia timestamp

• Definizione: Usa un campo timestamp per rilevare le modifiche.
• Quando usarla: La tabella di origine ha timestamp updated_at affidabili.

2. Strategia check

• Definizione: Confronta direttamente colonne specificate.
• Quando usarla: La tabella di origine non ha timestamp affidabili, ma è necessario tracciare i cambiamenti degli attributi.

Hard delete

Anche le modifiche ai dati, come le cancellazioni, possono essere tracciate, ma non di default. Tuttavia, c’è un modo per cambiare questo comportamento e monitorare tali hard delete.

• Problema: Gli snapshot non tracciano le righe cancellate di default.
• Soluzione: Imposta invalidate_hard_deletes=True per contrassegnare le righe cancellate con un valore dbt_valid_to, preservandone l’ultimo stato.

Ecco un esempio di implementazione della strategia check, tenendo conto degli hard delete:

{%
  snapshot customers_snapshot %}

{%
  set config(
    target_schema='snapshots',
    unique_key='customer_id',
    strategy='check',
    check_cols=['tier'],
    invalidate_hard_deletes=True
  )
%}

SELECT * FROM {{ source('customers') }}

{% endsnapshot %}

Guida all’implementazione degli Snapshot in dbt

Ora che sappiamo come funzionano gli snapshot di dbt, vediamo come implementarli 

1. Dataset di esempio per il tutorial sugli Snapshot

Per esercitarti con gli snapshot, creeremo una tabella clienti di esempio che imita un sistema di membership reale. Questo ci fornisce dati concreti per testare strategie comuni di snapshot.

import csv
from datetime import datetime

# Define the data
customers_data = [
    ["customer_id", "name", "tier", "updated_at"],  # header row
    [1, "Alice Tan", "Silver", "2025-07-01 10:00:00"],
    [2, "Bob Lee", "Gold", "2025-07-01 10:00:00"],
    [3, "Cheryl Lim", "Silver", "2025-07-01 10:00:00"]
]

# Write data to customers.csv
with open("customers.csv", mode="w", newline="", encoding="utf-8") as file:
    writer = csv.writer(file)
    writer.writerows(customers_data)

2. Configurare il tuo progetto dbt

Prima di poter implementare gli snapshot, è essenziale configurare correttamente il tuo progetto dbt. Ciò assicura che il tuo ambiente sia predisposto per gestire modelli, snapshot, test e documentazione in modo strutturato e scalabile.

Prerequisiti

• Assicurati di avere installato Python 3.7+.
• Installa dbt usando pip:

pip install dbt

Sostituisci dbt-postgres con l’adapter del tuo warehouse, ad es. dbt-snowflake o dbt-bigquery, in base al tuo ambiente.

Istruzioni di setup passo passo

1. Vai alla directory dei progetti desiderata.

Qui memorizzerai i tuoi progetti di analytics o ELT. In questo caso, conserveremo tutti i file correlati in questa cartella del progetto dbt.

cd ~/dbt-snapshot-project

2. Inizializza un nuovo progetto dbt.

Crea un file di configurazione chiamato dbt_project.yml:

Incolla il seguente contenuto nel file del progetto:

name: dbt_snapshots_project
version: '1.0'
profile: austinchia

seeds:
  dbt_snapshots_project:
    +quote_columns: false

3. Testa la tua connessione.

dbt debug

Questo dovrebbe essere l’output del comando:

4. Carica i seed in un database locale.

Esegui il seguente comando:

dbt seed

Questo dovrebbe essere l’output del comando:

5. Configura le impostazioni di connessione al database

Nel file profiles.yml, solitamente in ~/.dbt/profiles.yml.

Ecco cosa contiene il mio file profiles:

austinchia:
  target: dev
  outputs:
    dev:
      type: sqlite
      threads: 1
      database: ./dbt_snapshots_project.db
      schema: main
      schema_directory: ./schemas
      schemas_and_paths:
        main: ./dbt_snapshots_project.db
      extensions:
        - "C:/sqlean/crypto.dll"

Se stai usando un database SQLite come me, dovrai installare anche l’estensione SQLean.

6. Ingerisci i dati nei modelli di staging di dbt:

Crea una nuova cartella chiamata models. In quella cartella, crea un file chiamato stg_customers.sql.

Incolla il seguente codice nel file:

SELECT
  *
FROM {{ ref('customers') }}

7. Crea i modelli di staging usando il seguente comando in dbt.

dbt run --select stg_customers

Questo dovrebbe essere l’output del comando:

3. Configurare lo Snapshot di dbt

1. Crea una directory snapshots/.
2. Scrivi il tuo file SQL di snapshot con la corretta configurazione.

Per questo esempio, puoi usare il seguente codice per eseguire uno snapshot con strategia timestamp.

{% snapshot customers_snapshot %}

{{
  config(
    target_schema='snapshots',
    unique_key='customer_id',
    strategy='timestamp',
    updated_at='updated_at'
  )
}}

select * from {{ ref('customers') }}

{% endsnapshot %}

4. Eseguire lo Snapshot di dbt

Esegui:

dbt snapshot

Con questo comando, dbt crea la tabella di snapshot se non esiste. Inserisce anche nuove righe per le modifiche rilevate.

Questo dovrebbe essere l’output del comando:

5. Verificare le tabelle di Snapshot

Ora che hai eseguito lo snapshot, dovresti ottenere un nuovo file snapshot.db creato nella directory del progetto.

L’ho aperto in VSCode per vedere com’è il file:

Come puoi vedere, contiene colonne aggiuntive come dbt_updated_at e così via. Queste sono fondamentali per determinare se sono state apportate modifiche ai dati e quando.

Per guide più pratiche su dbt, dai un’occhiata alla nostra guida al Semantic Layer con dbt.

Esempio: tracciare le modifiche ai dati con gli Snapshot di dbt

Gli snapshot permettono ai team di catturare una traccia di audit completa delle modifiche di qualsiasi attributo all’interno di una tabella nel tempo, rendendoli potenti per conformità, debug e analytics.

1. Crea una tabella di esempio customers con i campi rilevanti. Include ID cliente, nome, email e timestamp updated_at per tracciare quando si verificano cambiamenti.

CREATE TABLE customers (
    customer_id INTEGER PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(100),
    updated_at TIMESTAMP
);

2. Inserisci dati iniziali per simulare uno stato di base.

Usa il seguente codice per inserire dati nella tabella. Questi dati verranno usati come stato originale prima della modifica.

INSERT INTO customers VALUES 
(1, 'Alice Tan', 'alice@example.com', '2025-07-01 10:00:00'),
(2, 'Bob Lee', 'bob.lee@example.com', '2025-07-01 10:00:00');

3. Scrivi una configurazione di snapshot dbt per tracciare le modifiche all’email:

{% snapshot customers_email_snapshot %}

{%
  set config(
    target_schema='snapshots',
    unique_key='customer_id',
    strategy='check',
    check_cols=['email'],
    invalidate_hard_deletes=True
  )
%}

SELECT * FROM {{ source('customers') }}

{% endsnapshot %}

4. Esegui dbt snapshot per registrare lo stato iniziale.

dbt snapshot

5. Simula un aggiornamento dell’email nella tabella sorgente.

Successivamente, aggiorneremo la nostra tabella originale modificando le informazioni di un cliente per simulare un cambiamento di dato.

UPDATE customers
SET email = 'alice.tan@example.com', updated_at = '2025-07-02 09:00:00'
WHERE customer_id = 1;

6. Esegui di nuovo dbt snapshot per catturare la modifica.

dbt snapshot

7. Interroga la tabella di snapshot.

Per vedere le differenze e le modifiche apportate ai dati, dovrai interrogare la tabella di snapshot. La tabella dovrebbe mostrare entrambe le versioni dell’indirizzo email con i rispettivi intervalli di validità:

SELECT customer_id, email, dbt_valid_from, dbt_valid_to
FROM snapshots.customers_email_snapshot
ORDER BY customer_id, dbt_valid_from;

Questo processo garantisce di mantenere una cronologia completa delle modifiche all’email, fondamentale per audit GDPR, tracciamento della cronologia dei contatti o analytics per il supporto clienti.

Configurazione avanzata e gestione

Una gestione efficace della configurazione consente ai team di scalare le implementazioni di snapshot tra progetti e ambienti senza interruzioni.

1. Configurazione a livello di progetto e di risorsa

• Config a livello di progetto: usa dbt_project.yml per impostare configurazioni di snapshot predefinite, come schema di destinazione o materializzazioni, applicabili a tutti gli snapshot.
• Config a livello di risorsa: sostituisci le impostazioni all’interno dei singoli file SQL di snapshot per requisiti specifici, garantendo flessibilità.

2. Personalizzare i campi di metadati

Per impostazione predefinita, dbt crea i campi dbt_valid_from e dbt_valid_to. Puoi rinominarli usando le opzioni di config valid_from e valid_to se gli standard del tuo team richiedono convenzioni di denominazione diverse per chiarezza negli strumenti BI o di data governance.

3. Migrare configurazioni di Snapshot legacy

Le migrazioni possono causare discrepanze se non gestite correttamente. Ecco alcune aree a cui prestare attenzione quando stai migrando le configurazioni degli snapshot:

1. Identificare le definizioni di snapshot legacy che utilizzano stili di blocco config deprecati.
2. Refactor verso configurazioni basate su YAML se usi versioni moderne di dbt, per coerenza.
3. Convalidare la correttezza:
• Esegui gli snapshot in ambienti di test.
• Confronta gli output prima di dismettere gli snapshot legacy.
4. Dismissione: rimuovi i vecchi file di snapshot e aggiorna la documentazione di conseguenza.

4. Integrazione con altri strumenti

Le modifiche ai dati possono essere tracciate in sincronia con gli snapshot di dbt. 

Per esempio:

• Strumenti BI (ad es., Power BI, Tableau): crea visualizzazioni temporali che mostrano i cambiamenti degli attributi nel tempo.
• Piattaforme di osservabilità (ad es., Monte Carlo, Datafold): monitora la freschezza dei dati e l’integrità storica.
• Data catalog (ad es., Alation, Collibra): includi le tabelle di cronologia degli snapshot come artefatti di lineage documentati per la conformità.

Best practice per l’implementazione in produzione

Implementare gli snapshot di dbt in produzione richiede un design attento per garantire prestazioni, manutenibilità e valore di business.

Meglio seguire queste indicazioni:

1. Casi d’uso ottimali e selezione delle tabelle

• Dai priorità alle tabelle di dimensione con attributi a lenta variazione come profili cliente, anagrafiche prodotto e contratti fornitori.
• Evita le tabelle transazionali (ad es., righe d’ordine) con inserimenti e aggiornamenti ad alta frequenza, a meno che non sia necessario, per evitare una rapida crescita dello storage.

2. Tecniche di ottimizzazione delle prestazioni

In produzione vorrai ottimizzare i tuoi dati affinché le modifiche possano essere tracciate in modo efficiente senza influire sul prodotto.

Ecco alcuni consigli:

• Indicizzazione: aggiungi indici su unique_key e colonne di validità per query più veloci.
• Partizionamento: partiziona le tabelle di snapshot per data per ottimizzare le scansioni.
• Clustering (specifico del warehouse): usa chiavi di clustering (ad es. in BigQuery) su campi ad alta cardinalità per migliorare la velocità dei filtri.

3. Pratiche di manutenzione e monitoraggio

• Scheduling: esegui gli snapshot nelle ore di minore attività per ridurre l’impatto sui costi di calcolo.
• Monitoraggio: configura avvisi per i fallimenti degli snapshot in dbt Cloud o nel tuo strumento di orchestrazione.
• Verifiche di freschezza dei dati: usa test di dbt o strumenti di osservabilità per validare la freschezza dei dati di snapshot.
• Analisi dello storage: rivedi periodicamente le dimensioni delle tabelle di snapshot e, se il business lo consente, elimina la cronologia non necessaria.

4. Errori comuni

Usare una unique_key non univoca porta a versionamento delle righe errato. Verifica sempre la logica di unicità prima del deploy. 

Il gonfiarsi dello snapshot può anche verificarsi quando si memorizzano modifiche storiche non necessarie (ad es., colonne con aggiornamenti di timestamp frequenti), facendo crescere rapidamente i costi di storage.

Sfide comuni e soluzioni

Usare gli snapshot in dbt può comportare alcune specifiche sfide tecniche:

1. Collisioni di chiavi univoche

Problema: Righe duplicate nello snapshot a causa di chiavi univoche definite male.

Soluzione:

• Convalida l’unicità usando test di dbt prima del deploy dello snapshot.
• Concatena più campi per assicurare un’unicità composita dove necessario.

2. Prestazioni delle query temporali

Problema: Query lente durante l’analisi dei dati storici.

Soluzione:

• Usa in modo efficace partizionamento e clustering del warehouse.
• Filtra sempre le query per dbt_valid_from o per intervalli di date per ridurre il volume di dati scansionati.

3. Risoluzione degli errori di esecuzione degli Snapshot

Problemi comuni includono:

• Permessi di schema o database errati.
• Modifiche allo schema della tabella sorgente (ad es. colonne rimosse) che interrompono le istruzioni SELECT dello snapshot.
• Errori di sintassi nei blocchi di config dello snapshot.

Soluzioni:

• Usa dbt debug per validare connessione e configurazione.
• Implementa test CI in dbt per intercettare errori prima del deploy.
• Consulta i log di esecuzione di dbt per messaggi di errore dettagliati.

Conclusione

Gli snapshot di dbt permettono ai team di analytics di costruire dataset storici solidi con un minimo carico ingegneristico, abilitando analytics per la conformità. Se vuoi saperne di più su dbt, consulta il nostro corso Introduzione a dbt. Per letture e altre guide, dai un’occhiata a Introduzione al pacchetto dbt-utils e al tutorial su dbt.