is_incremental() macro in dbt - Step-by-Step Execution

Concept Flow - is_incremental() macro

Start dbt model run

↓

Check if run is incremental?

↓

Run incremental

↓

Append new data

↓

End run

The is_incremental() macro checks if the current dbt model run is incremental or full refresh, guiding the model to append new data or replace all data.

Execution Sample

dbt

select * from source_table
{% if is_incremental() %}
where updated_at > (select max(updated_at) from {{ this }})
{% endif %}

This code selects all data from source_table, but if running incrementally, it only selects new or updated rows.

Execution Table

Step	is_incremental() Result	Condition Checked	Action Taken	Output Description
1	True	Is this an incremental run?	Apply WHERE filter to select new rows	Only rows with updated_at > max(updated_at) in target are selected
2	False	Is this an incremental run?	No filter applied, select all rows	All rows from source_table are selected
3	True	Run incremental append	Append new rows to existing table	Table grows with new data
4	False	Run full refresh	Replace entire table with new data	Table is fully replaced
5	-	Run ends	Process complete	Model run finished

💡 Execution stops after data is either appended (incremental) or fully replaced (full refresh).

Variable Tracker

Variable	Start	After Step 1	After Step 3	Final
is_incremental()	undefined	True or False depending on run type	True or False	True or False
selected_rows	empty	Filtered rows if incremental, else all rows	Rows ready to append or replace	Final rows loaded into table

Key Moments - 2 Insights

Why does the model select fewer rows when is_incremental() returns True?

Because when is_incremental() is True, the model adds a WHERE clause to select only new or updated rows, as shown in execution_table row 1.

What happens if is_incremental() returns False during a run?

The model runs a full refresh, selecting all rows and replacing the existing table, as shown in execution_table rows 2 and 4.

Visual Quiz - 3 Questions

Look at the execution table, what action is taken when is_incremental() returns True?

A Replace entire table with new data

B Skip data loading

C Append new rows to existing table

D Delete existing data without loading

💡 Hint

See execution_table row 3 for the action when is_incremental() is True.

At which step does the model decide to run a full refresh?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Check execution_table row 2 where is_incremental() is False.

If the WHERE clause inside the if block is removed, how does the output change when is_incremental() is True?

A All rows are selected regardless of incremental run

B No rows are selected

C Only new rows are selected

D Model run fails

💡 Hint

Refer to execution_sample code where the WHERE clause filters rows only if is_incremental() is True.

Concept Snapshot

is_incremental() macro in dbt:
- Returns True if the model run is incremental
- Use inside {% if is_incremental() %} to filter new data
- Incremental runs append data, full refresh replaces
- Helps optimize data loading by avoiding full reloads
- Commonly used with WHERE clauses to select new/updated rows

Full Transcript

The is_incremental() macro in dbt helps the model know if it is running incrementally or as a full refresh. When running incrementally, the macro returns True, so the model can add a filter to select only new or updated rows. This way, the model appends only new data instead of reloading everything. If the macro returns False, the model runs a full refresh and replaces all data. This process optimizes data loading and saves time. The execution table shows steps where the macro result guides the model's behavior, either filtering rows or selecting all. Variables like is_incremental() and selected_rows change accordingly during the run. Understanding this macro helps beginners write efficient dbt models.

Practice

1. What does the is_incremental() macro in dbt indicate when used inside a model?

easy

A. If the model has any syntax errors

B. Whether the model is running in incremental mode or full-refresh mode

C. The total number of rows in the model

D. The database connection status

Solution

1. Step 1: Understand the purpose of is_incremental()

   This macro returns true if the model is running incrementally, false if running a full-refresh.

2. Step 2: Identify what it indicates in the model

   It tells the model whether to add only new data or rebuild fully.

3. Final Answer:

   Whether the model is running in incremental mode or full-refresh mode -> Option B

4. Quick Check:

   is_incremental() = incremental mode check [OK]

Hint: Remember: is_incremental() checks incremental run status [OK]

Common Mistakes:

• Thinking it checks for errors
• Confusing it with row count
• Assuming it checks connection status

2. Which of the following is the correct way to use is_incremental() in a dbt model SQL file?

easy

A. WHERE is_incremental = true

B. SELECT * FROM table WHERE is_incremental() = true

