Skip to main content

Setting up dbt State Preview

dbt State is natively available in dbt platform and locally in dbt Core v1.12+ and the dbt Fusion engine. It is also available as a plugin for older versions of dbt Core (1.7-1.11).

Select the option that matches your setup:

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 at the bottom of the left-side menu and click Account settings.

  2. Under Settings, go to State.

  3. Click Start your 30-day free trial.

    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 to 90 days when you sign up. If you don't see the extension, 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:

    • All jobs in an environment: Enables dbt State on all jobs within the selected environment at once.
    • Specific jobs: Enables dbt State on individual jobs.

  8. Click Enable dbt State.

Once dbt State is enabled, all new jobs will have dbt State enabled by default. The dbt State page 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 existing deploy jobs ​

To enable dbt State on existing deploy jobs:

  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.

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