Selecting models by comparing against a prior run's state

dbt's --state flag enables comparing the current project against artifacts (primarily manifest.json) from a previous run, allowing commands to target only resources that have changed. This powers state-based selection methods like state:modified and state:new, which are foundational for slim CI and efficient deployments.

1 · Learn the must-know

• 1The --state flag points to a directory containing a prior run's artifacts (manifest.json, and optionally run_results.json), which must be generated by a previous dbt invocation and stored/retrieved (e.g., via dbt Cloud artifacts or CI caching).
• 2state:modified selects resources whose definitions changed relative to the stored state, including changes to SQL/Python code, configs, schema.yml properties, and referenced macros; state:new selects resources that exist in the current project but not in the prior state.
• 3The result:error, result:fail, and result:skipped selection methods require run_results.json from the prior invocation (not just manifest.json) and are typically used for rerunning failed or skipped nodes.
• 4Combining --select state:modified+ with --defer allows a slim CI workflow: only modified models and their downstream dependents are built/tested, while unmodified upstream models resolve to their production-built relations via the deferred manifest.
• 5State comparison is sensitive to non-functional changes like whitespace or comment edits only if dbt's parsing detects a change in the compiled/checksum representation; purely cosmetic changes that don't alter the parsed node are generally not flagged as modified.
• 6The DBT_STATE environment variable or the --state flag must resolve to a valid path at invocation time, and mismatched dbt versions or adapter versions between the stored state and current run can cause comparison errors or false positives.

2 · Check your understanding