Come reindirizzare le pipeline ETL dbt su Databricks

Sempre più team eseguono le proprie trasformazioni dbt su Databricks Lakehouse: una piattaforma aperta senza vincoli di lock-in, pipeline unificate, governance integrata di Unity Catalog e un eccellente rapporto prezzo/prestazioni.

Il tuo progetto dbt funziona: i modelli compilano, i test passano e la tua logica di trasformazione risiede in SQL e YAML sotto controllo di versione, non cablata in un singolo data warehouse. Il framework di adapter aperto di dbt è progettato proprio per questo disaccoppiamento, quindi il passaggio da un cloud data warehouse a un altro è principalmente una questione di modifica dell'adapter e della configurazione di connessione, oltre a qualche piccolo ritocco al dialetto, senza dover riscrivere il DAG o la logica di business.

Databricks offre tutto questo grazie all'adapter dbt-databricks co-progettato, allo storage lakehouse aperto (Delta Lake e Apache Iceberg™), Unity Catalog e Lakeflow Jobs, che offrono una piattaforma aperta e unificata in cui dbt viene eseguito con governance integrata e un eccellente rapporto prezzo/prestazioni fin dal primo giorno, rendendolo il luogo ideale per eseguire i carichi di lavoro dbt. Ecco perché oltre 3.000 organizzazioni eseguono già dbt su Databricks.

Se stai valutando una migrazione, la buona notizia è che non devi ricostruire il tuo progetto. Questo post spiega come reindirizzare un progetto dbt funzionante su Databricks sostituendo l'adapter e il profilo, gestendo alcune differenze SQL e mantenendo la logica di trasformazione all'interno di dbt.

Perché reindirizzare dbt è un ottimo punto di partenza per la migrazione

Una sfida ricorrente nei progetti di migrazione dei data warehouse è il tentativo di spostare tutto in una volta, il che può causare ritardi e colli di bottiglia. Un approccio migliore consiste nell'iniziare con il livello di trasformazione, che rappresenta un modo rapido per sbloccare risparmi sui costi derivanti dalla migrazione.

I progetti dbt sono già modulari e testabili. Questo li rende candidati ideali per una migrazione incrementale. Quando reindirizzi dbt su Databricks, ottieni:

• Validazione immediata. Puoi confrontare i risultati tra il vecchio e il nuovo warehouse, modello per modello
• Rischio ridotto. La tua logica di trasformazione non cambia, quindi isoli la variabile alle sole risorse di calcolo e archiviazione
• Un proof of concept funzionante. Gli stakeholder possono vedere le query in esecuzione su Databricks prima di migrare i livelli di ingestion o BI
• Time-to-value più rapido. Invece di migrare un intero stack tecnologico in una sola volta, sposta prima il livello di trasformazione

Prerequisiti

Ambito: Questa guida descrive solo come reindirizzare il livello di trasformazione dbt. Presuppone che i dati di origine siano già in Databricks (caricati come tabelle Delta o Iceberg e registrati in Unity Catalog) e che i cataloghi e gli schemi esistano già. La migrazione dei dati stessi e la configurazione di Unity Catalog sono attività separate; per queste, consulta le guide alla migrazione di Databricks e Lakebridge.

Prima di iniziare, assicurati di avere:

• Un'area di lavoro Databricks con un SQL warehouse configurato
• Una configurazione di Unity Catalog con il catalogo e lo schema di destinazione creati, e le tabelle di origine (raw/bronze) già caricate come Delta o Iceberg e registrate in UC
• Il tuo progetto dbt esistente sotto controllo di versione (dbt Core 1.8+ o dbt Platform)
• Python 3.9+ installato localmente (per gli utenti di dbt Core)
• Credenziali di accesso: un token di acesso personale Databricks o una configurazione OAuth
• In alternativa, Lakebridge può automatizzare gran parte della conversione SQL. Esegue la scansione del warehouse di origine e dell'SQL nei modelli dbt, converte l'SQL specifico del dialetto in Databricks Lakehouse e riconcilia i risultati con l'origine. Reindirizza l'SQL in un progetto dbt anziché migrare dbt stesso, e non sposta i dati che utilizzano pattern separati (Lakehouse Federation + CTAS, COPY INTO o Auto Loader).

