dbt State configurations

When you run a dbt command with dbt State enabled, dbt compares a node's logic and data against previous builds and takes the most efficient path:

• Reuse — if the object exists in the target schema, its logic hasn't changed, and its parents haven't received fresh data exceeding its lag_tolerance, the node is reused.
• Clone — if reuse isn't possible but the object exists in the deferred environment with the same logic and sufficiently fresh data, dbt State clones it.
• Normal build — if neither reuse nor clone is possible, the node builds as normal, using deferral for any unselected upstream nodes.

Use the following configs to control how dbt State makes these decisions.

Project YAML file

dbt_project.yml

models:
  +state:
    lag_tolerance: <duration>
    compare_unrendered_code: true | false
    require_fresh_data_from: any | all
    evaluate_volatile_sql: true | false
    pre_clone: never | if_missing | always
    execute_hooks_on_any_reuse: true | false

Properties YAML file

models/schema.yml

models:
  - name: <model_name>
    config:
      state:
        lag_tolerance: <duration>
        compare_unrendered_code: true | false
        require_fresh_data_from: any | all
        evaluate_volatile_sql: true | false
        pre_clone: never | if_missing | always
        execute_hooks_on_any_reuse: true | false

SQL file config

models/<filename>.sql

{{ config(
    state={
        "lag_tolerance": "<duration>",
        "compare_unrendered_code": true | false,
        "require_fresh_data_from": "any" | "all",
        "evaluate_volatile_sql": true | false,
        "pre_clone": "never" | "if_missing" | "always",
        "execute_hooks_on_any_reuse": true | false
    }
) }}

Profile-level settings are configured in profiles.yml and apply to a specific target environment:

profiles.yml

my_project:
  outputs:
    dev:
      type: snowflake
      # ... dev connection settings
      defer_to_target: prod  # self-managed only
    prod:
      type: snowflake
      # ... prod connection settings
      allow_clones: true | false
      metadata_warehouse: <warehouse_name>  # Snowflake only
  target: dev

Config	Default	Scope	Description
lag_tolerance	45m	Node, folder, or project-level via model config	How much time must pass since the last upstream data change before a node is eligible for a rebuild. Acts as a compute-saving buffer that helps align builds with freshness SLAs. Applies to data freshness only; SQL changes always trigger a rebuild regardless of this setting.
compare_unrendered_code	false	Node, folder, or project-level via model config	Controls whether dbt State checks both the Jinja template (unrendered code) and rendered SQL when detecting code changes. Useful for models with non-deterministic macros or environment variables that produce different rendered SQL on every run.
require_fresh_data_from	any	Node, folder, or project-level via model config	Whether any or all direct parents need fresh data before a node is eligible for a rebuild.
pre_clone	if_missing	Node, folder, or project-level via model config	Whether dbt State pre-populates incremental models and snapshots by cloning production before a run.
execute_hooks_on_any_reuse	false	Node, folder, or project-level via model config	Whether pre- and post-hooks run when a node is reused without rebuilding.
evaluate_volatile_sql	false	Node, folder, or project-level via model config	Whether dbt State stores and compares the runtime output of volatile SQL functions when deciding whether to rebuild.
defer_to_target	prod	Profile	(Self-managed only) Which profile target dbt State defers to.
allow_clones	true	Profile	Whether dbt State can clone tables into a target. For example, set to false on prod to prevent dbt State from cloning dev tables into production.
metadata_warehouse	Profile warehouse	Profile	(Snowflake only) A separate warehouse for dbt State metadata lookups. When set, dbt issues multiple, individual queries (one per schema) instead of a single, consolidated query.

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.