dbt-macro’s: een uitgebreide gids

In analytics engineering bieden dbt (data build tool)-macro’s een krachtige manier om dynamische, herbruikbare SQL-logica te schrijven via herbruikbare codeblokken. 

In deze tutorial bekijken we de basis van dbt-macro’s, hoe je ze bouwt met Jinja, best practices voor onderhoudbaarheid, en toepassingen in de praktijk, allemaal met codevoorbeelden. 

Wat zijn dbt-macro’s?

dbt-macro’s zijn herbruikbare codeblokken die met de Jinja-templatingtaal binnen dbt worden geschreven, waarmee je SQL dynamisch kunt genereren. Ze helpen herhaling te verminderen en transformatielogica te centraliseren. 

Deze macro’s werken hetzelfde als functies in traditionele programmeertalen.

Als je bijvoorbeeld een specifieke metriek in meerdere modellen moet berekenen, kan een macro die berekening inkapselen, zodat onderhoud en updates eenvoudiger worden.

Macro’s kunnen ook in packages worden opgeslagen, zoals dbt-utils.

Waarom dbt-macro’s gebruiken?

Macro’s bieden meerdere voordelen, vooral:

• Minder redundantie: Je schrijft een logica-blok één keer en hergebruikt het overal.
• Consistentie: Dezelfde transformatielogica toepassen in modellen zonder handmatig te dupliceren.
• Flexibiliteit: Macro’s ondersteunen parameters, waardoor ze zich aan verschillende inputs kunnen aanpassen.
• Delen tussen projecten: Goed ontworpen macro’s kun je als packages delen.

Deze voordelen leiden tot schonere, beter onderhoudbare en schaalbare codebases.

Fundamentele concepten van dbt-macro’s

Om te begrijpen hoe macro’s in dbt werken, bekijken we enkele kernconcepten.

1. Herbruikbaarheid

Met macro’s definieer je een stuk SQL-logica één keer en hergebruik je het in meerdere modellen, tests of zelfs andere macro’s.

2. Jinja-templatingengine

Dankzij de integratie van Jinja met dbt kun je variabelen invoegen, condities toepassen en over lijsten loopen, allemaal voordat je SQL de database bereikt. dbt compileert deze template naar ruwe SQL, waardoor macro’s database-agnostisch zijn.

3. Introductie van programmeertechnieken

Macro’s kunnen SQL omvormen tot een programmeerbaar raamwerk. Ze maken logica, loops en condities mogelijk—gebruikelijke zaken die standaard SQL minder flexibel aankan.

Net als functies kunnen dbt-macro’s argumenten (parameters) accepteren en met verschillende inputs worden aangeroepen om verschillende outputs te produceren. Ze helpen complexe transformaties te vereenvoudigen door ze op te delen in kleinere, herbruikbare onderdelen. 

Macro’s bouwen met Jinja

Laten we vervolgens bekijken hoe we zelf macro’s kunnen bouwen.

Jinja is de templatingengine achter dbt-macro’s, waarmee je SQL als dynamische, programmeerbare tekst kunt behandelen. 

Templateconstructies en delimiters

Om Jinja te gebruiken, moet je specifieke templateconstructies en delimiters gebruiken.

Hier zijn enkele veelgebruikte constructies en delimiters:

