How To Write dbt Macros?

Learn what is Macros & Jinja, setup, and best practices.

How To Write dbt Macros?

In the world of data transformation - a place where SQL and programming languages meet - dbt (Data Build Tool) has become a game-changer. dbt macros, analogous to functions in programming, allow for some powerful customization in your dbt project. They're central for controlling structures and can combine SQL statements and for loops to automate various tasks.

What are dbt Macros and Jinja?

dbt macros are essentially control structures, that are similar to functions in programming languages. They allow you to write reusable SQL code for data transformation. They can also help combine SQL statements and loops, making your dbt project efficient. For more on this, dbt documentation is a great place to start.

Jinja is a modern and designer-friendly templating language for Python, modeled after Django's templates. In the context of dbt (Data Build Tool) and dbt macros, Jinja is used as a SQL templating engine.

dbt macros are written using Jinja, which enables the dynamic generation of SQL code. This capability allows users to create reusable snippets of SQL code that can be applied across multiple models or projects, leading to increased efficiency and ease of maintenance.

Setting Up dbt for Macros

To start writing dbt macros, you'll need to install dbt and set up your dbt project. This involves:

  1. Prerequisites: Python 3.6 or higher, Git.
  2. Installing dbt: Use the command pip install dbt.
  3. Setting Up Your dbt Project: Create a new directory and run the dbt init your_project_name command.

dbt Macro Examples

Here are three examples on how to write dbt Macros -

Writing dbt Macros: Example 1 - Simple Date Macro

First, a simple macro that mimics order payment date formatting.

  1. Create a Macro File: In your dbt project, create a file called date_macro.sql.
  2. Write the Macro:



Run Query in dbt Model:


run query in dbt model

This macro will return the date 2023-08-02, similar to how you might handle order payment dates.

Example 2 - Conditional Logic Macro

This example illustrates how control structures and loops in SQL work using dbt macros.

  1. Create Macro File: conditional_macro.sql.
  2. Write Macro:


Logic Macro

Use Macro in dbt Model:


Macro in dbt

This will return a status level. You can think of it like a list of payment methods in terms of priority.

Example 3 - Advanced Iterative Macro

This example is more complex. Here we will set a variable to iterate through a query in our dbt model using dbt jinja.

  1. Create Macro File: iterative_macro.sql.
  2. Write Macro with SQL and Jinja:


SQL & Jinja

Use Macro in dbt Model:



This will run the query five times, showing the power of Jinja and macros with dbt.

Best Practices for Writing dbt Macros

  1. Check dbt Documentation: dbt documentation is an invaluable resource for understanding the syntax, functionalities, and intricacies of dbt macros. It provides comprehensive guides, examples, and tutorials that help in writing effective macros.
  2. Test Your Macros and SQL Code: Macros can be complex, and bugs may slip in. Regular testing ensures that the macros work as intended and interact well with the rest of the SQL code. It minimizes errors and streamlines development.
  3. Use dbt Utils for Additional Functionalities: dbt utils provide a set of predefined macros and functions that can save time and effort. They enhance the functionality of your dbt project without needing to write every feature from scratch.
  4. Explore Jinja and Macros in dbt: The combination of Jinja with dbt macros allows for powerful and dynamic SQL generation. Spend time learning about this synergy through the dbt documentation to unlock more advanced techniques and improve your coding efficiency.


dbt macros, analogous to functions in programming languages, can transform how you manage SQL code. With the power to combine SQL and loops, handle order payment data, and much more, dbt offers a robust templating language that empowers your data transformation efforts. The dbt documentation and dbt utils can further your journey in exploring what dbt has to offer.

Subscribe to the Newsletter

About us

We write about all the processes involved when leveraging data assets: from the modern data stack to data teams composition, to data governance. Our blog covers the technical and the less technical aspects of creating tangible value from data.

At Castor, we are building a data documentation tool for the Notion, Figma, Slack generation.

Or data-wise for the Fivetran, Looker, Snowflake, DBT aficionados. We designed our catalog software to be easy to use, delightful and friendly.

Want to check it out? Reach out to us and we will show you a demo.

New Release

Get in Touch to Learn More

See Why Users Love CastorDoc
Fantastic tool for data discovery and documentation

“[I like] The easy to use interface and the speed of finding the relevant assets that you're looking for in your database. I also really enjoy the score given to each table, [which] lets you prioritize the results of your queries by how often certain data is used.” - Michal P., Head of Data