This hub maps notes on dbt macro design: when to extract, how to scope, naming conventions, documentation, testing, and handling breaking changes. Notes can be read in sequence or consulted for specific questions.
Prerequisites
These notes assume you already understand how dbt macros work at a syntax level — Jinja fundamentals, the execute flag, context objects, and the dispatch pattern. If you’re new to macros entirely, start with dbt Macros first.
Reading Order
-
dbt Macro Rule of Three — when to extract a macro vs. when to leave code inline. The discipline that prevents premature abstraction.
-
dbt Single Responsibility Macros — once you’ve decided to extract, how to scope it. The parameter explosion warning sign and the composition pattern.
-
dbt Macro Naming Conventions — verb prefixes, descriptive names, underscore for internal helpers, one-macro-per-file. Names are the cheapest documentation you have.
-
dbt Macros — folder structure and organization, plus Jinja fundamentals if you need a refresher on dispatch, execute guards, and context objects.
-
dbt Macro Documentation YAML — why
_macros.ymlbeats comments, and how to write descriptions that developers actually use (usage examples, not abstract argument descriptions). -
dbt Macro Testing Patterns — integration test models, native unit tests (dbt 1.8+), and the compile-and-inspect debugging workflow.
-
dbt Macro Deprecation Pattern — staged deprecation using
exceptions.warn()when macro behavior needs to change after models depend on it.
Leaving three similar lines of code inline rather than extracting a macro is sometimes the correct call. Readability and maintainability are the criteria, not elimination of duplication.