• Expressies {{ }}: Voegt expressies in.
• Statements {% %}: Voert statements uit.
• Comments {# #}: Voegt opmerkingen toe die je wilt dat dbt negeert.

In macro’s gebruik je {{ ... }} voor expressies die een waarde moeten opleveren (bijv. kolomnamen of berekeningen), terwijl {% ... %} wordt gebruikt voor control flow (loops, if/else-statements, macrodefinities). Jinja-opmerkingen gebruiken {# ... #} en worden tijdens het compileren volledig verwijderd.

Hier is een voorbeeld van de syntaxis die wordt gebruikt voor statements in macro’s:

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

Hier is een voorbeeld van hoe je statements gebruikt om een macro te maken:

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

Voer de macro uit met:

dbt run-operation greet(name) --args 'Austin'Mogelijk gemaakt door

Variabelen beheren

Je kunt variabelen aan macro’s doorgeven of binnenin definiëren. Filters zoals upper of lower kunnen tekstwaarden transformeren.

Hier is een implementatie van de upper-functie om alle tekstwaarden naar hoofdletters te zetten. 

{% macro to_upper_case(column_name) %}
    upper({{ column_name }})
{% endmacro %}Mogelijk gemaakt door

Om dit te gebruiken, verwijs je in je dbt-model naar de nieuw aangemaakte macro.

Hier is een codevoorbeeld:

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

Controlestructuren

Net als in programmeertalen kunnen dbt-macro’s het volgende bieden:

• Conditionele statements ({% if %} / {% endif %}):
• Loops ({% for %} / {% endfor %}) 

Met deze structuren kun je dynamisch SQL-clausules opbouwen of meerdere expressies genereren op basis van inputs.

Dit maakt het voor macro’s eenvoudiger om complexe SQL-generatietaken af te handelen.

Parameterafhandeling en foutbeheer

Macro’s kunnen inputs valideren en compile-time fouten genereren om runtime-problemen te voorkomen.

Parameters definieer je binnen de macrodeclaratie met ()-haakjes, vergelijkbaar met functiedefinities in programmeertalen.

Hier is een voorbeeld van twee parameters:

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

Zoals je ziet hebben we in de eerste regel zowel param1 als param2 opgenomen.

Om de macro in een dbt-model aan te roepen, gebruik je dubbele accolades {{ }}. De parameters geef je door als argumenten tussen de haakjes.

SELECT
    id,
    {{ my_macro('column_a', 'column_b') }}
FROM my_source_tableMogelijk gemaakt door

In dit geval hebben we zowel column_a als column_b als onze parameters opgegeven.

Stappenplan om met dbt-macro’s te werken

Voordat we macro’s gaan bouwen en gebruiken, richten we een werkomgeving in zodat je de voorbeelden in deze tutorial kunt volgen. 

Dit zorgt ervoor dat je dbt hebt geïnstalleerd, een voorbeeld-dataset hebt geladen en de juiste mapstructuur hebt om macro’s te maken.

1. Installeer dbt Core

Je hebt dbt Core lokaal nodig. Als je in deze tutorial Postgres gebruikt, installeer dan met dit commando:

pip install dbtMogelijk gemaakt door

Als je project een data warehouse gebruikt, voer dan in plaats daarvan de betreffende commando’s uit:

pip install dbt-core dbt-postgres

pip install dbt-core dbt-snowflake

pip install dbt-core dbt-bigqueryMogelijk gemaakt door

2. Maak een dbt-project

Voordat we dbt-commando’s uitvoeren, moeten we een projectomgeving opzetten.

Navigeer naar je gewenste projectmap.

Hier sla je je dbt-projectbestanden op. In dit geval bewaren we alle gerelateerde bestanden in deze dbt-projectmap.

Initialiseer een dbt-project met:

dbt initMogelijk gemaakt door

cd ~/dbt-macros-tutorialMogelijk gemaakt door

Maak een mapstructuur in dit formaat:

macros_tutorial/
  ├─ models/
  ├─ macros/
  ├─ tests/
  ├─ seeds/
  ├─ dbt_project.ymlMogelijk gemaakt door

3. Bereid de voorbeeld-dataset voor

We gebruiken Python om een kleine orders-dataset te genereren en te laden in Postgres (of het door jou gekozen warehouse).

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)Mogelijk gemaakt door

Let op: Werk de connectiestring bij voor jouw database.

4. Maak een source in dbt

Voeg het volgende toe aan models/src_orders.yml:

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

    tables:
      - name: ordersMogelijk gemaakt door

5. Test de verbinding en de source

dbt debug

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

Je kunt nu beginnen met het schrijven van macro’s die op deze dataset werken.

Hoe dbt-macro’s te schrijven en te gebruiken

Laten we nu zelf wat macro’s schrijven.

Macro’s definiëren

Plaats macrodefinities in .sql-bestanden onder de map macros/.

Geef macro’s een beschrijvende naam die hun doel weergeeft en gebruik parameters om ze flexibel te maken. Een korte docstring bovenaan helpt teammates de bedoeling te begrijpen.

Voorbeeld:

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

Macro’s aanroepen in modellen

Je roept macro’s binnen modellen aan met {{ macro_name(arg1, arg2) }}. Je kunt ze gebruiken in SELECT-clausules, WHERE-filters of zelfs volledige CTE-blokken, zodat je herbruikbare SQL-patronen overal kunt injecteren.

Hier is een voorbeeld:

    -- 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') }}Mogelijk gemaakt door

Macro’s aanroepen vanaf de CLI

Voor operationele taken buiten modelbuilds gebruik je dit format/deze syntaxis:

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

Zo kun je utility-SQL uitvoeren, zoals het aanmaken van schema’s of opschonen van data, zonder een model te bouwen.

Hier is een voorbevel:

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

Macro’s uit packages gebruiken

Macro’s kunnen ook uit dbt-packages komen, zoals dbt-utils.

Wanneer je een package via packages.yml installeert, zijn de macro’s direct beschikbaar. Hiervoor moet je dbt deps uitvoeren.

Je kunt de nieuw toegevoegde macro’s dan aanroepen met dit format: package_name.macro_name.

Organisatie van macrobestanden

Voor een betere organisatie, sorteer en scheid macro’s op functionaliteit om de onderhoudbaarheid te verbeteren. 

Probeer verwante macro’s te groeperen in aparte bestanden (bijv. date_utils.sql, string_utils.sql) voor onderhoudbaarheid. Zo vind en update je logica makkelijker in de tijd.

Voorbeelden van dbt-macro’s in de praktijk

Hier zijn enkele voorbeelden van macro’s in praktijksituaties:

Datumvergelijkingsmacro

Stel, je wilt een functie maken die je vaak gebruikt om datums te vergelijken.

In dat geval kun je een macro gebruiken om het aantal dagen tussen twee datumvelden te berekenen en tegelijk verschil in SQL-dialecten af te handelen.

Begin met een nieuw bestand: macros/date_utils.sql.

Gebruik vervolgens de volgende code:

{% 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 %}Mogelijk gemaakt door

Nu gebruiken we deze nieuwe days_between-macro in een model.

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 srcMogelijk gemaakt door

Aangepaste generate_schema_name-macro

Standaard gebruikt dbt een standaardmacro genaamd generate_schema_name. Deze macro specificeert de naam van het schema waarin een model moet worden gebouwd.

Je kunt de dbt-standaard ook overschrijven om het schema per omgeving te bepalen.

Je kunt dit bestand opnemen op: 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 %}Mogelijk gemaakt door

