Data dbt State Selection and Defer

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

dbt state selection and defer let data agents compare a working branch against prior artifacts and run only changed resources while borrowing upstream references from another environment.

## Core Explanation

State-aware dbt workflows are common in CI and development because rebuilding an entire warehouse graph is slow. An agent debugging a dbt command should identify the state manifest path, selected resource expression, target profile, defer flag, generated artifacts, and whether the command is comparing code, configuration, relation names, or test definitions.

Useful evidence includes `manifest.json` version, invocation ID, state directory, selection expression such as `state:modified`, defer behavior, upstream relation resolution, and the final node list. Agents should avoid treating a small selected set as proof that the whole graph is healthy.

## Source-Mapped Facts

- dbt documentation says the state selector compares resources against a previous version of the same project represented by a manifest. ([source](https://docs.getdbt.com/reference/node-selection/methods#state))
- dbt documentation says the defer feature uses state artifacts to resolve references to upstream resources. ([source](https://docs.getdbt.com/reference/node-selection/defer))
- dbt documentation says state comparison requires a manifest from a previous dbt invocation. ([source](https://docs.getdbt.com/reference/node-selection/state-comparison-caveats))

## Further Reading

- [dbt State Selection](https://docs.getdbt.com/reference/node-selection/methods#state)
- [dbt Defer](https://docs.getdbt.com/reference/node-selection/defer)
- [dbt About State](https://docs.getdbt.com/reference/node-selection/state-comparison-caveats)