Skip to main content

Snapshot configurations

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:

dbt_project.yml
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

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 apply alter statements) to ensure table consistency.
  • New configurations — Convert the configs one at a time, testing as you go.
warning

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.

dbt_project.yml
snapshots:
<resource-path>:
+enabled: true | false
+tags: <string> | [<string>]
+alias: <string>
+pre-hook: <sql-statement> | [<sql-statement>]
+post-hook: <sql-statement> | [<sql-statement>]
+persist_docs: {<dict>}
+grants: {<dict>}
+event_time: my_time_field

Configuring snapshots

Snapshots can be configured in multiple ways:

  1. 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.
  2. From the dbt_project.yml file, under the snapshots: 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.yml
    snapshots:
    +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.yml
    snapshots:
    jaffle_shop:
    +unique_key: id

    Similarly, 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.yml
    snapshots:
    - name: orders_snapshot
    relation: source('jaffle_shop', 'orders')
    config:
    unique_key: id
    strategy: timestamp
    updated_at: updated_at
    persist_docs:
    relation: true
    columns: true

    Pro-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 the snapshots/postgres_app/ directory, where the snapshot is named orders_snapshot (as above), this would look like:

    dbt_project.yml
    snapshots:
    jaffle_shop:
    postgres_app:
    orders_snapshot:
    +unique_key: id
    +strategy: timestamp
    +updated_at: updated_at

    You 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.yml
    version: 2

    snapshots:
    - name: orders_snapshot
    +persist_docs:
    relation: true
    columns: true
0