Skip to main content

Migrating from state-aware orchestration to dbt State Preview

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.

To migrate to dbt State, update your configs from freshness.build_after to the new state block. Refer to the configuration changes table for the full mapping.

Configuration changes​

Much of dbt State's configuration will feel familiar if you've used state-aware orchestration, but there is one significant difference: the build_after configs have moved out of the freshness block and into a new state block.

State-aware orchestrationdbt StateNotes
freshness.build_after.updates_onstate.require_fresh_data_fromSame any and all options with the same behavior:
- any (default): rebuilds when any direct parent has fresh data
- all: rebuilds only when all direct parents have fresh data
freshness.build_after.count + freshness.build_after.periodstate.lag_toleranceCombined into a single field with shorthand values (for example, 1800s, 30m, 12h, 1d, 2w) or Jinja expressions
Loading table...
Backwards compatibility in Fusion

In the dbt Fusion engine, dbt State will automatically fall back to your existing build_after configs if lag_tolerance is not set. This means you can enable dbt State without updating your project configs first.

Examples​

You can set these configs at the project level in dbt_project.yml or at the model level in a .yml file.

Project-level:

Before (state-aware orchestration)

dbt_project.yml
models:
  +freshness:
    build_after:
      count: 1
      period: day
      updates_on: any

After (dbt State)

dbt_project.yml
models:
  +state:
    lag_tolerance: 1d
    require_fresh_data_from: any

Model-level:

Before (state-aware orchestration)

models/my_model.yml
models:
  - name: my_model
    config:
      freshness:
        build_after:
          count: 1
          period: day
          updates_on: any

After (dbt State)

models/my_model.yml
models:
  - name: my_model
    config:
      state:
        lag_tolerance: 1d
        require_fresh_data_from: any

Testing the migration​

You can run both configs side by side while validating. State-aware orchestration reads freshness.build_after and dbt State reads the state block, so they won't interfere with each other. Once you're confident everything looks right, remove the build_after configs.

dbt_project.yml
models:
  +freshness:
    build_after:            # state-aware orchestration (remove once migrated)
      count: 1
      period: day
      updates_on: any
  +state:                   # dbt State
    lag_tolerance: 1d
    require_fresh_data_from: any

Limitation​

State aware orchestration’s Efficient Testing feature (private beta) is currently not available in dbt State.

Was this page helpful?

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

0
Loading