Redirecione seu projeto dbt para o Databricks sem reescrever modelos, testes ou lógica de negócios.
• Saiba como redirecionar seu projeto dbt existente de qualquer data warehouse de origem para o Databricks com o mínimo de alterações no código
• Acompanhe as etapas práticas: configuração do adaptador, mapeamento de namespace, diferenças de dialeto SQL, fluxo de trabalho de desenvolvimento e agendamento de produção com o Lakeflow Jobs
• Entenda como validar os resultados modelo por modelo e fazer a transição com segurança
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.
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:

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:
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.
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.
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.
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.
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.
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
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.
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:
equality ou accepted_values falharem, quase sempre se trata de precisão de ponto flutuante, não de um bug de lógica.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.
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:
O que o Jobs oferece de forma nativa:

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:
profiles.yml para que o prod aponte para o Databricks — todas as novas execuções de produção agora gravarão no Databricks.system.billing.usage para confirmar o perfil de gastos do Databricks.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:
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.
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?
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
Assine nosso blog e receba os posts mais recentes diretamente na sua caixa de entrada.