lag_tolerance

Project YAML file

dbt_project.yml

models:
  <resource-path>:
    +state:
      lag_tolerance: <duration_string>

Properties YAML file

models/<filename>.yml

models:
  - name: my_model
    config:
      state:
        lag_tolerance: <duration_string>

SQL file config

models/<filename>.sql

{{ config(
    state={
      "lag_tolerance": "<duration_string>"
    }
) }}

Definition

Source systems may update more frequently than downstream models need to rebuild. For example, a model used for daily reporting doesn't need to refresh more than once per day, even if new upstream data is available hourly.

lag_tolerance lets you define how much time must pass since the last upstream data change before dbt triggers a rebuild. This acts as a compute-saving buffer that helps you stay aligned with data freshness Service Level Agreements (SLAs) without unnecessary rebuilds. It supports two key scenarios:

• Aligning builds with SLA requirements: lag_tolerance allows you to align model execution directly with data freshness SLA requirements, decoupling high-frequency upstream changes from downstream models that operate under wider, less demanding freshness requirements.
• Protecting compute during upstream SLA breaches: lag_tolerance protects your compute budget during freshness SLA breaches, preventing costly downstream rebuilds on static data when an upstream dependency fails its freshness SLA.

When dbt State evaluates whether to rebuild a node, it checks whether upstream parents have fresh data that exceeds the lag_tolerance threshold. If they haven't, dbt reuses the existing node rather than cloning or rebuilding it.

This config accepts two value types:

• Duration strings in the format <number><unit>:

  Unit	Accepted values
  Seconds	s, second, seconds
  Minutes	m, minute, minutes
  Hours	h, hour, hours
  Days	d, day, days
  Weeks	w, week, weeks

• Jinja expressions - lag_tolerance is evaluated as a Jinja template, so you can use any dbt context variables (target, var(), env_var()) to set dynamic tolerances. This is useful for applying different tolerances per environment without duplicating config blocks:

  lag_tolerance: "{{ '4h' if target.name == 'prod' else '7d' }}"

When does lag_tolerance apply

lag_tolerance only applies to data freshness checks. A downstream model still rebuilds within its tolerance window if an upstream model's compiled SQL has changed since the last run, regardless of the lag_tolerance setting.

This often happens with incremental models. The first time an incremental model runs, it executes a full load with no WHERE clause. On subsequent runs, is_incremental() becomes true and a filter is appended, changing the compiled SQL. dbt State detects this as a query change on the upstream model and rebuilds all downstream models, even those whose lag_tolerance has not elapsed.

For example, fct_orders is an incremental model that agg_orders_daily depends on:

models/fct_orders.sql

{{ config(materialized='incremental', unique_key='id') }}

select id, amount from {{ ref('raw_orders') }}
{% if is_incremental() %}
where id > (select max(id) from {{ this }})
{% endif %}

models/agg_orders_daily.sql

{{ config(materialized='table', state={'lag_tolerance': '3h'}) }}

select date_trunc('day', created_at) as day, sum(amount) as total
from {{ ref('fct_orders') }}
group by 1

When fct_orders transitions from a full load to an incremental run, its compiled SQL changes. agg_orders_daily rebuilds on that run despite its 3-hour lag_tolerance.

Default

45m. When lag_tolerance is not set, dbt State applies a default tolerance of 45 minutes.

Examples

Use different tolerances per environment

Use a Jinja expression to set a tight tolerance in production and a looser one everywhere else. This keeps production data fresh while reducing unnecessary rebuilds during development:

dbt_project.yml

models:
  +state:
    lag_tolerance: "{{ '4h' if target.name == 'prod' else '7d' }}"

In this example, models in the prod target rebuild only when upstream data is more than 4 hours old. In all other environments, models wait 7 days before rebuilding.

Apply different tolerances per folder

Set different tolerances for different parts of your project by targeting folders:

dbt_project.yml

models:
  <your_project>:
    marts:
      +state:
        lag_tolerance: 1d
    staging:
      +state:
        lag_tolerance: 1h

Override for a specific model

Override the project-level default for a single model:

models/my_model.yml

models:
  - name: my_model
    config:
      state:
        lag_tolerance: 1h

Related docs

• About dbt State
• Set up dbt State

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.