Como redirecionar pipelines de ETL do dbt para o Databricks

Mais equipes estão executando suas transformações dbt no Databricks Lakehouse: uma plataforma aberta sem aprisionamento tecnológico (lock-in), pipelines unificados, governança integrada do Unity Catalog e excelente relação custo-benefício.

Seu projeto dbt funciona: os modelos compilam, os testes passam e sua lógica de transformação reside em SQL e YAML com controle de versão, sem estar rigidamente vinculada a nenhum data warehouse específico. A estrutura de adaptador aberto do dbt foi projetada exatamente para esse desacoplamento, de modo que a migração de um cloud data warehouse para outro é basicamente uma questão de alterar o adaptador e a configuração de conexão, além de alguns ajustes de dialeto — e não reescrever seu DAG ou lógica de negócios.

A Databricks oferece isso com o adaptador dbt-databricks desenvolvido em parceria, armazenamento de lakehouse aberto (Delta Lake e Apache Iceberg™), Unity Catalog e Lakeflow Jobs, que oferecem uma plataforma aberta e unificada onde o dbt é executado com governança integrada e excelente relação custo-benefício desde o primeiro dia, tornando-o um ótimo lugar para executar suas cargas de trabalho dbt. É por isso que mais de 3.000 organizações já executam o dbt na Databricks.

Se você está avaliando uma migração, a boa notícia é que não precisa reconstruir seu projeto. Este post explica como redirecionar um projeto dbt ativo para a Databricks, trocando o adaptador e o perfil, lidando com algumas diferenças de SQL e mantendo sua lógica de transformação dentro do dbt.

Por que redirecionar o dbt é um excelente ponto de partida para a migração

Um desafio recorrente em projetos de migração de data warehouse é tentar mover tudo de uma vez, o que pode levar a atrasos e gargalos. Uma abordagem melhor é começar pela camada de transformação, que é uma maneira rápida de gerar economia de custos em uma migração.

Os projetos dbt já são modulares e testáveis. Isso os torna candidatos ideais para uma migração incremental. Ao redirecionar o dbt para a Databricks, você obtém:

• Validação imediata. Você pode comparar os resultados entre os data warehouses antigo e novo, modelo por modelo
• Risco reduzido. Sua lógica de transformação não muda, então você isola a variável para computação e armazenamento
• Uma prova de conceito funcional. As partes interessadas podem ver as consultas sendo executadas na Databricks antes de você migrar as camadas de ingestão ou BI
• Geração de valor mais rápida. Em vez de migrar toda a pilha de tecnologia de uma só vez, mova a camada de transformação primeiro

Pré-requisitos

Escopo: Este guia aborda apenas o redirecionamento da sua camada de transformação dbt. Ele pressupõe que seus dados de origem já estejam na Databricks — carregados como tabelas Delta ou Iceberg e registrados no Unity Catalog — e que seus catálogos e esquemas já existam. A migração dos dados em si e a configuração do Unity Catalog são esforços separados; consulte os guias de migração da Databricks e o Lakebridge para obter mais informações.

Antes de começar, certifique-se de ter:

• Um workspace da Databricks com um SQL warehouse provisionado
• Uma configuração do Unity Catalog com o catálogo e o esquema de destino criados, e suas tabelas de origem (raw/bronze) já carregadas como Delta ou Iceberg e registradas no UC
• Seu projeto dbt existente sob controle de versão (dbt Core 1.8+ ou dbt Platform)
• Python 3.9+ instalado localmente (para usuários do dbt Core)
• Credenciais de acesso: um token de acesso pessoal da Databricks ou configuração OAuth
• Opcionalmente, o Lakebridge pode automatizar grande parte da conversão de SQL. Ele verifica seu warehouse de origem e o SQL em seus modelos dbt, converte o SQL específico do dialeto para o Databricks Lakehouse e reconcilia os resultados com a origem. Ele redireciona o SQL em um projeto dbt em vez de migrar o próprio dbt, e não move dados que usam padrões separados (Lakehouse Federation + CTAS, COPY INTO ou Auto Loader).

O modelo que migraremos neste exemplo é uma tabela de fatos analítica padrão criada com base em dois modelos de origem: orders e order_items. Ele agrega dados no nível do pedido para calcular a receita total e compila uma lista de produtos vendidos para cada transação individual do ano passado. 

Este modelo usa vários padrões comuns de dialeto SQL, como regexp_substr, div0 e object_construct, que geralmente diferem entre data warehouses, tornando-o um ótimo exemplo. Depois de ver como lidar com esses padrões aqui, você poderá aplicar a mesma abordagem a todos os outros modelos do seu projeto.

Passo 1: Instalar o adaptador e adicionar um destino da Databricks

Esta parte aborda o trabalho de migração único, que envolve a instalação do adaptador, o mapeamento de namespaces e o tratamento de diferenças de dialeto.

Instalar o adaptador dbt-databricks

O adaptador dbt-databricks é a ponte entre o seu projeto dbt e o warehouse do Databricks Lakehouse. Ele traduz o SQL compilado do dbt em consultas compatíveis com a Databricks.

