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.

With lag_tolerance, you can prevent those unnecessary rebuilds. 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' }}"

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.