Hoe dit helpt: Op dev landen modellen in de dev_analytics- (isolatie)omgeving. Op prod landen ze in analytics. Dit zorgt voor voorspelbare, conflictvrije deployments.

SQL uitvoeren buiten een model

Je kunt ook SQL-commando’s buiten modellen uitvoeren voor operaties zoals het opschonen van tabellen of metadata-updates zonder modellen te maken.

Je kunt een macro schrijven die ruwe SQL uitvoert en deze vervolgens draaien via dbt run-operation.

Dit is handig voor DDL (tabellen droppen/aanmaken) of metadata-updates die niet in een model passen.

Hier is de 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 %}Mogelijk gemaakt door

Voer vervolgens deze bewerking uit in de terminal:

dbt run-operation cleanup_temp_tablesMogelijk gemaakt door

Zo kun je macro’s uitvoeren zonder ze in modellen op te nemen.

Geparametriseerd macrovoorbeeld

We kunnen ook een macro maken die sterk geparametriseerd is, net als een functie. 

In dit voorbeeld filteren we records op basis van een opgegeven status, wanneer waarden worden meegegeven. Dit gebruikt if- en do-statements om logica te creëren.

{% 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 %}Mogelijk gemaakt door

Nu passen we deze macro toe in een model:

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

Deze macro bouwt logica in voor wanneer een argument wordt weggelaten; dat criterium wordt genegeerd. Zo blijft optionele logica overzichtelijk.

