Calling macros across projects in dbt - Step-by-Step Execution

Concept Flow - Calling macros across projects

Start: Define macro in Project A

↓

Macro saved in Project A's macros folder

↓

In Project B: Reference Project A's macro

↓

dbt resolves macro using project namespace

↓

Macro executes with passed arguments

↓

Output used in Project B's models or macros

This flow shows how a macro defined in one dbt project (Project A) can be called from another project (Project B) by using the project namespace to reference it.

Execution Sample

dbt

/* In Project A: macros/my_macro.sql */
{% macro greet(name) %}
  Hello, {{ name }}!
{% endmacro %}

/* In Project B: models/example.sql */
{{ project_a.greet('Alice') }}

Defines a macro 'greet' in Project A and calls it from Project B using the project namespace.

Execution Table

Step	Action	Evaluation	Result
1	Define macro 'greet' in Project A	Macro stored in Project A's namespace	Macro 'greet' ready to use
2	In Project B, call macro as project_a.greet('Alice')	dbt looks up 'greet' in Project A's macros	Macro found and prepared for execution
3	Execute macro with argument 'Alice'	Replace {{ name }} with 'Alice'	Returns string: 'Hello, Alice!'
4	Use macro output in Project B's model	Insert returned string into SQL model	Model contains: Hello, Alice!
5	dbt compiles and runs model	Model runs with macro output	Final SQL includes greeting text

💡 Macro call completes after returning the processed string to Project B's model

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
name	undefined	'Alice'	'Alice'	'Alice'
macro greet	defined in Project A	located by Project B	executed with 'Alice'	returns 'Hello, Alice!'

Key Moments - 3 Insights

How does Project B know where to find the macro defined in Project A?

Project B uses the project namespace prefix (like 'project_a.greet') to tell dbt exactly which project's macro to use, as shown in execution_table step 2.

What happens if the macro name is the same in both projects?

Using the project namespace ensures the correct macro is called. Without the prefix, dbt uses the local project's macro, avoiding confusion (see step 2).

Can macros accept arguments when called across projects?

Yes, arguments like 'Alice' are passed and used inside the macro, demonstrated in step 3 where '{{ name }}' is replaced.

Visual Quiz - 3 Questions

Look at the execution table, what is the output of the macro after step 3?

A 'Hello, project_a!'

B 'Hello, Alice!'

C 'Alice'

D 'greet'

💡 Hint

Check the 'Result' column in step 3 of the execution table.

At which step does dbt resolve the macro location using the project namespace?

A Step 2

B Step 1

C Step 4

D Step 5

💡 Hint

Look at the 'Action' and 'Evaluation' columns in step 2.

If the macro call in Project B omitted the project namespace, what would happen?

A dbt would find the macro in Project A anyway

B dbt would throw an error because macro is undefined

C dbt would use a macro with the same name in Project B if it exists

D dbt would ignore the macro call

💡 Hint

Refer to the key moment about macro name conflicts and local macro resolution.

Concept Snapshot

Calling macros across projects in dbt:
- Define macro in Project A's macros folder
- Call macro in Project B using 'project_a.macro_name()'
- Pass arguments as usual
- dbt resolves macro by project namespace
- Macro output is inserted into Project B's models
- Ensures code reuse across projects

Full Transcript

This visual execution shows how to call macros across dbt projects. First, a macro named 'greet' is defined in Project A. Then, in Project B, the macro is called using the project namespace prefix 'project_a.greet'. dbt resolves this call by looking up the macro in Project A's macros. The macro executes with the argument 'Alice', replacing the placeholder with the name. The resulting string 'Hello, Alice!' is returned and used in Project B's model. This process allows sharing reusable code between projects safely and clearly by using namespaces.