Il modello che migreremo in questo esempio è una tabella dei fatti analitica standard creata sulla base di due modelli di origine: orders e order_items. Aggrega i dati a livello di ordine per calcolare i ricavi totali e compila un elenco di prodotti venduti per ogni singola transazione dell'ultimo anno. 

Questo modello utilizza diversi pattern comuni del dialetto SQL, come regexp_substr, div0 e object_construct, che spesso differiscono tra i vari data warehouse, rappresentando quindi un ottimo esempio. Una volta compreso come gestire questi pattern in questo caso, potrai applicare lo stesso approccio a tutti gli altri modelli del tuo progetto.

Passaggio 1: installa l'adapter e aggiungi una destinazione Databricks

Questa parte copre il lavoro di migrazione una tantum, che prevede l'installazione dell'adapter, la mappatura dei namespace e la gestione delle differenze di dialetto.

Installa l'adapter dbt-databricks

L'adapter dbt-databricks è il ponte tra il tuo progetto dbt e il warehouse Databricks Lakehouse. Traduce l'SQL compilato di dbt in query compatibili con Databricks.

(Utenti di dbt Platform: selezionate "Databricks" come tipo di connessione in un nuovo ambiente, come descritto in dettaglio nella documentazione di dbt; l'adapter viene installato automaticamente.)

Aggiungi una destinazione Databricks a `profiles.yml`. Mantieni intatta la destinazione esistente; ti servirà durante la validazione. Aggiungi una seconda destinazione accanto ad essa:

Verifica la connessione:

Dovresti vedere:  Connection test: [OK connection ok].

Se riscontri ancora problemi di connessione, segui i passaggi per la risoluzione dei problemi nella guida all'integrazione di Databricks + dbt e nel riferimento del profilo dbt Databricks.

Suggerimento: http_path determina se le query vengono eseguite su un SQL warehouse (scelta consigliata per dbt) o su un cluster all-purpose. I SQL warehouse offrono un rapporto prezzo/prestazioni migliore per i carichi di lavoro ad alta intensità di SQL.

Passaggio 2: indirizza le tabelle di origine verso Unity Catalog e aggiungi i test

Databricks utilizza un namespace a tre livelli: catalog.schema.table. Aggiorna le voci sources.yml da cui legge fct_orders:

Aggiorna schema.yml per includere i test

Suggerimento: Se salti database:, le query finiranno nel catalogo predefinito dell'area di lavoro. Impostalo esplicitamente.

Passaggio 3: prima compilazione

Ora esegui dbt compile per il modello:

Il nostro modello fct_orders ha generato 3 errori di compilazione come dettagliato di seguito, tutti relativi al dialetto SQL. Questo è previsto e, sebbene questi tre siano rappresentativi dei problemi di dialetto riscontrati nella maggior parte dei progetti, non sono tutto: le migrazioni più grandi devono affrontare anche strategie di modelli incrementali, snapshot e funzioni semistrutturate senza un equivalente diretto. 

Utilizziamo intenzionalmente un modello di esempio che si basa su pattern specifici del dialetto come REGEXP_SUBSTR con parametri posizionali, DIV0 per la divisione sicura e OBJECT_CONSTRUCT per la creazione di JSON - il tipo di funzioni che variano a seconda del data warehouse. In questo modo, gli errori iniziali di dbt run diventano una guida nel processo di conversione, mostrandoti come trasformarli in macro portabili e in SQL compatibile con Databricks, così da poter applicare le stesse correzioni al resto del progetto. Per dimostrarlo, ti guideremo attraverso ciascun errore, la causa principale e la correzione. Prima di analizzare gli errori, una nota sulla portabilità: quando una funzione ha un equivalente portabile, le macro cross-database di dbt (il namespace dbt.*) ti consentono di scriverla una sola volta in modo che venga compilata su qualsiasi data warehouse — una pratica che vale la pena adottare man mano che standardizzi. Esamineremo ogni errore e la relativa correzione, per poi mostrarti come automatizzare la conversione su un intero progetto di grandi dimensioni.

Errore 1: incompatibilità del dialetto REGEXP_SUBSTR

Databricks segue il dialetto Apache SQL e supporta solo 2 parametri per REGEXP_SUBSTR

Soluzione: usa la funzione nativa regexp_extract() di Databricks

Potresti anche lasciare che sia Genie Code a eseguire questa conversione per te; colmare lacune dialettali come questa è esattamente ciò in cui eccelle. Le faremo tutte e tre manualmente in modo che tu possa vedere cosa cambia.

Errore 2: DIV0 (divisione sicura)

Causa principale: alcuni data warehouse utilizzano DIV0 per restituire 0 anziché generare un errore in caso di divisione per zero.

Soluzione: aggiungi dbt_utils ai tuoi pacchetti e usa la sua funzione integrata safe_divide

Errore 3: object_construct (creatore JSON)

Impossibile risolvere la routine `object_construct`

Soluzione: usa la funzione named_struct di Databricks

Esegui nuovamente la compilazione:

Compilazione completata con successo. Modifiche totali del dialetto per questo modello: dbt_utils package installed (per la divisione sicura), regexp_substr call converted to regexp_extract, chiamata a div0 sostituita con dbt_utils.safe_divide(), da  object_construct call converted a named_struct.

Correggere tre funzioni a mano è semplice. Un vero progetto dbt ha centinaia o migliaia di modelli, e queste lacune dialettali sono esattamente ciò che gli strumenti di IA colmano automaticamente. Genie Code converte il codice SQL specifico del dialetto e gestisce queste correzioni direttamente nell'editor, così potrai dedicare il tuo tempo a rivedere le conversioni anziché a scriverle una per una.

Passaggio 4: prima esecuzione

Una volta che la compilazione è andata a buon fine, esegui il modello e gli eventuali test esistenti:

Sia la build del modello che i test sono stati superati con successo. Suggerimento:

• Tempo di esecuzione. Prendine nota: lo confronterai con il vecchio data warehouse nel passaggio successivo.
• Errori nei test sulle colonne numeriche. Se i test equality o accepted_values falliscono, quasi sempre si tratta di precisione in virgola mobile, non di un bug logico.

Passo 5: Convalida riga per riga rispetto al warehouse legacy

Un dbt run verde dimostra che l'SQL viene eseguito. Ora dobbiamo riconciliare i risultati tra il warehouse legacy e Databricks. Usa dbt-audit-helper per confrontare riga per riga.

Installa:

Confronta fct_orders tra entrambi i warehouse. In analyses/compare_fct_orders.sql:

Esegui il comando su Databricks (presupponendo che tu abbia replicato l'output legacy in Databricks per il confronto, o che tu stia eseguendo un confronto tra warehouse diversi):

Risultato previsto:

Nota: questi esempi coprono i pattern più comuni, ma non sono esaustivi. Per qualsiasi ulteriore discrepanza (ad es. rimozione degli spazi nelle stringhe, collation o comportamento di UDF personalizzate), imposta summarize=false per materializzare le righe di esempio, esamina alcune chiavi primarie in cui in_a e in_b differiscono, correggi il modello o la macro e riavvia fino a ottenere una corrispondenza al 100%.

Nella nostra esecuzione: fct_orders corrispondeva esattamente.

Passo 6: Distribuzione in Databricks

Invece di gestire un livello di orchestrazione separato per dbt, puoi eseguire dbt insieme all'ingestione a monte e alle azioni a valle in una singola pipeline con i Lakeflow Jobs. dbt è un tipo di task di prima classe all'interno di Jobs e non hai bisogno di un orchestratore esterno o di un'immagine Docker personalizzata.

Crea il Job:

1. Workspace → Jobs & Pipelines → Create Job
2. Tipo di task: dbt
3. Origine Git: il tuo repository dbt
4. Comandi:

5. SQL warehouse: il tuo warehouse di produzione
6. Catalogo del warehouse: il catalogo in cui verrà scritta la tabella: dev
7. Schema del warehouse: lo schema in cui verrà scritta la tabella: analytics
8. Pianificazione: la frequenza preferita

Cosa offre Jobs fin da subito:

• Completamente gestito: nessuna infrastruttura aggiuntiva da acquistare, proteggere o gestire
• Possibilità di creare una singola pipeline per eseguire i task dbt insieme alle pipeline di ingestione a monte e ad attività a valle come gli aggiornamenti di Power BI

Passo 7: Transizione e dismissione

Dopo aver convalidato il progetto dbt e averlo distribuito su Databricks, il passo successivo consiste nello spostare il traffico di produzione su Databricks in modo controllato, mantenere un percorso di rollback breve ed evitare di pagare per due warehouse più a lungo del necessario.

Tieni a mente questa checklist:

1. Modifica il target di produzione in profiles.yml in modo che prod punti a Databricks: tutte le nuove esecuzioni di produzione ora scriveranno su Databricks.
2. Aggiorna le credenziali CI/CD in modo che i controlli delle PR vengano eseguiti su un catalogo di staging di Databricks, non sul warehouse legacy.
3. Monitora i costi tramite system.billing.usage per confermare il profilo di spesa di Databricks.
4. Dismetti il target legacy una volta chiusa la finestra di rollback e quando hai la certezza che Databricks sia stabile in produzione.

Estensione al resto del progetto

La maggior parte del lavoro appena svolto si fa una sola volta: l'installazione dell'adapter, il target profiles.yml e la modifica del namespace di origine. Una volta configurati, reindirizzare il modello successivo richiederà solo le correzioni incrementali del dialetto.

Alcuni pattern richiedono più di un semplice cambio di dialetto e li incontrerai man mano che estendi il progetto:

• Modelli incrementali: le strategie incrementali variano a seconda delle piattaforme; la strategia utilizzata dall'origine potrebbe non corrispondere 1:1 a una strategia incrementale di Databricks, quindi dovrai selezionare nuovamente la strategia e riconvalidare la logica incrementale.
• Snapshot: reindirizzerai la logica degli snapshot e, separatamente, trasferirai i dati storici degli snapshot esistenti per non perdere la cronologia.
• Funzioni semistrutturate e di nicchia: alcune funzioni di origine non hanno un equivalente diretto in Databricks e richiedono una riscrittura o una macro, non una semplice riga di codice.

Per il lavoro più impegnativo, fai affidamento sulle guide complete alla migrazione.

Da lì, esegui la migrazione in piccoli lotti e procedi in ordine di DAG: prima le origini, poi staging, intermediate e mart, in modo che ogni lotto venga convalidato correttamente rispetto ai modelli già spostati. Esegui entrambi i target in parallelo e usa audit-helper per confrontare ogni modello finché non corrispondono tutti. Quando l'ultimo modello è verde, effettua la transizione dell'intero progetto. Questa guida è una panoramica semplificata del reindirizzamento, mentre l'intero ambito di una migrazione è trattato nelle nostre guide pubbliche alla migrazione. 

Conclusione

Il reindirizzamento di dbt verso Databricks è un modo pratico e a basso rischio per avviare la migrazione di un warehouse. I tuoi modelli e test rimangono gli stessi: cambia solo il luogo in cui vengono eseguiti, e ottieni formati e standard open source come Delta Lake e Apache Iceberg™, con Unity Catalog che fornisce governance e lineage su una piattaforma in grado di supportare anche le tue attività di AI a valle. Inizia con un modello, confronta i risultati, quindi espandi fino a quando non ti sentirai a tuo agio nel rendere Databricks la sede principale del tuo progetto dbt.

Vuoi provarlo? 

1. Attiva una prova gratuita di Databricks
2. Installa l'adapter dbt-databricks
3. Esegui la tua prima compilazione dbt su un warehouse Databricks Lakehouse. Successivamente, distribuisci un Job di Databricks per eseguire un modello dbt in produzione seguendo la documentazione di Databricks.

Per saperne di più su dbt con Databricks, esplora l'adapter dbt-databricks su GitHub.

(Questo post sul blog è stato tradotto utilizzando strumenti basati sull'intelligenza artificiale) Post originale