Best practices voor dbt-macro’s

Geweldige macro’s ontwerpen is meer dan SQL laten compileren. De beste macro’s zijn vindbaar, goed gedocumenteerd, voorspelbaar, testbaar en eenvoudig uit te faseren of uit te breiden. 

Hier zijn enkele best practices om te volgen:

1. Naamgevingsconventies en parameterontwerp

Net als in SQL en programmeertalen moeten naamgevingsconventies worden gevolgd om de leesbaarheid te waarborgen.

Enkele naamgevingstips:

• Wees expliciet en actiegericht. Geef de voorkeur aan werkwoorden of duidelijke intenties (bijv. generate_select_list, where_orders) boven vage namen zoals helper.
• Houd namen stabiel en in lowercase. Gebruik snake_case en stabiele prefixen per domein, bijv. date_*, string_*, test_*, admin_*.

2. Documentatiestrategieën

Ontwikkel gewoontes om te documenteren wat je maakt. Documenteer op plekken waar devs kijken. 

Combineer bijvoorbeeld inline docstrings + een macros.yml (of schema.yml) met beschrijvingen en voorbeelden.

Documentatie kan bevatten:

• Doel en verwachte output (1–2 zinnen)
• Parametertabel met defaults en toegestane waarden
• Kort voorbeeld van aanroep in een model en met run-operation
• Opmerkingen over gedrag tussen databases

Voorbeeldfragment van een configbestand:

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: trueMogelijk gemaakt door

3. Codeorganisatie

Je code moet ook goed georganiseerd zijn, zeker als je veel macro’s in je map moet beheren.

Structureer bij voorkeur per domein voor gebruiksgemak. Enkele voorbeelden:

• macros/date_utils.sql
• macros/string_utils.sql
• macros/testing/ (aangepaste tests)
• macros/admin/ (DDL, housekeeping)
• macros/compat/ (warehouse-shims)

4. Houd macro’s klein en met één doel

Een macro moet één ding goed doen. Als een macro te groot wordt of niet-verwante logica afhandelt, splits hem dan op in kleinere macro’s. Dit verbetert herbruikbaarheid en maakt testen eenvoudiger.

5. Test macro’s met representatieve data

Gebruik speciale testmodellen of een stagingomgeving om macrogedrag te valideren. 

Bijvoorbeeld:

• Maak een kleine seed-dataset die randgevallen dekt.
• Schrijf een testmodel dat de macro met verschillende parameters aanroept.
• Gebruik dbt run en inspecteer de gecompileerde SQL op correctheid.

Pro tip: Koppel macro’s aan aangepaste dbt test-tests om te verifiëren dat de outputs aan de verwachte constraints voldoen.

Veelvoorkomende use-cases en toepassingen

dbt-macro’s zijn veelzijdig en hun toepassingen strekken zich uit tot veel dagelijkse analytics engineering-workflows. 

Hier zijn enkele uitgebreidere voorbeelden:

• Transformaties standaardiseren: Macro’s kunnen overal dezelfde naamgevingsconventies, trimming, null-afhandeling en typecasting toepassen. Zo kun je bijvoorbeeld een standardize_customer_name-macro maken om namen overal in dezelfde vorm te gieten.
• Cross-database queries ondersteunen: Warehouses hebben subtiele SQL-dialectverschillen. Macro’s kunnen die verschillen abstraheren—zoals DATEDIFF op Snowflake en DATE_DIFF op BigQuery. Dit maakt je modellen draagbaar.
• Kwaliteitscontroles automatiseren: Schrijf herbruikbare macro’s die datatests genereren, zoals het controleren op dubbele ID’s, nulls in kritieke kolommen of waarden buiten bereik. Deze kun je in meerdere testmodellen aanroepen.
• Repetitieve SQL-patronen vereenvoudigen: Veelvoorkomende CTE’s, berekende velden of filterclausules kun je parametriseren in macro’s. Een macro om dynamische WHERE-clausules te bouwen op basis van optionele filters voorkomt het kopiëren en plakken van complexe logica.

