Cómo redireccionar pipelines ETL de dbt a Databricks

Cada vez más equipos ejecutan sus transformaciones de dbt en Databricks Lakehouse: una plataforma abierta sin dependencia de proveedores, pipelines unificados, gobernanza integrada de Unity Catalog y una excelente relación precio/rendimiento.

Su proyecto de dbt funciona: los modelos compilan, las pruebas se superan y su lógica de transformación reside en SQL y YAML con control de versiones, no codificada de forma rígida en un único almacén de datos. El framework de adaptador abierto de dbt está diseñado exactamente para este desacoplamiento, por lo que migrar de un data warehouse en la nube a otro es principalmente cuestión de cambiar el adaptador y la configuración de conexión, además de algunos ajustes de dialecto, no de reescribir su DAG o lógica de negocio.

Databricks cumple con eso gracias al adaptador dbt-databricks, el almacenamiento de lakehouse abierto (Delta Lake y Apache Iceberg™), Unity Catalog y Lakeflow Jobs, que le ofrecen una plataforma abierta y unificada donde dbt se ejecuta con gobernanza integrada y una excelente relación precio/rendimiento desde el primer día, lo que lo convierte en un lugar ideal para ejecutar sus cargas de trabajo de dbt. Por eso, más de 3000 organizaciones ya ejecutan dbt en Databricks.

Si ha estado evaluando una migración, la buena noticia es que no tiene que reconstruir su proyecto. Este artículo explica cómo redirigir un proyecto de dbt activo a Databricks cambiando el adaptador y el perfil, gestionando algunas diferencias de SQL y manteniendo su lógica de transformación dentro de dbt.

Por qué redirigir dbt es un excelente punto de partida para la migración

Un desafío recurrente en los proyectos de migración de data warehouses es intentar mover todo a la vez, lo que puede provocar retrasos y cuellos de botella. Un mejor enfoque es comenzar con la capa de transformación, lo cual es una forma rápida de generar ahorros de costos en una migración.

Los proyectos de dbt ya son modulares y testeables. Eso los convierte en candidatos ideales para una migración incremental. Al redirigir dbt a Databricks, obtiene:

• Validación inmediata. Puede comparar los resultados entre el antiguo y el nuevo almacén de datos, modelo por modelo
• Riesgo reducido. Su lógica de transformación no cambia, por lo que aísla la variable al cómputo y al almacenamiento
• Una prueba de concepto funcional. Las partes interesadas pueden ver las consultas ejecutándose en Databricks antes de migrar las capas de ingesta o BI
• Menor tiempo para obtener valor. En lugar de migrar toda la pila tecnológica a la vez, mueva primero la capa de transformación

Requisitos previos

Alcance: Esta guía solo cubre la redirección de su capa de transformación de dbt. Se asume que sus datos de origen ya están en Databricks (almacenados como tablas Delta o Iceberg y registrados en Unity Catalog) y que sus catálogos y esquemas ya existen. La migración de los datos en sí y la configuración de Unity Catalog son esfuerzos independientes; consulte las guías de migración de Databricks y Lakebridge para obtener más información al respecto.

Antes de comenzar, asegúrese de tener:

• Un espacio de trabajo de Databricks con un SQL warehouse aprovisionado
• Una configuración de Unity Catalog con el catálogo y el esquema de destino creados, y sus tablas de origen (raw/bronze) ya almacenadas como Delta o Iceberg y registradas en UC
• Su proyecto de dbt existente en un sistema de control de versiones (dbt Core 1.8+ o dbt Platform)
• Python 3.9+ instalado localmente (para usuarios de dbt Core)
• Credenciales de acceso: un token de acceso personal de Databricks o una configuración de OAuth
• Opcionalmente, Lakebridge puede automatizar gran parte de la conversión de SQL. Escanea su almacén de origen y el SQL de sus modelos de dbt, convierte el SQL específico del dialecto a Databricks Lakehouse y concilia los resultados con el origen. Redirige el SQL en un proyecto de dbt en lugar de migrar dbt en sí, y no mueve datos que utilicen patrones independientes (Lakehouse Federation + CTAS, COPY INTO o Auto Loader).

