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.

Practice

1. What is the main reason to call macros across different dbt projects?

easy

A. To make the project run slower

B. To increase the size of the project

C. To reuse code and keep projects organized

D. To avoid using any dependencies

Solution

1. Step 1: Understand the purpose of macros

   Macros are reusable pieces of code that help avoid repetition.

2. Step 2: Recognize the benefit of calling macros across projects

   Calling macros across projects allows sharing code, which keeps projects clean and organized.

3. Final Answer:

   To reuse code and keep projects organized -> Option C

4. Quick Check:

   Code reuse = To reuse code and keep projects organized [OK]

Hint: Macros help reuse code across projects easily [OK]

Common Mistakes:

• Thinking macros increase project size
• Believing macros slow down the project
• Ignoring the need for dependencies

2. Which syntax correctly calls a macro named calculate_total from a project named sales_project?

easy

A. {{ sales_project.calculate_total() }}

B. {{ calculate_total() }}

C. {% sales_project.calculate_total() %}

D. {{ sales_project->calculate_total() }}

Solution

1. Step 1: Recall the correct macro call syntax

   Macros from other projects are called using {{ project_name.macro_name() }}.

2. Step 2: Match the syntax to the options

   {{ sales_project.calculate_total() }} uses the correct dot notation and double curly braces.

3. Final Answer:

   {{ sales_project.calculate_total() }} -> Option A

4. Quick Check:

   Use dot notation inside {{ }} = {{ sales_project.calculate_total() }} [OK]

Hint: Use {{ project_name.macro_name() }} to call macros [OK]

Common Mistakes:

• Using {% %} instead of {{ }} for macro calls
• Missing the project name before the macro
• Using incorrect symbols like ->

3. Given the following packages.yml snippet and macro call, what will happen?

packages:
  - package: sales_project
    version: 1.0.0

-- In a model SQL file:
SELECT {{ sales_project.calculate_discount(100) }} AS discount_amount

medium

A. The macro will run and return the discount value

B. Error because the macro call syntax is wrong

C. Error because sales_project is not added as a dependency

D. The SQL will run but ignore the macro call

Solution

1. Step 1: Check the packages.yml for dependencies

   The sales_project is listed as a dependency, so it is available.

2. Step 2: Verify the macro call syntax

   The macro is called correctly using {{ sales_project.calculate_discount(100) }}.

3. Final Answer:

   The macro will run and return the discount value -> Option A

4. Quick Check:

   Dependency + correct syntax = macro runs [OK]

Hint: Add project in packages.yml before calling macros [OK]

Common Mistakes:

• Forgetting to add dependency in packages.yml
• Using wrong macro call syntax
• Assuming macro calls run without dependencies

4. You try to call a macro from another project but get an error. Which of these is the most likely cause?

medium

A. The macro name is misspelled in the call

B. You used single curly braces instead of double

C. The macro is called without parentheses

D. The other project is not listed in packages.yml

Solution

1. Step 1: Identify common errors in cross-project macro calls

   Missing the other project in packages.yml means dbt cannot find the macro.

2. Step 2: Compare other options

   Misspelling or syntax errors cause different errors, but missing dependency is most common.

3. Final Answer:

   The other project is not listed in packages.yml -> Option D

4. Quick Check:

   Missing dependency = macro call error [OK]

Hint: Always add dependencies in packages.yml first [OK]

Common Mistakes:

• Ignoring packages.yml dependencies
• Using wrong macro call syntax
• Forgetting parentheses in macro calls

5. You want to call a macro format_date from a project utils_project inside your project. You added utils_project in packages.yml. Which is the correct way to pass a date string '2024-01-01' to the macro and use its result in a model?

hard

A. SELECT {{ utils_project.format_date(`2024-01-01`) }} AS formatted_date

B. SELECT {{ utils_project.format_date("2024-01-01") }} AS formatted_date

C. SELECT {{ utils_project.format_date(2024-01-01) }} AS formatted_date

D. SELECT {{ utils_project.format_date('2024-01-01') AS formatted_date }}

Solution

1. Step 1: Confirm dependency is added

   utils_project is added in packages.yml, so macro can be called.

2. Step 2: Check correct string passing in macro call

   Strings in Jinja macros should be double-quoted inside {{ }} to avoid syntax issues.

3. Step 3: Validate SQL syntax

   SELECT {{ utils_project.format_date("2024-01-01") }} AS formatted_date correctly uses double quotes inside the macro call and proper SQL aliasing.

4. Final Answer:

   SELECT {{ utils_project.format_date("2024-01-01") }} AS formatted_date -> Option B

5. Quick Check:

   Double quotes for strings in macro calls = SELECT {{ utils_project.format_date("2024-01-01") }} AS formatted_date [OK]

Hint: Use double quotes for string args inside {{ }} [OK]

Common Mistakes:

• Using unquoted strings causing errors
• Incorrect SQL alias syntax
• Missing quotes or wrong quote types