is_incremental() macro in dbt

Introduction

The is_incremental() macro helps you know if your dbt model is running as an incremental update or a full refresh. This lets you write code that only adds new data, saving time and resources.

When you want to add only new rows to a large table instead of rebuilding it from scratch.

When your data source updates regularly and you want to keep your model up to date efficiently.

When you want to avoid processing all historical data every time you run your model.

When you want to write conditional logic in your model to handle incremental loads differently.

When you want to improve performance by processing only changed or new data.

Syntax

dbt

{{ is_incremental() }}

This macro returns true if the model is running incrementally, otherwise false.

Use it inside {% raw %}{% if %}{% endif %}{% endraw %} blocks to write conditional SQL.

Examples

This example shows how to run different SQL depending on whether the model is incremental or full refresh.

dbt

{% raw %}{% if is_incremental() %}
  -- SQL to add only new rows
{% else %}
  -- SQL to build full table
{% endif %}{% endraw %}

This example selects only new or updated rows when incremental, otherwise selects all rows.

dbt

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

Sample Program

This dbt model uses is_incremental() to load only new or updated rows when running incrementally, and loads all rows on full refresh.

dbt

{% raw %}
-- dbt model SQL file

{% if is_incremental() %}
  SELECT id, name, updated_at
  FROM source_table
  WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})
{% else %}
  SELECT id, name, updated_at
  FROM source_table
{% endif %}
{% endraw %}

Important Notes

Remember to define a unique key or timestamp column to identify new or changed rows for incremental loads.

If you run a full refresh, is_incremental() returns false, so your model rebuilds completely.

Use is_incremental() only inside dbt model SQL files or macros.

Summary

is_incremental() tells if the model runs incrementally or fully.

Use it to write SQL that adds only new data when possible.

This saves time and computing resources on large datasets.