El modelo que migraremos en este ejemplo es una tabla de hechos analítica estándar construida sobre dos modelos de origen: orders y order_items. Agrega datos a nivel de pedido para calcular los ingresos totales y compila una lista de productos vendidos para cada transacción individual del último año. 

Este modelo utiliza varios patrones comunes de dialecto SQL, como regexp_substr, div0 y object_construct, que a menudo difieren entre los almacenes de datos, lo que lo convierte en un excelente ejemplo. Una vez que vea cómo manejar estos patrones aquí, podrá aplicar el mismo enfoque a todos los demás modelos de su proyecto.

Paso 1: Instalar el adaptador y agregar un destino de Databricks

Esta parte cubre el trabajo de migración que se realiza una sola vez, el cual incluye instalar el adaptador, mapear espacios de nombres y gestionar las diferencias de dialecto.

Instalar el adaptador dbt-databricks

El adaptador dbt-databricks es el puente entre su proyecto de dbt y el almacén de Databricks Lakehouse. Traduce el SQL compilado de dbt en consultas compatibles con Databricks.

(Usuarios de dbt Platform: seleccionen "Databricks" como tipo de conexión en un nuevo entorno, tal como se detalla en la documentación de dbt; el adaptador se instala automáticamente).

Agregue un destino de Databricks a `profiles.yml`. Mantenga intacto su destino existente; lo necesitará durante la validación. Agregue un segundo destino junto a él:

Verifica la conexión:

Deberías ver:  Connection test: [OK connection ok].

Si aún no puedes conectarte, sigue los pasos de resolución de problemas de conexión en la guía de integración de Databricks + dbt y en la referencia de perfil de dbt Databricks.

Consejo profesional: http_path determina si las consultas se ejecutan en un SQL warehouse (recomendado para dbt) o en un clúster de uso general. Los SQL warehouses ofrecen una mejor relación precio/rendimiento para cargas de trabajo con un uso intensivo de SQL.

Paso 2: Apuntar las fuentes de tabla a Unity Catalog y agregar pruebas

Databricks utiliza un espacio de nombres de tres niveles: catalog.schema.table. Actualiza las entradas de sources.yml de las que lee fct_orders:

Actualiza schema.yml para incluir pruebas

Consejo profesional: Si omites database:, las consultas irán al catálogo predeterminado del espacio de trabajo. Establécelo de forma explícita.

Paso 3: Primera compilación

Ahora ejecuta dbt compile para el modelo:

Nuestro modelo fct_orders produjo 3 errores de compilación como se detalla a continuación, todos relacionados con el dialecto. Esto es de esperarse y, aunque estos tres son representativos de los problemas de dialecto que experimentan la mayoría de los proyectos, no lo son todo: las migraciones más grandes también se topan con estrategias de modelos incrementales, instantáneas (snapshots) y funciones semiestructuradas sin un equivalente directo. 

Utilizamos intencionalmente un modelo de ejemplo que se basa en patrones específicos del dialecto como REGEXP_SUBSTR con parámetros posicionales, DIV0 para la división segura y OBJECT_CONSTRUCT para la creación de JSON - el tipo de funciones que difieren entre los warehouses. De esa manera, los errores iniciales de dbt run se convierten en una guía a lo largo del proceso de conversión, mostrándote cómo transformarlos en macros portátiles y SQL compatible con Databricks para que puedas aplicar las mismas correcciones en el resto de tu proyecto. Para demostrarlo, te guiaremos a través de cada error, su causa raíz y la solución. Antes de profundizar en los errores, una nota sobre la portabilidad: cuando una función tiene un equivalente portátil, las macros de bases de datos cruzadas de dbt (el espacio de nombres dbt.*) te permiten escribirla una sola vez para que se compile en cualquier warehouse, algo que vale la pena adoptar a medida que estandarizas. Analizaremos cada error y su solución, y luego mostraremos cómo automatizar la conversión en un proyecto grande.