Geavanceerde technieken en performance-optimalisatie

dbt-macro’s kun je ook in geavanceerdere toepassingen gebruiken. We bekijken hieronder twee veelvoorkomende manieren.

Recursieve en metaprogrammeerpatronen

Macro’s kunnen andere macro’s aanroepen, door metadata loopen of dynamisch SQL-fragmenten genereren op basis van schema-inspectie. 

Dit stelt je in staat om:

• Automatisch stagingmodellen te maken voor elke sourcetabel.
• Pivot/unpivot-queries te genereren zonder elke kolom handmatig te typen.
• Omgevingsbewuste queries te bouwen door over config-variabelen te loopen.

Strategieën voor performance-optimalisatie

Je kunt ook verder optimaliseren om de performance te verbeteren:

• Minimaliseer querycomplexiteit door alleen de benodigde kolommen of joins op te nemen.
• Pas materializations of SQL-strategieën aan op basis van het type warehouse.

Integratie met het dbt-ecosysteem

Macro’s maken deel uit van het dbt-ecosysteem en worden nog krachtiger in combinatie met packages, cloudfuncties en externe tools.

Packagemanagement

Veel community-dbt-packages zoals dbt-utils, dbt-date en dbt-expectations zijn in essentie verzamelingen van zeer herbruikbare macro’s. 

Deze packages brengen kant-en-klare transformaties, tests en helpers zonder het wiel opnieuw uit te vinden. 

Compatibiliteit met dbt Cloud en ontwikkeltools

Macro’s werken naadloos in dbt Cloud-omgevingen, wat betekent dat je dynamische SQL-logica hetzelfde werkt, lokaal of in een geplande cloudjob. 

Ze integreren ook goed met versiebeheer, CI/CD-pijplijnen en code reviews, zodat macro-updates consistent worden getest en uitgerold.

Strategieën voor implementatie in de echte wereld

Overstappen van traditionele SQL-scripts naar een macro-gedreven dbt-workflow vereist zowel technische veranderingen als culturele adoptie.

Migratie en verandermanagement

Begin bij migratie met het identificeren van herhaalde SQL-patronen in modellen. Refactor deze vervolgens stapsgewijs naar macro’s en valideer dat de gecompileerde SQL overeenkomt met de oude logica. 

Gebruik featureflags (var()) om nieuwe macrologica tijdens de uitrol aan/uit te zetten en zo verstoring te minimaliseren. Het belangrijkste is dat je stakeholders op de hoogte zijn van wijzigingen om downstream-queries niet te breken.

Governance- en deploymentstrategieën

Stel voor governance duidelijke naamgevingsconventies, parameterstandaarden en documentatie-eisen vast voor alle macro’s.

Review macroveranderingen in pull requests net als modelupdates en zorg dat ze aan performance- en compatibiliteitsstandaarden voldoen. 

Monitor in productie joblogs voor door macro’s gegenereerde queries om te verifiëren dat ze naar verwachting draaien. Voor projecten met veel macro’s kun je observability-dashboards opzetten om compilatietijden en queryperformance per macrotype te volgen.

Conclusie

dbt-macro’s zijn cruciaal voor productiviteit en onderhoudbaarheid in moderne analytics engineering-teams. Werken met dbt-modellen in combinatie met macro’s kan leiden tot betere resultaten voor datacleaning-operaties.

Meer leren over dbt? Onze Introduction to dbt-cursus en dbt-tutorial zijn mogelijk nuttig voor je.