Snapshot configurations
Related documentation
Available configurations
Snapshot-specific configurations
Resource-specific configurations are applicable to only one dbt resource type rather than multiple resource types. You can define these settings in the project file (dbt_project.yml
), a property file (models/properties.yml
for models, similarly for other resources), or within the resource’s file using the {{ config() }}
macro.
The following resource-specific configurations are only available to Snapshots:
- Project file
- YAML file
- Config block
snapshots:
<resource-path>:
+schema: <string>
+database: <string>
+alias: <string>
+unique_key: <column_name_or_expression>
+strategy: timestamp | check
+updated_at: <column_name>
+check_cols: [<column_name>] | all
+snapshot_meta_column_names: {<dictionary>}
+dbt_valid_to_current: <string>
+hard_deletes: string
Refer to configuring snapshots for the available configurations.
snapshots:
- name: <string>
config:
database: <string>
schema: <string>
unique_key: <column_name_or_expression>
strategy: timestamp | check
updated_at: <column_name>
check_cols: [<column_name>] | all
snapshot_meta_column_names: {<dictionary>}
hard_deletes: string
dbt_valid_to_current: <string>
Starting from the dbt Cloud "Latest" release track and dbt Core v1.9, defining snapshots in a .sql
file using a config block is a legacy method. You can define snapshots in YAML format using the latest snapshot-specific configurations. For new snapshots, we recommend using these latest configs. If applying them to existing snapshots, you'll need to migrate over.
Snapshot configuration migration
The latest snapshot configurations introduced in dbt Core v1.9 (such as snapshot_meta_column_names
, dbt_valid_to_current
, and hard_deletes
) are best suited for new snapshots. For existing snapshots, we recommend the following to avoid any inconsistencies in your snapshots:
For existing snapshots
- Migrate tables — Migrate the previous snapshot to the new table schema and values:
- Create a backup copy of your snapshots.
- Use
alter
statements as needed (or a script to applyalter
statements) to ensure table consistency.
- New configurations — Convert the configs one at a time, testing as you go.
If you use one of the latest configs, such as dbt_valid_to_current
, without migrating your data, you may have mixed old and new data, leading to an incorrect downstream result.
General configurations
General configurations provide broader operational settings applicable across multiple resource types. Like resource-specific configurations, these can also be set in the project file, property files, or within resource-specific files.
- Project file
- YAML file
- Config block
version: 2
snapshots:
- name: [<snapshot-name>]
relation: source('my_source', 'my_table')
config:
enabled: true | false
tags: <string> | [<string>]
alias: <string>
pre_hook: <sql-statement> | [<sql-statement>]
post_hook: <sql-statement> | [<sql-statement>]
persist_docs: {<dict>}
grants: {<dictionary>}
event_time: my_time_field
Starting from the dbt Cloud "Latest" release track and dbt Core v1.9, defining snapshots in a .sql
file using a config block is a legacy method. You can define snapshots in YAML format using the latest snapshot-specific configurations. For new snapshots, we recommend using these latest configs. If applying them to existing snapshots, you'll need to migrate over.
Configuring snapshots
Snapshots can be configured in multiple ways:
- Defined in YAML files using the
config
resource property, typically in your snapshots directory or whichever folder you pefer. Available in the dbt Cloud release track, dbt v1.9 and higher. - From the
dbt_project.yml
file, under thesnapshots:
key. To apply a configuration to a snapshot, or directory of snapshots, define the resource path as nested dictionary keys.
Snapshot configurations are applied hierarchically in the order above with higher taking precedence. You can also apply tests to snapshots using the tests
property.
Examples
The following examples demonstrate how to configure snapshots using the dbt_project.yml
file and a .yml
file.
-
Apply configurations to all snapshots
To apply a configuration to all snapshots, including those in any installed packages, nest the configuration directly under the
snapshots
key:dbt_project.ymlsnapshots:
+unique_key: id -
Apply configurations to all snapshots in your project
To apply a configuration to all snapshots in your project only (for example, excluding any snapshots in installed packages), provide your project name as part of the resource path.
For a project named
jaffle_shop
:dbt_project.ymlsnapshots:
jaffle_shop:
+unique_key: idSimilarly, you can use the name of an installed package to configure snapshots in that package.
-
Apply configurations to one snapshot only
snapshots/postgres_app/order_snapshot.ymlsnapshots:
- name: orders_snapshot
relation: source('jaffle_shop', 'orders')
config:
unique_key: id
strategy: timestamp
updated_at: updated_at
persist_docs:
relation: true
columns: truePro-tip: Use sources in snapshots:
select * from {{ source('jaffle_shop', 'orders') }}
You can also use the full resource path (including the project name, and subdirectories) to configure an individual snapshot from your
dbt_project.yml
file.For a project named
jaffle_shop
, with a snapshot file within thesnapshots/postgres_app/
directory, where the snapshot is namedorders_snapshot
(as above), this would look like:dbt_project.ymlsnapshots:
jaffle_shop:
postgres_app:
orders_snapshot:
+unique_key: id
+strategy: timestamp
+updated_at: updated_atYou can also define some common configs in a snapshot's
config
block. However, we don't recommend this for a snapshot's required configuration.dbt_project.ymlversion: 2
snapshots:
- name: orders_snapshot
+persist_docs:
relation: true
columns: true