(Usuários do dbt Platform: selecionem "Databricks" como o tipo de conexão em um novo ambiente, conforme detalhado na documentação do dbt — o adaptador é instalado automaticamente.)

Adicione um destino da Databricks ao `profiles.yml`. Mantenha seu destino existente intacto; você precisará dele durante a validação. Adicione um segundo destino ao lado dele:

Verifique a conexão:

Você deve ver:  Connection test: [OK connection ok].

Se ainda assim não conseguir se conectar, siga as etapas de solução de problemas de conexão no guia de integração do Databricks + dbt e na referência do perfil dbt do Databricks.

Dica de especialista: http_path determina se as consultas são executadas em um SQL warehouse (recomendado para dbt) ou em um cluster de uso geral. Os SQL warehouses oferecem melhor relação custo-benefício para cargas de trabalho com uso intenso de SQL.

Etapa 2: Apontar as origens das tabelas para o Unity Catalog e adicionar testes

O Databricks usa um namespace de três níveis: catalog.schema.table. Atualize as entradas do sources.yml que o fct_orders lê:

Atualize o schema.yml para incluir testes

Dica de especialista: Se você pular o database:, as consultas irão para o catálogo padrão do workspace. Defina-o explicitamente.

Etapa 3: Primeira compilação

Agora execute dbt compile para o modelo:

Nosso modelo fct_orders gerou 3 erros de compilação, conforme detalhado abaixo, todos relacionados ao dialeto. Isso é esperado e, embora esses três sejam representativos dos problemas de dialeto que a maioria dos projetos enfrenta, eles não são tudo: migrações maiores também encontram estratégias de modelo incremental, snapshots e funções semiestruturadas sem equivalente direto. 

Usamos intencionalmente um modelo de exemplo que depende de padrões específicos de dialeto, como REGEXP_SUBSTR com parâmetros posicionais, DIV0 para divisão segura e OBJECT_CONSTRUCT para criação de JSON – o tipo de funções que diferem entre os warehouses. Dessa forma, os erros iniciais do dbt run tornam-se um guia pelo processo de conversão, mostrando como transformá-los em macros portáteis e SQL compatível com o Databricks, para que você possa aplicar as mesmas correções no restante do seu projeto. Para demonstrar, vamos orientar você em cada erro, na causa raiz e na correção. Antes de nos aprofundarmos nos erros, uma observação sobre portabilidade: quando uma função tem um equivalente portátil, as macros de banco de dados cruzado do dbt (o namespace dbt.*) permitem que você a escreva uma vez para que seja compilada em qualquer warehouse — algo que vale a pena adotar à medida que você padroniza. Vamos analisar cada erro e sua correção e, em seguida, mostrar como automatizar a conversão em um projeto grande.

Erro 1: Incompatibilidade de dialeto do REGEXP_SUBSTR

O Databricks segue o dialeto Apache SQL e suporta apenas 2 parâmetros para REGEXP_SUBSTR

Correção: use a função nativa regexp_extract() do Databricks

Você também pode deixar que o Genie Code faça essa conversão para você; corrigir lacunas de dialeto como essa é exatamente a especialidade dele. Faremos as três manualmente para que você possa ver o que está mudando.

Erro 2: DIV0 (divisão segura)

Causa raiz: alguns warehouses usam DIV0 para retornar 0 em vez de gerar um erro ao dividir por zero.

Correção: adicione dbt_utils aos seus pacotes e use sua função integrada safe_divide

Erro 3: object_construct (criador de JSON)

Não é possível resolver a rotina `object_construct`

Correção: Use a função named_struct do Databricks

Execute a compilação novamente:

Compilado com sucesso. Total de alterações de dialeto para este modelo: dbt_utils package installed (para divisão segura), regexp_substr call converted to regexp_extract, div0 chamada substituída por dbt_utils.safe_divide(), object_construct call converted para named_struct.

Corrigir três funções manualmente é fácil. Um projeto dbt real tem centenas ou milhares de modelos, e essas lacunas de dialeto são exatamente o que as ferramentas de IA resolvem automaticamente. O Genie Code converte SQL específico de dialeto e lida com essas correções diretamente no editor, para que você gaste seu tempo revisando as conversões em vez de escrever cada uma delas.

Etapa 4: Primeira execução

Com a compilação bem-sucedida, execute o modelo e todos os testes existentes:

Tanto a compilação do modelo quanto os testes foram aprovados. Dica de especialista:

• Tempo de execução. Anote-o — você fará a comparação com o warehouse antigo na próxima etapa.
• Falhas de teste em colunas numéricas. Se os testes equality ou accepted_values falharem, quase sempre se trata de precisão de ponto flutuante, não de um bug de lógica.

Etapa 5: Validar linha por linha em relação ao warehouse legado

Um dbt run verde prova que o SQL é executado. Agora, precisamos reconciliar os resultados entre o warehouse legado e o Databricks. Use o dbt-audit-helper para comparar linha por linha.

Instalação:

Compare o fct_orders em ambos os warehouses. No analyses/compare_fct_orders.sql:

Execute-o no Databricks (supondo que você tenha replicado a saída legada no Databricks para a comparação ou executado uma comparação entre warehouses):

