/dbt-snapshots

name: dbt-snapshots
description: "Load when task involves dbt snapshots, SCD Type 2, or tracking data changes over time. Covers strategy selection, column casing, verification, and common pitfalls."
disable-model-invocation: false
allowed-tools: Bash(dbt *)

dbt Snapshots - SCD Type 2

1. File Location

Place snapshot files in `snapshots/`, NOT `models/`. Verify `snapshot-paths: ["snapshots"]` exists in `dbt_project.yml`.

2. Strategy Selection

**Choose the strategy BEFORE writing the snapshot file.**

Query the candidate timestamp column first:

SELECT COUNT(DISTINCT updated_at), MIN(updated_at), MAX(updated_at)
FROM my_source_table

• If `COUNT(DISTINCT updated_at) = 1` or all values are frozen (e.g., `1980-01-01`), the column is unreliable - a frozen timestamp means `dbt snapshot` will never detect changes.
• If values vary and reflect real mutation times, `strategy='timestamp'` is valid.

| Condition | Strategy | |-----------|----------| | `updated_at` has changing, meaningful values | `strategy='timestamp'`, `updated_at='UPDATED_AT'` | | `updated_at` frozen at a single constant value (COUNT(DISTINCT)=1) | `strategy='check'`, `check_cols='all'` - a column stuck at one value will never detect changes | | No `updated_at` column at all | `strategy='check'`, `check_cols='all'` |

Default to `strategy='check'` with `check_cols='all'` when uncertain - it always works.

Do NOT rationalize a frozen timestamp as valid business data. `1980-01-01` on every row is a data quality artifact, not a real date.

3. Column Casing

Snapshot `unique_key`, `updated_at`, and `check_cols` must match the EXACT case of the source columns.

Query column names before writing the config:

DESCRIBE my_source_table

Wrong: `unique_key='id'` when the source column is `ID`. Right: `unique_key='ID'`.

DuckDB and Snowflake snapshot configs are case-sensitive. A casing mismatch silently produces zero change detection.

4. Writing the Snapshot Block

SELECT explicit columns - not `SELECT *`. Include only business columns. Use raw source column names - do NOT alias them (e.g., `SELECT ID`, not `SELECT ID AS HOST_ID`). The snapshot output columns must match the source for `unique_key` and `check_cols` to work.

{% snapshot snap__employees %}
{{
    config(
        target_schema='main',
        unique_key='EMPLOYEE_ID',
        strategy='check',
        check_cols='all'
    )
}}
SELECT EMPLOYEE_ID, DEPARTMENT, TITLE, SALARY
FROM {{ source('hr', 'employees') }}
{% endsnapshot %}

Set `target_schema` to the project's default schema (`'main'` for DuckDB).

5. Data Type Awareness

Query actual column values before writing predicates:

SELECT DISTINCT IS_ACTIVE FROM my_source_table LIMIT 10

• If values are `'t'`/`'f'` (strings), compare with `= 't'`, NOT `= TRUE`.
• If values are `true`/`false` (booleans), compare with `= TRUE`.

Getting this wrong silently filters to zero rows.

6. Running Snapshots

Run `dbt snapshot` - not `dbt run`. `dbt run` ignores snapshot files.

If the task involves tracking changes over time, run `dbt snapshot` once per mutation phase. A single run captures only the initial state.

7. Verification

After `dbt snapshot`, verify history was captured:

SELECT COUNT(*) AS total, COUNT(DISTINCT EMPLOYEE_ID) AS distinct_keys
FROM main.snap__employees

• If `total = distinct_keys`, zero changes were detected - the strategy or config is wrong. Go back to Section 2.
• Query `dbt_valid_to`: if ALL values are NULL, only the initial load exists - no mutations were tracked.

Also verify SCD2 columns exist: `dbt_valid_from`, `dbt_valid_to`, `dbt_scd_id`, `dbt_updated_at`.

8. Downstream Models

Reference snapshots like any model: `{{ ref('snap__employees') }}`.

• For **current state** (latest version of each row): `WHERE dbt_valid_to IS NULL`.
• For **full change history** (e.g., "who has ever been X"): use ALL rows. Use `LAG()` over `dbt_valid_from` to detect status transitions.
• A snapshot table can hold history loaded before your run, even when `snapshots/` is absent. Probe it BEFORE `dbt snapshot`: `SELECT COUNT(*), COUNT(DISTINCT dbt_valid_from) FROM main.snap__employees`. Multiple `dbt_valid_from` values are pre-existing history to build on, NOT the Section 7 zero-change failure - compute metrics over all versions.
• For a "first time in state X" metric (not a transition count), use `MIN(dbt_valid_from)` filtered to state X. A row already in state X at the earliest version still has a first-observed time, so do NOT require an earlier different-state version.

Rules

• NEVER use `run_in_background` or `&` with `dbt snapshot` - it holds a write lock.
• Do NOT modify `.yml` files for snapshots - snapshot config lives in the `.sql` block.
• A single `dbt snapshot` run with no prior state produces only the initial load, not history. This is expected - history builds across multiple runs with source mutations between them.