Error 1: Incompatibilidad de dialecto de REGEXP_SUBSTR

Databricks sigue el dialecto Apache SQL y solo admite 2 parámetros para REGEXP_SUBSTR

Solución: usa la función nativa regexp_extract() de Databricks

También podrías dejar que Genie Code realice esta conversión por ti; solucionar brechas de dialecto como esta es exactamente para lo que sirve. Haremos las tres a mano para que puedas ver qué está cambiando.

Error 2: DIV0 (división segura)

Causa raíz: algunos warehouses usan DIV0 para devolver 0 en lugar de generar un error al dividir por cero.

Solución: agrega dbt_utils a tus paquetes y usa su función integrada safe_divide

Error 3: object_construct (creador de JSON)

No se puede resolver la rutina `object_construct`

Solución: Usa la función named_struct de Databricks

Vuelve a ejecutar la compilación:

Se compiló correctamente. Cambios totales de dialecto para este modelo: dbt_utils package installed (para división segura), regexp_substr call converted to regexp_extract, llamada a div0 reemplazada por dbt_utils.safe_divide(), object_construct call converted por named_struct.

Corregir tres funciones a mano es fácil. Un proyecto de dbt real tiene cientos o miles de modelos, y estas brechas de dialecto son exactamente lo que las herramientas de IA resuelven automáticamente. Genie Code convierte SQL específico del dialecto y se encarga de estas correcciones directamente en el editor, para que dediques tu tiempo a revisar las conversiones en lugar de escribir cada una de ellas.

Paso 4: Primera ejecución

Con la compilación en verde, ejecuta el modelo y cualquier prueba que exista:

Tanto la compilación del modelo como las pruebas se completaron correctamente. Consejo profesional:

• Tiempo de ejecución. Anótalo; lo compararás con el warehouse anterior en el siguiente paso.
• Errores de prueba en columnas numéricas. Si las pruebas de equality o accepted_values fallan, casi siempre se debe a la precisión de punto flotante, no a un error de lógica.

Paso 5: Validar fila por fila con el almacén de datos heredado

Un dbt run en verde demuestra que el SQL se ejecuta. Ahora, debemos conciliar los resultados entre el almacén de datos heredado y Databricks. Utilice dbt-audit-helper para comparar fila por fila.

Instalar:

Compare fct_orders en ambos almacenes de datos. En analyses/compare_fct_orders.sql:

Ejecútelo en Databricks (asumiendo que ha replicado el resultado heredado en Databricks para la comparación, o ejecute una comparación entre almacenes de datos):

Resultado esperado:

Nota: Estos ejemplos abarcan los patrones más comunes, pero no son exhaustivos. Para cualquier discrepancia adicional (por ejemplo, recorte de cadenas, intercalación o comportamiento de UDF personalizadas), configure summarize=false para materializar filas de muestra, inspeccione algunas claves primarias donde in_a y in_b difieran, corrija el modelo o la macro, y vuelva a ejecutar hasta obtener una coincidencia del 100 %.

En nuestra ejecución: fct_orders coincidió exactamente.

Paso 6: Implementar en Databricks

En lugar de mantener una capa de orquestación independiente para dbt, puede ejecutar dbt junto con la ingesta ascendente y las acciones descendentes en una sola canalización con Lakeflow Jobs. dbt es un tipo de tarea de primer nivel dentro de Jobs y no necesita un orquestador externo ni una imagen de Docker personalizada.

Crear el Job:

1. Workspace → Jobs & Pipelines → Create Job
2. Tipo de tarea: dbt
3. Origen de Git: su repositorio de dbt
4. Comandos:

5. SQL warehouse: su warehouse de producción
6. Catálogo del warehouse: El catálogo en el que se escribirá la tabla: dev
7. Esquema del warehouse: El esquema en el que se escribirá la tabla: analytics
8. Programación: su frecuencia preferida

