Macros dbt: Una guía completa

En ingeniería analítica, las macros de dbt (herramienta de creación de datos) proporcionan una forma potente de escribir lógica SQL dinámica y reutilizable a través de bloques de código reutilizables.

En este tutorial, exploraremos los fundamentos de las macros dbt, cómo crearlas utilizando Jinja, las mejores prácticas para su mantenimiento y aplicaciones en el mundo real, todo ello con ejemplos de código.

¿Qué son las macros dbt?

Las macros dbt son bloques de código reutilizables escritos con el lenguaje de plantillas Jinja dentro de dbt, que te permiten generar SQL de forma dinámica. Ayudan a reducir la repetición y a centralizar la lógica de transformación. 

Estas macros funcionan de la misma manera que las funciones en los lenguajes de programación tradicionales.

Por ejemplo, si necesitas calcular una métrica específica en varios modelos, una macro puede encapsular ese cálculo, lo que facilita su mantenimiento y actualización.

Las macros también se pueden almacenar en paquetes, como dbt-utils.

¿Por qué utilizar macros dbt?

Las macros aportan varias ventajas, principalmente:

• Reducir la redundancia: Puedes escribir un bloque lógico una vez y reutilizarlo en cualquier lugar.
• Coherencia: Aplicar la misma lógica de transformación en todos los modelos sin necesidad de duplicarla manualmente.
• Flexibilidad: Las macros admiten parámetros, lo que las hace adaptables a diversas entradas.
• Intercambio entre proyectos: Las macros bien diseñadas se pueden compartir como paquetes.

Estas ventajas dan lugar a bases de código más limpias, fáciles de mantener y escalables.

Conceptos fundamentales de dbt Macro

Para ayudarte a comprender cómo funcionan las macros en dbt, veamos algunos conceptos clave.

1. Reutilización

Las macros te permiten definir una parte de la lógica SQL una sola vez y reutilizarla en múltiples modelos, pruebas o incluso otras macros.

2. Motor de plantillas Jinja

La integración de Jinja con dbt permite insertar variables, aplicar condiciones y realizar bucles sobre listas, todo ello antes de que tu SQL llegue a la base de datos. dbt compila esta plantilla en SQL sin procesar, lo que hace que las macros sean independientes de la base de datos.

3. Introducción a las técnicas de programación

Las macros pueden transformar SQL en un marco programable. Permiten lógica, bucles y condiciones, elementos comunes que el SQL estándar no puede manejar con tanta flexibilidad.

Al igual que las funciones, las macros en dbt pueden aceptar argumentos (parámetros) y pueden invocarse con diferentes entradas para producir diferentes salidas. Ayudan a simplificar transformaciones complejas al dividirlas en unidades más pequeñas y reutilizables. 

Creación de macros con Jinja

A continuación, veamos cómo podemos crear algunas macros para nosotros mismos.

Jinja es el motor de plantillas que impulsa las macros dbt, lo que te permite tratar el SQL como texto dinámico y programable. 

Construcciones de plantillas y delimitadores

Para utilizar Jinja, necesitarás utilizar construcciones y delimitadores de plantillas específicos.

A continuación se muestran algunas construcciones y delimitadores comunes:

