using-dbt-state

Name: using-dbt-state
Author: dbt-labs

116installs55forks

How to install using-dbt-state?

dbt-labs/dbt-agent-skills/using-dbt-state

$npx -y skills add dbt-labs/dbt-agent-skills --skill using-dbt-state

Installs into the current project.

Summary

Use when a user is enabling, configuring, optimizing, or debugging dbt State (the server-backed reuse mechanism that clones or skips nodes instead of rebuilding them). Use when they conflate dbt State with the state:modified selector or --state deferral. Use when asked about

Files · 1

View on GitHub

SKILL.md

1	# Using dbt State
2
3	dbt State is a server-backed reuse mechanism. It should not be conflated with dbt's `state:modified` selector or `--state` deferral.
4
5	Before building each selected node, dbt asks the dbt State server whether the object can be skipped (reuse from the target schema), cloned (reuse from another schema), or must be built. It is the successor to State-Aware Orchestration, but works in dbt Core, in development, and in CI — not just Fusion in production.
6
7	dbt State is a paid product, but it does not require a dbt platform (fka dbt Cloud) subscription.
8
9	## Common Misconceptions
10
11	\| Misconception \| Reality \|
12	\|---\|---\|
13	\| "dbt State is just `state:modified` / `--state`" \| No. `state:modified` hashes file contents against a manifest you manage (and must keep fresh — e.g. via `dbt parse` or similar) and rebuilds `state:modified+` (all descendants). dbt State manages state automatically on a server and does not require maintaining a fresh comparison manifest — it parses SQL into a syntax tree and compares semantic hashes, considers upstream data freshness, and rebuilds a descendant only if it actually depends on the change (not the whole `+` subtree). \|
14	\| "It's Fusion-only / production-only" \| Works in dbt Core, the dbt platform, and Fusion, across dev, CI, and production, with any orchestrator. \|
15	\| "dbt Core users can't use it" \| They can. dbt Core 1.7–1.11 require `pip install dbt-state`. It's baked into dbt Core 1.12 / v2.0 and Fusion. \|
16	\| "It's free / it's local" \| It calls the dbt State server and requires authentication via a dbt platform account or a standalone dbt State account ([app.state.dbt.com](https://app.state.dbt.com)). Reuse is metered in DATTs — daily active target tables (see Billing below). \|
17	\| "It sends my data to dbt Labs" \| It sends last-modified timestamps and SQL text. The SQL is hashed then discarded — dbt Labs cannot read query contents after hashing, and can never access raw data. \|
18
19	## How the reuse decision works
20
21	For each selected node, dbt State picks the cheapest valid option:
22
23	1. Skip — object exists in the target schema, its semantic hash is unchanged, and no parent has fresher data beyond `lag_tolerance`. Does nothing.
24	2. Clone — a matching object (same hash, fresh data) exists in another schema (e.g. production, or a teammate's dev schema). Clones it, marked Reused. Uses zero-copy clone if supported by the warehouse, or runs a CTAS statement to copy the transformed data from elsewhere if not. Test results are reused too — a failing test still surfaces even though it wasn't re-executed.
25	3. Build — no valid reuse. Builds normally, auto-deferring unselected upstream nodes.
26
27	If a node is selected for execution but its inputs do not exist in the target schema, dbt State uses deferral as normal. If a `manifest.json` is present it will use that, otherwise it will make a [best-effort guess](https://docs.getdbt.com/reference/resource-configs/defer-to-target#caveats-to-dbt-state-without-a-manifest) at the correct FQN based on the `generate_*_name` macros. Deferral does not consume DATTs. The `defer_to_target` config in `profiles.yml` can be used to specify which schema to defer to for self-managed users. It is not necessary for dbt platform users.
28
29	To get freshness, dbt fetches warehouse metadata (or `loaded_at_field`/`loaded_at_query`) for each input relation. For views without a `loaded_at` config, it traverses upstream until it finds a real table.
30
31	## Query normalization & why models rebuild
32
33	dbt State hashes a parsed syntax tree, so it ignores cosmetic changes — whitespace, comments, table aliases, `dbt lint --fix` reformatting. A model rebuilds only when its logic or data changes.
34
35	Volatile SQL (`current_timestamp()`, `getdate()`, `random()`): by default treated as logic — the hash uses the function name, not its runtime value, so it does not invalidate the model every run (otherwise nothing downstream of `getdate()` could ever be reused). To make a model rebuild when the value changes:
36	- Set `evaluate_volatile_sql: true` (preferred — covers all functions in the model, inheritable like any config). dbt State emulates the function's value into the hash.
37	- Or use a Jinja equivalent (e.g. `{{ run_started_at }}`) — Jinja renders before parsing, so it changes the compiled SQL each run.
38
39	**Non-determi

People who liked this also viewed

6 picks

Type

using-dbt-state

116installs55forks

View on GitHub

How to install using-dbt-state?

dbt-labs/dbt-agent-skills/using-dbt-state

$npx -y skills add dbt-labs/dbt-agent-skills --skill using-dbt-state

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Using dbt State
2
3	dbt State is a server-backed reuse mechanism. It should not be conflated with dbt's `state:modified` selector or `--state` deferral.
4
5	Before building each selected node, dbt asks the dbt State server whether the object can be skipped (reuse from the target schema), cloned (reuse from another schema), or must be built. It is the successor to State-Aware Orchestration, but works in dbt Core, in development, and in CI — not just Fusion in production.
6
7	dbt State is a paid product, but it does not require a dbt platform (fka dbt Cloud) subscription.
8
9	## Common Misconceptions
10
11	\| Misconception \| Reality \|
12	\|---\|---\|
13	\| "dbt State is just `state:modified` / `--state`" \| No. `state:modified` hashes file contents against a manifest you manage (and must keep fresh — e.g. via `dbt parse` or similar) and rebuilds `state:modified+` (all descendants). dbt State manages state automatically on a server and does not require maintaining a fresh comparison manifest — it parses SQL into a syntax tree and compares semantic hashes, considers upstream data freshness, and rebuilds a descendant only if it actually depends on the change (not the whole `+` subtree). \|
14	\| "It's Fusion-only / production-only" \| Works in dbt Core, the dbt platform, and Fusion, across dev, CI, and production, with any orchestrator. \|
15	\| "dbt Core users can't use it" \| They can. dbt Core 1.7–1.11 require `pip install dbt-state`. It's baked into dbt Core 1.12 / v2.0 and Fusion. \|
16	\| "It's free / it's local" \| It calls the dbt State server and requires authentication via a dbt platform account or a standalone dbt State account ([app.state.dbt.com](https://app.state.dbt.com)). Reuse is metered in DATTs — daily active target tables (see Billing below). \|
17	\| "It sends my data to dbt Labs" \| It sends last-modified timestamps and SQL text. The SQL is hashed then discarded — dbt Labs cannot read query contents after hashing, and can never access raw data. \|
18
19	## How the reuse decision works
20
21	For each selected node, dbt State picks the cheapest valid option:
22
23	1. Skip — object exists in the target schema, its semantic hash is unchanged, and no parent has fresher data beyond `lag_tolerance`. Does nothing.
24	2. Clone — a matching object (same hash, fresh data) exists in another schema (e.g. production, or a teammate's dev schema). Clones it, marked Reused. Uses zero-copy clone if supported by the warehouse, or runs a CTAS statement to copy the transformed data from elsewhere if not. Test results are reused too — a failing test still surfaces even though it wasn't re-executed.
25	3. Build — no valid reuse. Builds normally, auto-deferring unselected upstream nodes.
26
27	If a node is selected for execution but its inputs do not exist in the target schema, dbt State uses deferral as normal. If a `manifest.json` is present it will use that, otherwise it will make a [best-effort guess](https://docs.getdbt.com/reference/resource-configs/defer-to-target#caveats-to-dbt-state-without-a-manifest) at the correct FQN based on the `generate_*_name` macros. Deferral does not consume DATTs. The `defer_to_target` config in `profiles.yml` can be used to specify which schema to defer to for self-managed users. It is not necessary for dbt platform users.
28
29	To get freshness, dbt fetches warehouse metadata (or `loaded_at_field`/`loaded_at_query`) for each input relation. For views without a `loaded_at` config, it traverses upstream until it finds a real table.
30
31	## Query normalization & why models rebuild
32
33	dbt State hashes a parsed syntax tree, so it ignores cosmetic changes — whitespace, comments, table aliases, `dbt lint --fix` reformatting. A model rebuilds only when its logic or data changes.
34
35	Volatile SQL (`current_timestamp()`, `getdate()`, `random()`): by default treated as logic — the hash uses the function name, not its runtime value, so it does not invalidate the model every run (otherwise nothing downstream of `getdate()` could ever be reused). To make a model rebuild when the value changes:
36	- Set `evaluate_volatile_sql: true` (preferred — covers all functions in the model, inheritable like any config). dbt State emulates the function's value into the hash.
37	- Or use a Jinja equivalent (e.g. `{{ run_started_at }}`) — Jinja renders before parsing, so it changes the compiled SQL each run.
38
39	**Non-determi

People who liked this also viewed

6 picks

Type