Lo que Jobs ofrece listo para usar:

• Totalmente administrado: sin infraestructura adicional que comprar, proteger o mantener
• Capacidad de crear una sola canalización para ejecutar tareas de dbt junto con canalizaciones de ingesta ascendente y tareas descendentes como actualizaciones de Power BI

Paso 7: Transición y desmantelamiento

Una vez que haya validado su proyecto de dbt e implementado en Databricks, el siguiente paso es trasladar el tráfico de producción a Databricks de manera controlada, mantener una ruta de retorno rápida (rollback) y evitar pagar por dos almacenes de datos más tiempo del necesario.

Siga esta lista de verificación:

1. Cambie el destino de producción en profiles.yml para que prod apunte a Databricks; ahora, todas las nuevas ejecuciones de producción escribirán en Databricks.
2. Actualice las credenciales de CI/CD para que las comprobaciones de PR se ejecuten en un catálogo de staging de Databricks, no en el almacén de datos heredado.
3. Monitoree los costos a través de system.billing.usage para confirmar el perfil de gastos de Databricks.
4. Desactive el destino heredado una vez que se cierre la ventana de rollback y tenga la seguridad de que Databricks es estable en producción.

Escalar al resto de su proyecto

La mayor parte del trabajo que acaba de realizar se hace una sola vez: la instalación del adaptador, el destino profiles.yml y el cambio de espacio de nombres de origen. Una vez que estén listos, volver a apuntar el siguiente modelo solo requerirá las correcciones incrementales de dialecto.

Algunos patrones requieren más que un cambio de dialecto, y se encontrará con ellos a medida que escale:

• Modelos incrementales: las estrategias incrementales difieren entre plataformas; es posible que la estrategia que utiliza su origen no se corresponda exactamente (1:1) con una estrategia incremental de Databricks, por lo que deberá volver a seleccionar la estrategia y volver a validar la lógica incremental.
• Snapshots: volverá a apuntar la lógica de snapshot y, por separado, transferirá los datos históricos de snapshot existentes para no perder el historial.
• Funciones semiestructuradas y especializadas: algunas funciones de origen no tienen un equivalente directo en Databricks y requieren una reescritura o una macro, no solo una línea de código.

Para el trabajo más complejo, apóyese en las guías de migración completas.

A partir de ahí, migre en pequeños lotes y trabaje en orden de DAG: primero los orígenes, luego staging, intermedias y marts, de modo que cada lote se valide correctamente con los modelos que ya ha trasladado. Ejecute ambos destinos en paralelo y use audit-helper para comparar cada modelo hasta que todos coincidan. Cuando el último modelo esté en verde, realice la transición de todo el proyecto. Esta guía es un recorrido simplificado para volver a apuntar, mientras que el alcance completo de una migración se cubre en nuestras guías de migración públicas. 

Conclusión

Volver a apuntar dbt a Databricks es una forma práctica y de bajo riesgo de iniciar una migración de almacén de datos. Sus modelos y pruebas siguen siendo los mismos: solo está cambiando dónde se ejecutan, y obtiene formatos y estándares de código abierto como Delta Lake y Apache Iceberg™, con Unity Catalog proporcionando gobernanza y linaje sobre una plataforma que también puede servir para su trabajo de AI descendente. Comience con un modelo, compare los resultados y luego expándalo hasta que se sienta cómodo haciendo de Databricks el hogar principal de su proyecto de dbt.

¿Listo para probarlo? 

1. Configure una prueba gratuita de Databricks
2. Instale el adaptador dbt-databricks
3. Ejecute su primera compilación de dbt en un warehouse de Databricks Lakehouse. Después, implemente un Job de Databricks para ejecutar un modelo de dbt en producción siguiendo la documentación de Databricks.

Para obtener más información sobre dbt con Databricks, explore el adaptador dbt-databricks en GitHub.

(Esta entrada del blog ha sido traducida utilizando herramientas basadas en inteligencia artificial) Publicación original