Skip to main content

Setting up dbt State Preview

This page walks you through setting up dbt State across dbt Core, dbt platform, and Fusion.

Prerequisites​

Before you set up dbt State, make sure you have:

  • A supported dbt version: dbt State is natively available in dbt platform and the dbt Fusion engine. It's also available as a plugin for dbt Core v1.7–1.12.
  • A supported data platform: Snowflake, Databricks, BigQuery, or Redshift. More warehouses are on the roadmap.
  • A dbt platform account: Refer to About dbt State for sign-up details, and dbt State usage and pricing for pricing details. Note that dbt State isn't available on legacy Starter plan. Please contact dbt Labs if that applies to you.

Setting up dbt State​

Set up dbt State either in dbt platform or locally in dbt Core by using the following steps depending on how you're using dbt:

  • Already logged in to dbt platform and managing your account? Use dbt Account settings.
  • Signing up or logging in through the dbt platform sign-up page? Use dbt platform sign-up.
  • Using the CLI? Use dbt v2 or dbt v1.7-1.12.

Enabling dbt State on your account​

Prerequisite: You must be an admin in your dbt platform account.

To enable dbt State:

  1. In your dbt platform account, click your account name in the lower-left corner above your username and click Account settings.

  2. Under Settings, go to Billing & Usage > Usage-based features.

  3. Under the State tab, click Start free trial.

    Once started, you cannot pause the trial. After 30 days, you must add a credit card or enterprise contract to continue. For information about how the trial period and billing work, refer to dbt State trial and billing.

    Extended trial for state-aware orchestration users

    If you were using state-aware orchestration prior to June 1, 2026, your dbt State trial will be extended beyond 30 days. If the extension isn’t applied to your account, contact your account team.

  4. Review and agree to the terms of service.

  5. Click Start 30-day trial.

  6. Click Enable dbt State.

  7. Select the jobs to enable dbt State for. You can either enable:

    • By environment: Enables dbt State on all existing jobs within the selected environment at once. New jobs created in that environment will have dbt State enabled automatically.
    • By specific jobs: Enables dbt State on individual jobs. To enable it on additional jobs later, refer to Enabling dbt State on individual jobs.

  8. Click Enable dbt State.

For next steps, see:

To see how dbt State optimizes your runs, refer to dbt State usage examples.

Configuring lag tolerance​

Lag tolerance allows you to set a tolerance level for older data at the project, environment, or model level. If not configured, lag_tolerance defaults to 45m. We recommend starting with the following Jinja expression:

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.

For more details, refer to the lag_tolerance config reference.

Inviting team members​

The more team members you have using dbt State, the better it gets; more team members means more opportunities to clone existing nodes rather than rebuilding them. To invite colleagues:

  • From the dbt Core 2.0 CLI: Have your colleagues run dbt login after dbt State is enabled on the account.
  • From dbt platform: Go to Account settings > Users and click Invite users. For more information, refer to Invite new users.

Debugging dbt State​

If dbt State is behaving unexpectedly, you can prepend your run command with the DBT_ENGINE_MANAGE_STATE environment variable to isolate the issue:

DBT_ENGINE_MANAGE_STATE=0 dbt run --target dev --select "customers"

To see which decision dbt State made for each node after a run and why, you can run the (Applies to dbt v2.0 and later) dbt state explain command.

Next steps​

Was this page helpful?

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

0
Loading