• Expresiones {{ }}: Inserta expresiones.
• Declaraciones {% %}: Ejecuta sentencias.
• Comentarios {# #}: Añade comentarios que deseas que dbt ignore.

En las macros, {{ ... }} se utiliza para expresiones que deben generar un valor (por ejemplo, nombres de columnas o cálculos), mientras que {% ... %} se utiliza para el flujo de control (bucles, sentencias if/else, definiciones de macros). Los comentarios Jinja utilizan {# ... #} y se eliminan por completo durante la compilación.

A continuación se muestra un ejemplo de la sintaxis utilizada para las instrucciones empleadas en las macros:

{% macro your_macro_name(your_variable) %}
    select 'Hello, {{ your_variable}}' as greeting
{% endmacro %}

A continuación se muestra un ejemplo de cómo utilizar sentencias para crear una macro:

{% macro greet(name) %}
    select 'Hello, {{ name }}' as greeting
{% endmacro %}

Para ejecutar la macro, utiliza esto:

dbt run-operation greet(name) --args 'Austin'

Gestión de variables

Puedes pasar variables a las macros o definirlas dentro de ellas. Los filtros como upper o lower pueden transformar valores de texto.

Aquí tienes una implementación de la función upper para cambiar todos los valores de texto a mayúsculas. 

{% macro to_upper_case(column_name) %}
    upper({{ column_name }})
{% endmacro %}

Para implementar esto, tendrías que llamar/referenciar la macro recién creada en tu modelo dbt.

Aquí tienes un ejemplo de código:

SELECT
    id,
    {{ to_upper_case('product_name') }} AS product_name_upper
FROM {{ source('public', 'orders') }}

Estructuras de control

A continuación, al igual que los lenguajes de programación, las macros dbt pueden ofrecer lo siguiente:

• Sentencias condicionales ({% if %} / {% endif %}):
• Loops ({% for %} / {% endfor %}) 

Estas estructuras te permiten crear cláusulas SQL de forma dinámica o generar múltiples expresiones basadas en entradas.

Esto facilita que las macros manejen tareas complejas de generación de SQL.

Manejo de parámetros y gestión de errores

Las macros pueden validar entradas y generar errores en tiempo de compilación para evitar problemas en tiempo de ejecución.

Los parámetros se definen dentro de la declaración de la macro utilizando paréntesis () es, de forma similar a las definiciones de funciones en los lenguajes de programación.

Aquí tienes un ejemplo de cómo podemos incluir dos parámetros:

{% macro my_macro(param1, param2) %}
    SELECT
        {{ param1 }},
        {{ param2 }}
    FROM my_table
{% endmacro %}

Como puedes ver, en la primera línea hemos incluido tanto param1 como param2.

Para invocar la macro en un modelo dbt, debes utilizar llaves dobles {{ }}. Los parámetros se pasan como argumentos dentro de los paréntesis.

SELECT
    id,
    {{ my_macro('column_a', 'column_b') }}
FROM my_source_table

En este caso, especificamos tanto column_a como column_b como nuestros parámetros.

Guía de configuración para trabajar con macros dbt

Antes de empezar a crear y utilizar macros, vamos a configurar un entorno de trabajo para que puedas seguir los ejemplos de este tutorial. 

Esto garantizará que tengas instalado dbt, un conjunto de datos de muestra cargado y la estructura de carpetas adecuada para crear macros.

1. Instalar dbt Core

Necesitarás tener instalado dbt Core localmente. Si utilizas Postgres en este tutorial, instálalo con este comando:

pip install dbt

Si tu proyecto utiliza un almacén de datos, ejecuta los comandos correspondientes:

pip install dbt-core dbt-postgres

pip install dbt-core dbt-snowflake

pip install dbt-core dbt-bigquery

2. Crear un proyecto dbt

Antes de ejecutar cualquier comando dbt, tendrás que configurar un entorno de proyecto.

Ve al directorio de proyectos que desees.

Aquí es donde almacenarás tus archivos de proyecto dbt. En este caso, almacenaremos todos los archivos relacionados en esta carpeta del proyecto dbt.

Para inicializar un proyecto dbt, deberás ejecutar:

dbt init

cd ~/dbt-macros-tutorial

Crea una estructura de carpetas con este formato:

macros_tutorial/
  ├─ models/
  ├─ macros/
  ├─ tests/
  ├─ seeds/
  ├─ dbt_project.yml

3. Prepara el conjunto de datos de muestra.

Usaremos Python para generar un pequeño conjunto de datos de pedidos que cargaremos en Postgres (o en el almacén que elijas).

import pandas as pd
import random
from datetime import datetime, timedelta
from sqlalchemy import create_engine

# Create sample orders dataframe
random.seed(42)
num_rows = 20
start_date = datetime(2025, 1, 1)

data = []
for i in range(1, num_rows + 1):
    order_date = start_date + timedelta(days=random.randint(0, 30))
    ship_date = order_date + timedelta(days=random.randint(1, 10))
    data.append({
        'order_id': i,
        'customer_id': random.randint(100, 105),
        'order_date': order_date.date(),
        'ship_date': ship_date.date(),
        'status': random.choice(['pending', 'shipped', 'delivered']),
        'revenue': round(random.uniform(50, 500), 2),
        'cost': round(random.uniform(20, 400), 2)
    })

df = pd.DataFrame(data)

# Load into Postgres
engine = create_engine('postgresql://user:password@localhost:5432/dbt_demo')
df.to_sql('orders', engine, if_exists='replace', index=False)

Nota: Actualiza la cadena de conexión de tu base de datos.

4. Crear una fuente en dbt

Añade lo siguiente a models/src_orders.yml:

version: 2
sources:
  - name: public
schema: public

    tables:
      - name: orders

5. Comprueba la conexión y la fuente

dbt debug

dbt run-operation list_relations --args '{"schema_name": "public"}'

Ahora estás listo para empezar a escribir macros que operen con este conjunto de datos.

Cómo escribir y utilizar macros dbt

Ahora, probemos a escribir algunas macros propias.

Definición de macros

Coloca las definiciones de macros en archivos .sql dentro del directorio macros/.

Al nombrar las macros, asegúrate de dar a cada una un nombre descriptivo que refleje su finalidad y utiliza parámetros para que sean flexibles. Añadir un breve comentario docstring al principio ayuda a tus compañeros de equipo a comprender su intención.

Aquí tienes un ejemplo:

    -- macros/my_macro.sql
    {% macro cents_to_dollars(column_name, precision=2) %}
        ({{ column_name }} / 100.0)::numeric(18, {{ precision }})
    {% endmacro %}

Invocar macros en modelos

Las macros se invocan dentro de los modelos con {{ macro_name(arg1, arg2) }}. Se pueden utilizar en cláusulas SELECT, filtros WHERE o incluso bloques CTE completos, lo que te permite insertar patrones SQL reutilizables en cualquier lugar.

Aquí tienes un ejemplo:

    -- models/my_model.sql
    SELECT
        order_id,
        {{ cents_to_dollars('amount_in_cents') }} AS amount_in_dollars,
        {{ cents_to_dollars('tax_in_cents', precision=4) }} AS tax_in_dollars
    FROM {{ ref('raw_orders') }}

Invocar macros desde la CLI

Para tareas operativas fuera de la creación de modelos, utiliza este formato/sintaxis:

dbt run-operation macro_name --args '{"param": "value"}'

Esto te permite ejecutar utilidades SQL, como la creación de esquemas o la limpieza de datos, sin necesidad de crear un modelo.

Aquí tienes un ejemplo de comando:

dbt run-operation greet --args '{"name": "Austin"}'

Uso de macros de paquetes

Las macros también pueden provenir de paquetes en dbt, como dbt-utils.

Cuando instalas un paquete a través de packages.yml, sus macros están disponibles de inmediato. Para ello, deberás ejecutar dbt deps.

A continuación, puedes llamar a las macros recién añadidas con este formato: package_name.macro_name.

Organización de archivos macro

Para una mejor organización, ordena y separa las macros por funcionalidad para mejorar su mantenimiento. 

Intenta agrupar las macros relacionadas en archivos separados (por ejemplo, date_utils.sql, string_utils.sql) para facilitar el mantenimiento. Esto facilita la localización y actualización de la lógica a lo largo del tiempo.

Ejemplos de macros dbt en la práctica

A continuación, se muestran algunos ejemplos de macros en casos de uso más prácticos:

Macro de comparación de fechas

Supongamos que quieres crear una función que utilizarás a menudo para comparar fechas.

En este caso, puedes utilizar una macro para calcular las diferencias de días entre dos campos de fecha mientras gestionas las diferencias entre dialectos SQL.

Empieza creando un nuevo archivo aquí: macros/date_utils.sql.

A continuación, utiliza el siguiente código:

{% macro days_between(start_col, end_col) %}
    {#-- Handle different warehouses --#}
    {% if target.type in ['postgres', 'redshift'] %}
        (DATE_PART('day', {{ end_col }}::timestamp - {{ start_col }}::timestamp))
    {% elif target.type in ['snowflake'] %}
        DATEDIFF('day', {{ start_col }}, {{ end_col }})
    {% elif target.type in ['bigquery'] %}
        DATE_DIFF(CAST({{ end_col }} AS DATE), CAST({{ start_col }} AS DATE), DAY)
    {% else %}
        -- Fallback to ANSI-ish expression; may need adjustment per engine
        CAST({{ end_col }} AS DATE) - CAST({{ start_col }} AS DATE)
    {% endif %}
{% endmacro %}

Ahora, utilizaremos esta nueva macro days_between en un modelo.

with src as (
  select * from {{ source('public', 'orders') }}
)
select
  order_id,
  customer_id,
  order_date,
  ship_date,
  {{ days_between('order_date', 'ship_date') }} as days_to_ship
from src

Personalizado generate_schema_name macro

Por defecto, dbt utiliza una macro predeterminada llamada « generate_schema_name ». Esta macro se utiliza para especificar el nombre del esquema en el que se debe construir un modelo.

También puedes anular la configuración predeterminada de dbt para controlar el esquema utilizado por cada entorno.

Puedes incluir este archivo en la ubicación: macros/generate_schema_name.sql.

`sql
{% macro generate_schema_name(custom_schema_name, node) -%}
    {# Policy:
       - prod:    ANALYTICS
       - nonprod: dev_analytics, ci_analytics, etc.
    #}
    {%- if target.name == 'prod' -%}
        {{ custom_schema_name | trim }}
    {%- else -%}
        {{ (target.name ~ '_' ~ custom_schema_name) | lower | replace(' ', '_') }}
    {%- endif -%}
{%- endmacro %}

Cómo ayuda: En dev, los modelos aterrizan en el entorno de aislamiento ( dev_analytics ). En prod, aterrizan en analytics. Esto permite realizar implementaciones predecibles y sin colisiones.

Ejecutar SQL fuera de un modelo

También puedes ejecutar comandos SQL fuera de los modelos para operaciones como la limpieza de tablas o la actualización de metadatos sin necesidad de crear modelos.

Puedes escribir una macro que ejecute SQL sin procesar y luego ejecutarla a través de dbt run-operation.

Esto resulta útil para DDL (eliminar/crear tablas) o actualizaciones de metadatos que no encajan en un modelo.

Aquí está la macro:

{% macro cleanup_temp_tables() %}
    {% set sql %}
        drop table if exists {{ target.schema }}.temp_table;
        delete from {{ target.schema }}.audit_log where event_type = 'test';
    {% endset %}
    {{ run_query(sql) }}
{% endmacro %}

A continuación, ejecuta esta operación en el terminal:

dbt run-operation cleanup_temp_tables

Esto te permitirá ejecutar macros sin incluirlas en los modelos.

Ejemplo de macro parametrizada

También podemos crear una macro altamente parametrizada, como en una función. 

En este ejemplo, filtraremos los registros en función de un estado determinado, que es cuando se proporcionan valores. Esto utiliza las instrucciones « if » y « do » para crear lógica.

{% macro where_orders(status=None, min_date=None, max_date=None) %}
  {%- set clauses = [] -%}
  {%- if status is not none -%}
    {%- do clauses.append("status = '" ~ status ~ "'") -%}
  {%- endif -%}
  {%- if min_date is not none -%}
    {%- do clauses.append("order_date >= '" ~ min_date ~ "'") -%}
  {%- endif -%}
  {%- if max_date is not none -%}
    {%- do clauses.append("order_date < '" ~ max_date ~ "'") -%}
  {%- endif -%}
  {%- if clauses | length > 0 -%}
    where {{ clauses | join(' and ') }}
  {%- endif -%}
{% endmacro %}

Ahora aplicamos esta macro en un modelo:

with src as (
  select * from {{ ref('orders') }}
)
select *
from src
{{ where_orders(status='shipped', min_date='2025-01-05') }}

Esta macro incorpora una lógica para cuando se omite un argumento; ese criterio se ignora. Esto mantiene ordenada la lógica opcional.

Prácticas recomendadas para macros dbt

Diseñar macros excelentes es mucho más que conseguir que el SQL se compile. Las mejores macros son fáciles de encontrar, están bien documentadas, son predecibles, se pueden probar y son fáciles de descartar o ampliar. 

A continuación, se indican algunas prácticas recomendadas que debes seguir:

1. Convenciones de nomenclatura y diseño de parámetros

Al igual que con SQL y los lenguajes de programación, es necesario seguir las convenciones de nomenclatura para garantizar la legibilidad.

Aquí tienes algunos consejos para elegir nombres:

• Sé explícito y orientado a la acción. Es preferible utilizar verbos o intenciones claras (por ejemplo, generate_select_list, where_orders) en lugar de nombres vagos como helper.
• Mantén los nombres estables y en minúsculas. Utiliza snake_case y prefijos estables por dominio, por ejemplo, date_*, string_*, test_*, admin_*.

2. Estrategias de documentación

Debes desarrollar hábitos que te ayuden a documentar lo que creas. La documentación debe realizarse en lugares donde los desarrolladores puedan consultarla. 

Por ejemplo, combina cadenas de documentación en línea + un macros.yml (o schema.yml) con descripciones y ejemplos.

El contenido de la documentación puede incluir:

• Objetivo y resultados esperados (1-2 frases)
• Tabla de parámetros con valores predeterminados y valores permitidos
• Breve ejemplo de invocación en un modelo y con run-operation
• Notas sobre el comportamiento entre bases de datos

Ejemplo de fragmento de un archivo de configuración:

version: 2
macros:
  - name: days_between
    description: |
      Return day difference between two date expressions, normalized across warehouses.
    arguments:
      - name: start_col
        type: string
        description: Column/expression for the start date
      - name: end_col
        type: string
        description: Column/expression for the end date
    docs:
      show: true

3. Organización del código

Tu código también deberá estar bien organizado, especialmente cuando tengas que gestionar un gran número de macros en tu directorio.

Intenta estructurar por dominio para facilitar su uso. Aquí hay algunos ejemplos de eso:

• macros/date_utils.sql
• macros/string_utils.sql
• macros/testing/ (pruebas personalizadas)
• macros/admin/ (DDL, tareas domésticas)
• macros/compat/ (cuñas de almacén)

4. Mantén las macros pequeñas y con un único propósito.

Una macro debe hacer bien una sola cosa. Si observas que una macro se está volviendo demasiado grande o maneja lógica no relacionada, divídela en macros más pequeñas. Esto mejora la reutilización y hace que las pruebas sean más sencillas.

5. Prueba las macros con datos representativos.

Utiliza modelos de prueba específicos o un entorno de ensayo para validar el comportamiento de las macros. 

Por ejemplo:

• Crea un pequeño conjunto de datos inicial que cubra los casos extremos.
• Escribe un modelo de prueba que llame a la macro con diferentes parámetros.
• Utiliza dbt run y comprueba que el SQL compilado sea correcto.

Consejo profesional: Combina macros con pruebas personalizadas de dbt test para verificar que los resultados cumplan con las restricciones esperadas.

Casos de uso y aplicaciones comunes

Las macros dbt son versátiles y sus aplicaciones se extienden a muchos flujos de trabajo cotidianos de ingeniería analítica. 

A continuación, se incluyen algunos ejemplos ampliados y detallados:

• Estandarización de las transformaciones de datos: Las macros pueden garantizar que se apliquen las mismas convenciones de nomenclatura, recorte, manejo de valores nulos y lógica de conversión de tipos a varios modelos. Por ejemplo, puedes crear una macro standardize_customer_name para limpiar y formatear los nombres de forma idéntica en todos los mercados.
• Compatibilidad con consultas entre bases de datos: Los almacenes presentan sutiles diferencias en el dialecto SQL. Las macros pueden abstraer esas diferencias, como usar DATEDIFF en Snowflake y DATE_DIFF en BigQuery. Esto hace que tus modelos sean portátiles.
• Automatización de los controles de calidad: Escribe macros reutilizables que generen pruebas de datos, como la comprobación de ID duplicados, columnas críticas nulas o valores fuera de rango. Se pueden invocar en múltiples modelos de prueba.
• Simplificación de patrones SQL repetitivos: Los CTE comunes, los campos calculados o las cláusulas de filtrado se pueden parametrizar en macros. Por ejemplo, una macro para crear cláusulas dinámicas WHERE basadas en filtros opcionales evita tener que copiar y pegar lógica compleja.

Técnicas avanzadas y optimización del rendimiento

Las macros dbt también se pueden utilizar en aplicaciones más avanzadas. Veamos dos formas comunes a continuación.

Patrones recursivos y de metaprogramación

Las macros pueden llamar a otras macros, recorrer metadatos o generar fragmentos SQL de forma dinámica basándose también en la inspección del esquema. 

Esto te permite:

• Crear automáticamente modelos de ensayo para cada tabla de origen.
• Genera consultas pivotantes/no pivotantes sin tener que escribir manualmente cada columna.
• Crea consultas sensibles al entorno mediante bucles a través de variables de configuración.

Estrategias de optimización del rendimiento

También puedes realizar otras optimizaciones para ayudarte a mejorar el rendimiento:

• Minimiza la complejidad de las consultas incluyendo de forma selectiva solo las columnas o uniones necesarias.
• Ajusta las materializaciones o las estrategias SQL en función del tipo de almacén.

Integración con el ecosistema dbt

Las macros se crean para formar parte del ecosistema dbt, lo que las hace aún más potentes cuando se combinan con paquetes, funciones de nube y herramientas externas.

Gestión de paquetes

Muchos paquetes dbt comunitarios, como dbt-utils, dbt-date y dbt-expectations, son esencialmente colecciones de macros altamente reutilizables. 

Estos paquetes incluyen transformaciones, pruebas y ayudantes preconstruidos sin necesidad de reinventar la rueda. 

Compatibilidad con dbt Cloud y herramientas de programadores

Las macros funcionan a la perfección en entornos dbt Cloud, lo que significa que tu lógica SQL dinámica se comporta de la misma manera tanto si se ejecuta localmente como en una tarea programada en la nube. 

También se integran bien con el control de versiones, los procesos de CI/CD y los procesos de revisión de código, lo que garantiza que las actualizaciones macro se prueben e implementen de forma coherente.

Estrategias de implementación en el mundo real

Pasar de los scripts SQL tradicionales a un flujo de trabajo dbt basado en macros requiere tanto cambios técnicos como una adopción cultural.

Migración y gestión del cambio

Al realizar la migración, empieza por identificar los patrones SQL repetidos en todos los modelos. A continuación, refactorízalos en macros de forma incremental, validando que el SQL compilado coincida con la lógica anterior. 

Utiliza indicadores de funciones (var()) para activar o desactivar la nueva lógica macro durante la implementación, minimizando así las interrupciones. Lo más importante es que quieras que tus partes interesadas estén informadas de los cambios para evitar interrumpir las consultas posteriores.

Estrategias de gobernanza y despliegue

En cuanto a la gobernanza, empieza por establecer convenciones de nomenclatura claras, normas para los parámetros y requisitos de documentación para todas las macros.

A continuación, revisa los cambios macro en las solicitudes de extracción, al igual que las actualizaciones de modelos, asegurándote de que cumplan con los estándares de rendimiento y compatibilidad. 

En producción, supervisa los registros de trabajo de las consultas generadas por macros para verificar que se ejecutan según lo previsto. Para proyectos con gran cantidad de macros, configura paneles de observabilidad para programar el seguimiento de los tiempos de compilación y el rendimiento de las consultas por tipo de macro.

Conclusión

Las macros dbt son una parte fundamental de la productividad y la facilidad de mantenimiento en los equipos modernos de ingeniería analítica. El uso de modelos dbt junto con macros puede dar lugar a mejores resultados en las operaciones de limpieza de datos.

¿Quieres saber más sobre dbt? Nuestra Introducción a dbt y el Tutorial de dbt pueden resultarte útiles.