C. {% if is_incremental() %} WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }}) {% endif %}

D. SELECT * FROM table WHERE incremental = is_incremental()

Solution

1. Step 1: Recognize correct Jinja syntax for is_incremental()

   It must be used inside a Jinja if statement with {% %} tags.

2. Step 2: Check the options for correct usage

   {% if is_incremental() %} WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }}) {% endif %} uses {% if is_incremental() %} correctly to conditionally add a WHERE clause.

3. Final Answer:

   {% if is_incremental() %} WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }}) {% endif %} -> Option C

4. Quick Check:

   Use Jinja {% if is_incremental() %} for conditional SQL [OK]

Hint: Use {% if is_incremental() %} to add incremental filters [OK]

Common Mistakes:

• Using is_incremental() directly in SQL WHERE clause
• Missing Jinja tags {% %}
• Using is_incremental as a column or variable

3. Given the following dbt model snippet, what rows will be selected when the model runs incrementally?

SELECT * FROM source_table
{% if is_incremental() %}
  WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})
{% endif %}

medium

A. Only rows with updated_at greater than the max in the existing model

B. Only rows with updated_at less than the max in the existing model

C. No rows will be selected

D. All rows from source_table every time

Solution

1. Step 1: Understand the condition inside the incremental block

   When running incrementally, the WHERE clause filters rows with updated_at greater than the max in the current model.

2. Step 2: Determine which rows are selected

   This means only new or updated rows after the last run are selected.

3. Final Answer:

   Only rows with updated_at greater than the max in the existing model -> Option A

4. Quick Check:

   Incremental filter selects newer rows [OK]

Hint: Incremental runs add only newer rows based on max timestamp [OK]

Common Mistakes:

• Thinking all rows are selected every time
• Confusing greater than with less than
• Ignoring the existing model's max timestamp

4. You wrote this dbt model code but it fails to run incrementally:

SELECT * FROM source_table
{% if is_incremental %}
  WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})
{% endif %}

What is the error?

medium

A. Using {{ }} instead of {% %} for if statement

B. Incorrect SQL syntax in WHERE clause

C. No error, code is correct

D. Missing parentheses after is_incremental macro call

Solution

1. Step 1: Check the usage of is_incremental

   The macro must be called with parentheses: is_incremental().

2. Step 2: Identify the error in the if statement

   The code uses is_incremental without parentheses, causing a syntax error.

3. Final Answer:

   Missing parentheses after is_incremental macro call -> Option D

4. Quick Check:

   Always call is_incremental() with parentheses [OK]

Hint: Remember: is_incremental() needs parentheses [OK]

Common Mistakes:

• Forgetting parentheses on macro calls
• Confusing {{ }} and {% %} tags
• Assuming macro is a variable

5. You want to create a dbt model that updates only new rows incrementally but also handles the case when the model is run for the first time (empty table). Which code snippet correctly uses is_incremental() to achieve this?

hard

A. SELECT * FROM source_table
{% if is_incremental() %}
WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})
{% else %}
-- full refresh: select all rows
{% endif %}

B. SELECT * FROM source_table
WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})

C. {% if is_incremental() %}
SELECT * FROM source_table
{% else %}
SELECT * FROM source_table WHERE updated_at < NOW()
{% endif %}

D. SELECT * FROM source_table
{% if is_incremental() %}
WHERE updated_at < (SELECT MAX(updated_at) FROM {{ this }})
{% endif %}

Solution

1. Step 1: Understand incremental and full-refresh logic

   When running incrementally, filter new rows; on full-refresh, select all rows.

2. Step 2: Check which option handles both cases correctly

   SELECT * FROM source_table {% if is_incremental() %} WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }}) {% else %} -- full refresh: select all rows {% endif %} uses is_incremental() with an else block for full-refresh selecting all rows.

3. Final Answer:

   SELECT * FROM source_table {% if is_incremental() %} WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }}) {% else %} -- full refresh: select all rows {% endif %} -> Option A

4. Quick Check:

   Use is_incremental() with else for full-refresh [OK]

Hint: Use else block with is_incremental() for full-refresh [OK]

Common Mistakes:

• Not handling full-refresh case
• Using wrong comparison operators
• Filtering incorrectly on first run