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 or experience. dbt State is:
    • Natively available in dbt platform, dbt Core v1.12 and later, and the dbt Fusion engine
    • Available as a plugin for dbt Core v1.7 through v1.11
  • A supported data platform. dbt State currently supports Snowflake, Databricks, BigQuery, and Redshift
  • A supported dbt State account type. dbt State requires authentication through either:
    • A current dbt platform account*
    • A standalone dbt State account that's independent of dbt platform
    To learn more about which account option is right for you, refer to About dbt State. For pricing information, refer to dbt State usage and pricing.

*dbt State isn't available to users on legacy Starter plans. If you're on a legacy Starter plan, reach out to dbt Labs for guidance.

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

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.

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 State.

  3. Click Start your 30-day free trial.

    Once started, you cannot pause the trial. After 30 days, you must add a credit card or enterprise contract to continue. For more information, refer to dbt State usage and pricing.

    Extended trial for state-aware orchestration users

    If you're using state-aware orchestration prior to June 1, 2026, your dbt State trial will be extended until the billing period begins on September 1, 2026. 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.

    dbt State pagedbt State page

  7. In the Upgrade to dbt State page, 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 deploy 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.

The dbt State page where you started your trial in step 3 displays how many days remain in your trial period alongside the following monthly data:

  • Number of models reused
  • Total % build reduction
  • Total query run time reduction

Enabling dbt State on individual jobs​

To enable dbt State on any job — whether already existing or newly created in an environment that doesn't have dbt State enabled:

  1. Go to Orchestration > Jobs.
  2. Select the job you want dbt State enabled for.
  3. Click Settings > Edit.
  4. In the Execution settings section of the job, select Enable dbt State.
  5. Click Save.

Enabling dbt State in Studio​

When you enable dbt State in the Studio IDE, it runs automatically on every dbt run or dbt build during development — skipping unchanged models and reusing production results so your runs are faster.

You can turn it on for your development environment so it's the default for everyone, or you can override that setting just for your own account.

Prerequisite: An account admin must enable dbt State before you can use it.

Enabling dbt State on a development environment​

Enabling dbt State on your development environment turns it on for everyone using the Studio IDE, unless they override it for their own account.

  1. Go to Orchestration > Environments and select your development environment.
  2. Click Settings > Edit.
  3. In the dbt State section, select Enable dbt State.
  4. Click Save.
  5. In the pop-up box, click Continue if you want to go ahead with the changes and restart all IDE sessions for this project.
Overriding dbt State setting per user​

You can override the development environment's dbt State setting for your own account without affecting other users. Because the user-level setting takes precedence over the environment-level setting, you can turn dbt State on for yourself before enabling it for your whole team, or turn it off when it's enabled at the environment level.

  1. Click your account name in the lower-left corner and select Account settings.
  2. Under Your profile, go to Credentials.
  3. Select the project you want to enable dbt State for.
  4. Click Edit and go to the User development settings section.
  5. Under dbt State, select one of the following options:
    • Enabled: Enables dbt State for your user regardless of the development environment setting.
    • Disabled: Disables dbt State for your user regardless of the development environment setting.
    • Reset (inherit from development): Only appears after you've saved an Enabled or Disabled override. Clears your override and falls back to the dbt State setting configured on your development environment.
  6. Click Save.

How dbt login works with dbt State​

When dbt State is enabled, dbt login is used for dbt State authentication. Running this command opens a browser window with two options:

  • Log in with your dbt platform account: Enter your email address. If you don't have a dbt platform account, dbt Labs will create a standalone Developer account for you. After that, you'll authorize access between the CLI and dbt platform.
  • Log in without a dbt platform account: Redirects you to the dbt State standalone app at app.state.dbt.com, where a token is created and stored locally at ~/.dbt/auth_state.json. dbt State is automatically enabled locally after account creation.

In the dbt Fusion engine, after platform authentication, the CLI checks your configuration and responds accordingly:

dbt State enabled in dbt platform?dbt State enabled locally?Behavior
✅✅dbt State is ready to use.
✅❌CLI prompts you to enable dbt State locally. If you confirm, user_settings.yml is updated automatically.
❌✅CLI prompts you to enable dbt State in your platform account.

In dbt Core v1.12, dbt login automatically sets manage_state: true in user_settings.yml after platform authentication, unless you've explicitly disabled it. Whether dbt State is enabled in your dbt platform account is checked when you run a dbt command — if it's not enabled, dbt will fail on your next dbt run or dbt build. To resolve this, refer to User settings.

dbt State works out of the box, but the following steps can help you get more value from it.

Configuring lag tolerance​

Lag tolerance allows you to set a tolerance level for older data at the project, environment, or model level. We recommend starting with the following Jinja expression, which tolerates older data locally and requires fresher data in production. As you get a better feel for where adjustments make sense, you can tune individual models.

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.

Configuring deferral​

By default, dbt State defers to your production environment. To customize which environment dbt defers to, use the defer_to_target config.

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

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.

  • For standalone app users: Click the invite link in the upper-right corner of the Users page.
  • For dbt platform users: Have your colleagues run dbt login after dbt State is enabled on the account.

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=1 dbt run --target dev --select "customers"

Was this page helpful?

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

0
Loading