Resultado esperado:

Observação: Estes exemplos cobrem os padrões mais comuns, mas não são exaustivos. Para qualquer divergência adicional (por exemplo, remoção de espaços em strings, colação ou comportamento de UDF personalizada), defina summarize=false para materializar linhas de amostra, inspecione algumas chaves primárias onde in_a e in_b diferem, corrija o modelo ou macro e execute novamente até obter 100% de correspondência.

Em nossa execução: fct_orders correspondeu exatamente.

Etapa 6: Implantar no Databricks

Em vez de manter uma camada de orquestração separada para o dbt, você pode executar o dbt junto com a ingestão upstream e as ações downstream em um único pipeline com o Lakeflow Jobs. O dbt é um tipo de tarefa de primeira classe no Jobs, e você não precisa de um orquestrador externo ou de uma imagem Docker personalizada.

Criar o Job:

1. Workspace → Jobs e Pipelines → Criar Job
2. Tipo de tarefa: dbt
3. Origem do Git: seu repositório dbt
4. Comandos:

5. SQL warehouse: seu warehouse de produção
6. Catálogo do Warehouse: o catálogo no qual a tabela será gravada: dev
7. Esquema do Warehouse: o esquema no qual a tabela será gravada: analytics
8. Agendamento: sua frequência preferida

O que o Jobs oferece de forma nativa:

• Totalmente gerenciado — sem infraestrutura adicional para adquirir, proteger ou manter
• Capacidade de criar um único pipeline para executar tarefas dbt junto com pipelines de ingestão upstream e tarefas downstream, como atualizações do Power BI

Etapa 7: Transição e desativação

Depois de validar seu projeto dbt e implantá-lo no Databricks, a próxima etapa é mover o tráfego de produção para o Databricks de forma controlada, manter um caminho curto de reversão (rollback) e evitar pagar por dois warehouses por mais tempo do que o necessário.

Guarde este checklist:

1. Altere o destino de produção no profiles.yml para que o prod aponte para o Databricks — todas as novas execuções de produção agora gravarão no Databricks.
2. Atualize as credenciais de CI/CD para que as verificações de PR sejam executadas em um catálogo de staging do Databricks, não no warehouse legado.
3. Monitore os custos por meio do system.billing.usage para confirmar o perfil de gastos do Databricks.
4. Desative o destino legado assim que a janela de reversão (rollback) fechar e você tiver certeza de que o Databricks está estável em produção.

Escalando para o restante do seu projeto

A maior parte do trabalho que você acabou de fazer é realizada apenas uma vez: a instalação do adaptador, o destino profiles.yml e a alteração do namespace de origem. Depois que eles estiverem configurados, redirecionar o próximo modelo custará apenas as correções incrementais de dialeto.

Alguns padrões exigem mais do que uma troca de dialeto, e você os encontrará à medida que escalar:

• Modelos incrementais — as estratégias incrementais diferem entre as plataformas; a estratégia que sua origem usa pode não mapear de 1 para 1 para uma estratégia incremental do Databricks, portanto, você precisará selecionar novamente a estratégia e revalidar a lógica incremental.
• Snapshots — você redirecionará a lógica de snapshot e, separadamente, trará os dados históricos de snapshot existentes para não perder o histórico.
• Funções semiestruturadas e de nicho — algumas funções de origem não têm equivalente direto no Databricks e exigem uma reescrita ou uma macro, não apenas uma linha de código.

Para o trabalho mais pesado aqui, conte com os guias de migração completos.

A partir daí, migre em pequenos lotes e trabalhe na ordem do DAG — primeiro as origens, depois staging, intermediários e marts, para que cada lote seja validado de forma limpa em relação aos modelos que você já moveu. Execute ambos os destinos em paralelo e use o audit-helper para comparar cada modelo até que todos correspondam. Quando o último modelo estiver verde, faça a transição de todo o projeto. Este guia é um passo a passo simplificado de redirecionamento, com o escopo completo de uma migração abordado em nossos guias públicos de migração. 

Conclusão

Redirecionar o dbt para o Databricks é uma maneira prática e de baixo risco de iniciar uma migração de warehouse. Seus modelos e testes continuam os mesmos — você está apenas mudando onde eles são executados e ganha formatos e padrões de código aberto, como o Delta Lake e o Apache Iceberg™, com o Unity Catalog fornecendo governança e linhagem sobre uma plataforma que também pode atender ao seu trabalho de AI downstream. Comece com um modelo, compare os resultados e, em seguida, expanda até se sentir confortável em tornar o Databricks a casa principal do seu projeto dbt.

Pronto para testar? 

1. Configure uma avaliação gratuita do Databricks
2. Instale o adaptador dbt-databricks
3. Execute sua primeira compilação dbt em um warehouse do Databricks Lakehouse. Depois, implante um Job do Databricks para executar um modelo dbt em produção seguindo a documentação do Databricks.

Para saber mais sobre o dbt com o Databricks, explore o adaptador dbt-databricks no GitHub.

(Esta publicação no blog foi traduzida utilizando ferramentas baseadas em inteligência artificial) Publicação original