About dbt State Preview

dbt State makes dbt smarter about what to build. Instead of rebuilding every node on every run, dbt reuses nodes by cloning from another location or skipping a rebuild when the logic and data haven't changed.

With dbt State, dbt first compares the logic and data of each node to previous builds across multiple environments on every run — whether orchestrated in the dbt platform, through your own orchestrator, or in development. If the logic is the same and the data is still fresh, dbt reuses an existing object. It will either clone an existing node from elsewhere, or skip executing a model that already exists, rather than building it anew. Additionally, it will automatically defer to production state without the need to manually set the --defer or --state flags.

dbt State can reuse all node types that create relations in the database (such as models, snapshots, seeds) and data tests.

dbt State works with dbt Core, the dbt platform, and dbt Fusion engine, across all environments and orchestrators, making it a flexible approach regardless of how you run dbt.

Benefits

dbt State delivers efficiency gains across both production and development environments:

• Fresher data, lower costs — Nodes only rebuild when the result would be different (new data or code changes), reducing warehouse compute while keeping production data fresh.
• Faster iteration cycles — In development, dbt automatically clones selected nodes from production whenever possible, so you spend less time waiting for builds and more time writing code.
• Smarter than standard deferral — Unlike standard deferral, which always builds selected nodes and only defers unselected upstream references, dbt State decides whether transformations need to run at all, or whether an existing table can simply be cloned.

How dbt State works

When you run a command like dbt build --select +my_model, dbt State evaluates each selected node and applies the most efficient approach it can:

• Reuse node from same schema (skip) — dbt checks whether the object already exists in the target schema, its logic hasn't changed, and its upstream parents haven't received fresh data beyond the configured lag_tolerance. If all conditions are met, dbt skips the node entirely, as if it was never selected. For data tests, if the nodes being tested haven't changed since the last run, the previous test result is reused without re-executing the test query.
• Reuse node from different schema (clone) — If the same object exists with matching logic and fresh data, dbt State clones it. The node is marked as Reused at a fraction of the compute cost.
• Normal build — If reuse is not possible, dbt builds the node as normal, automatically deferring any unselected upstream nodes.

Without dbt State, every selected node rebuilds on every run regardless of whether anything has changed.

For the full list of available configs, see dbt State configs.

Supported data warehouses

dbt State is supported on the following data warehouses:

• Snowflake
• Databricks
• BigQuery
• Redshift

More data warehouses are on the roadmap. If you're using another data warehouse and are interested in dbt State, let us know.

Signing up for dbt State

When you sign up for dbt State, you'll choose one of two paths:

• dbt platform account — dbt State is connected to your existing dbt platform account. Your dbt State credentials are the same as your platform credentials, and dbt State has access to your platform environments and jobs.
• Standalone account (app.state.dbt.com) — A standalone dbt State account is independent of any dbt platform account. You manage dbt State credentials separately, and dbt State has no visibility into your platform environments or jobs.

A standalone account makes sense if you:

• Don't have a dbt platform account
• Don't have admin permissions to enable dbt State in your dbt platform account
• Want to test dbt State without connecting it to your dbt platform account yet

FAQs

What happened to state-aware orchestration?

On June 1, 2026, dbt Labs and Fivetran announced dbt StatePreview as a new and improved version of state-aware orchestration. A key feature is lag_tolerance, which controls how much time must pass since the last upstream data change before a node is eligible for a rebuild.

dbt State improves upon state-aware orchestration in a few key ways:

• Works everywhere — dbt State works with dbt Core, Fusion, and dbt platform, as well as external orchestrators, across both development and deployment environments.
• Smarter data freshness tracking — dbt State tracks data freshness across the DAG and automatically propagates it through models materialized as views. Unlike state-aware orchestration's build_after config which compares against the model's last successful execution, dbt State's lag_tolerance compares against the freshness of the underlying data.
• Advanced change detection — dbt State can detect and ignore file modifications that don't change actual transformation logic, such as adding a comment or cleaning up whitespace.

If you're using state-aware orchestration prior to June 1, 2026, you can continue using it. As an existing customer, your dbt State trial will be extended to 90 days when you sign up. If you don't see the extension, contact your account team. To get started, refer to Migrate from state-aware orchestration. While dbt State is in preview, there is no required migration timeline — dbt Labs will communicate a timeline when dbt State reaches general availability.

How is dbt State different from using state:modified?

state:modified in dbt Core requires manual management of manifest.json, which is cumbersome and error-prone. dbt State is completely managed with almost zero setup and no workflow changes.

state:modified only checks if a file has changed. dbt State has semantic understanding of SQL, so meaningless changes like whitespace or table aliases are not counted as a change — making dbt State smarter about what actually needs to rebuild.

state:modified does not consider upstream data changes. dbt State checks all sources to see if there is any new data or if the schema has been modified. This enables dbt State to skip running models if the result of the run would be the same as before. For example, if you run dbt run with state:modified twice, it runs all modified models both times. dbt State only reruns models the second time if upstream sources have changed.

dbt State also has the ability to auto-defer refs and automatically clone tables when the result of the clone would have been the same as a full model run.

state:modified has a limitation on seed files over 1MB, while dbt State does not.

Does dbt State support incremental models?

dbt State works with incremental models. When you make a change to an incremental model and run it in development, dbt State automatically clones the model from production if it exists, then runs the new model logic on top of the clone.

If you want to revert to the original dbt behavior and fully refresh the incremental model, pass the --full-refresh flag.

How is data stored in dbt State?

dbt State sends last-modified timestamps and SQL statements to dbt Labs servers. SQL statements are hashed before transmission, so dbt Labs cannot see the contents. These hashes are used to identify whether a statement has changed by comparing them on each run.

Where does the metadata about last updated timestamp come from?

Last updated timestamps come directly from the data warehouse, for example from INFORMATION_SCHEMA tables.

How does dbt State calculate that a model has changed?

dbt State only considers substantial changes to a model. Because dbt State understands the entire lineage of your models, it can see through things like whitespace and aliases to determine whether a model is the same or different across environments.

What happens if dbt State servers fail?

If dbt State servers are unavailable, dbt gracefully falls back to normal dbt behavior.

What if I work on multiple projects that each use their own dbt State?

You can specify your org ID in dbt_project.yml:

dbt-cloud:
  state-org-id: <your-org-id>

What if my prod environment isn't named prod?

You can specify the defer-to environment using the defer_to_target config in profiles.yml:

my_project:
  outputs:
    prod:
      type: snowflake
      defer_to_target: production

defer_to_target only applies to self-managed deployments. If you're using the dbt platform, deferral is configured through your environment settings in the UI. For more details, refer to Configuring deferral.

Related docs

• Set up dbt State
• CI/CD setup
• dbt State configs
• Migrate from state-aware orchestration
• dbt State usage and pricing

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.