# Устаревшая конфигурация snapshot legacy

Используйте устаревшие SQL‑конфигурации снапшотов на основе Jinja‑блоков в любой версии dbt. В dbt v1.9 были представлены YAML‑конфигурации, которые обеспечивают лучшую читаемость и учитывают окружение.

В некоторых ситуациях вам может понадобиться использовать устаревший синтаксис для [snapshots](https://docs.getdbt.tech/docs/build/snapshots.md) в любой версии или ветке релизов dbt. На этой странице описано, как при необходимости использовать устаревшие SQL‑конфигурации.

В dbt v1.9 этот синтаксис был заменён на [конфигурацию на основе YAML](https://docs.getdbt.tech/reference/snapshot-configs.md#configuring-snapshots) в [канале релизов **v1 Latest** dbt](https://docs.getdbt.tech/docs/dbt-versions/dbt-release-tracks.md). Преимущества конфигураций на основе YAML заключаются в том, что снимки учитывают окружение, поэтому вам не нужно указывать `schema` или `database`, а синтаксис стал более лаконичным.

Для новых снапшотов мы рекомендуем использовать актуальные YAML‑конфигурации. Если вы хотите перейти на YAML‑конфигурацию для существующих снапшотов, вы можете [выполнить миграцию](https://docs.getdbt.tech/reference/snapshot-configs.md#snapshot-configuration-migration).

Когда стоит использовать SQL‑синтаксис, а когда — YAML‑синтаксис?

* SQL‑синтаксис:

  * Определяется в файлах `.sql` внутри snapshot Jinja‑блока, обычно расположенных в директории `snapshots`. Доступен во всех версиях.
  * Подходит для существующих снапшотов, которые уже используют этот синтаксис.
  * Подходит для выполнения очень лёгких трансформаций (однако для лучшей поддерживаемости рекомендуется выносить трансформации в отдельную ephemeral‑модель).

* Синтаксис на основе YAML:

  * Определяется в файле `whatever_name.yml` в каталоге `snapshots` или `models` по вашему выбору. Доступен в канале выпусков **v1 Latest** dbt и в dbt v1.9 и более поздних версиях.
  * Идеально подходит для новых снимков или существующих снимков, которые необходимо [мигрировать](https://docs.getdbt.tech/reference/snapshot-configs.md#snapshot-configuration-migration).
  * Определяйте преобразования отдельно от файла снимка: создайте эфемерную модель и укажите ссылку на неё в снимке с помощью поля `relation`.

## Конфигурации снапшотов

Хотя вы можете использовать более производительную YAML‑конфигурацию, в некоторых случаях вам всё же может подойти устаревшая конфигурация для определения снапшотов.

Снапшоты можно настраивать двумя основными способами:

* с помощью [специфичных для снапшотов конфигураций](#snapshot-specific-configurations)
* либо с помощью [общих конфигураций](#general-configuration)

Эти конфигурации позволяют управлять тем, как dbt обнаруживает изменения в данных и где хранятся снапшоты. Оба типа конфигураций могут сосуществовать в одном проекте и даже в одном `config`‑блоке (либо задаваться через файл `dbt_project.yml` или `properties.yaml`).

Одной из самых важных настроек является выбор [стратегии](#snapshot-strategies), которая определяет, каким образом dbt обнаруживает изменённые строки.

### Специфичные для снапшотов конфигурации

Специфичные для снапшотов конфигурации применяются только к одному типу ресурсов dbt, а не к нескольким сразу. Эти настройки можно определить непосредственно в файле ресурса с помощью макроса `{{ config() }}` (а также в файле проекта `dbt_project.yml` или в property‑файле, например `models/properties.yml` для моделей — аналогично и для других ресурсов).

snapshots/orders\_snapshot.sql

```sql
{ % snapshot orders_snapshot %}

{{ config(
    target_schema="<string>",
    target_database="<string>",
    unique_key="<column_name_or_expression>",
    strategy="timestamp" | "check",
    updated_at="<column_name>",
    check_cols=["<column_name>"] | "all"
    invalidate_hard_deletes=true | false
) 
}}

select * from {{ source('jaffle_shop', 'orders') }}

{% endsnapshot %}
```

### Общие конфигурации

Используйте общие конфигурации для более широких операционных настроек, применимых к нескольким типам ресурсов. Как и конфигурации, специфичные для ресурсов, их можно задавать в проектном YAML‑файле, в property‑файлах YAML или непосредственно в файлах ресурсов с помощью `config`‑блока.

snapshots/snapshot.sql

```sql
{{ 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={<dict>}
) }}
```

### Стратегии снапшотов

«Стратегии» снапшотов определяют, каким образом dbt понимает, что строка изменилась. В dbt встроены две стратегии, для которых требуется параметр `strategy`:

* [Timestamp](https://docs.getdbt.tech/reference/resource-configs/snapshots-jinja-legacy.md?strategy=timestamp#snapshot-strategies) — использует колонку `updated_at`, чтобы определить, изменилась ли строка.
* [Check](https://docs.getdbt.tech/reference/resource-configs/snapshots-jinja-legacy.md?strategy=check#snapshot-strategies) — сравнивает список колонок между текущими и историческими значениями, чтобы определить изменения. Использует параметр `check_cols`.

### Timestamp

Стратегия timestamp использует поле `updated_at` для определения изменений строки. Если значение `updated_at` для строки новее, чем время последнего запуска снапшота, dbt помечает старую запись как неактуальную и сохраняет новую. Если временные метки не изменились, dbt не предпринимает никаких действий.

#### Пример

snapshots/timestamp\_example.sql

```sql
{% snapshot orders_snapshot_timestamp %}

    {{
        config(
          target_schema='snapshots',
          strategy='timestamp',
          unique_key='id',
          updated_at='updated_at',
        )
    }}

    select * from {{ source('jaffle_shop', 'orders') }}

{% endsnapshot %}
```

### Check

Стратегия check полезна для таблиц, в которых нет надёжной колонки `updated_at`. Она требует параметр `check_cols`, который представляет собой список колонок из результата запроса снапшота, по которым проверяются изменения. В качестве альтернативы можно указать значение `all`, чтобы использовать все колонки (однако это может быть менее производительно).

#### Пример

snapshots/check\_example.sql

```sql
{% snapshot orders_snapshot_check %}

    {{
        config(
          strategy='check',
          unique_key='id',
          check_cols=['status', 'is_cancelled'],
        )
    }}

    select * from {{ source('jaffle_shop', 'orders') }}

{% endsnapshot %}
```

#### Примеры

 Проверка списка колонок на изменения

snapshots/check\_example.sql

```sql
{% snapshot orders_snapshot_check %}

    {{
        config(
          strategy='check',
          unique_key='id',
          check_cols=['status', 'is_cancelled'],
        )
    }}

    select * from {{ source('jaffle_shop', 'orders') }}

{% endsnapshot %}
```

 Проверка всех колонок на изменения

snapshots/check\_example.sql

```sql
{% snapshot orders_snapshot_check %}

    {{
        config(
          strategy='check',
          unique_key='id',
          check_cols='all',
        )
    }}

    select * from {{ source('jaffle_shop', 'orders') }}

{% endsnapshot %}
```

## Справочник конфигураций

Настройте снапшот, чтобы указать dbt, как определять изменения записей. Снапшоты — это `select`‑запросы, определённые внутри snapshot‑блока в `.sql`‑файле (обычно в директории `snapshots` или любой другой).

В таблице ниже перечислены конфигурации, доступные для снапшотов:

(Версии dbt: v1.9 и новее)

| Config                                                                                                       | Описание                                                                                                                         | Обязательно?                     | Пример      |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------- |
| [database](https://docs.getdbt.tech/reference/resource-configs/database.md)                                 | Указать пользовательскую базу данных для снапшота                                                                                | Нет                              | analytics   |
| [schema](https://docs.getdbt.tech/reference/resource-configs/schema.md)                                     | Указать пользовательскую схему для снапшота                                                                                      | Нет                              | snapshots   |
| [strategy](https://docs.getdbt.tech/reference/resource-configs/strategy.md)                                 | Стратегия снапшота: `timestamp` или `check`                                                                                      | Да                               | timestamp   |
| [unique\_key](https://docs.getdbt.tech/reference/resource-configs/unique_key.md)                            | Колонка или выражение первичный ключ, идентифицирующее запись                                                                    | Да                               | id          |
| [check\_cols](https://docs.getdbt.tech/reference/resource-configs/check_cols.md)                            | Колонки для проверки при использовании стратегии `check`                                                                         | Только при стратегии `check`     | \["status"] |
| [updated\_at](https://docs.getdbt.tech/reference/resource-configs/updated_at.md)                            | Колонка с временной меткой при использовании стратегии `timestamp`                                                               | Только при стратегии `timestamp` | updated\_at |
| [invalidate\_hard\_deletes](https://docs.getdbt.tech/reference/resource-configs/invalidate_hard_deletes.md) | Находить физически удалённые записи в источнике и устанавливать `dbt_valid_to` в текущее время, если запись больше не существует | Нет                              | True        |

* Также поддерживается ряд других конфигураций (например, `tags` и `post-hook`) — полный список смотрите [здесь](https://docs.getdbt.tech/reference/snapshot-configs.md).
* Снапшоты можно настраивать как через файл `dbt_project.yml`, так и через `config`‑блок — подробнее см. [документацию по конфигурации](https://docs.getdbt.tech/reference/snapshot-configs.md).
* Примечание: пользователи BigQuery могут использовать `target_project` и `target_dataset` как алиасы для `target_database` и `target_schema` соответственно.
* До версии v1.9 параметры `target_schema` (обязательный) и `target_database` (необязательный) задавали фиксированную схему или базу данных для снапшотов, что затрудняло разделение dev‑ и prod‑окружений. Начиная с v1.9 `target_schema` стал необязательным, что позволило использовать снапшоты с учётом окружения. По умолчанию снапшоты теперь используют `generate_schema_name` или `generate_database_name`, однако разработчики по‑прежнему могут указать пользовательское расположение с помощью [schema](https://docs.getdbt.tech/reference/resource-configs/schema.md) и [database](https://docs.getdbt.tech/reference/resource-configs/database.md), аналогично другим типам ресурсов.

## Добавление снапшота в проект

Чтобы добавить снапшот в проект:

1. Создайте файл в директории `snapshots` с расширением `.sql`. Например, `snapshots/orders.sql`.
2. Используйте блок `snapshot`, чтобы определить начало и конец снапшота:

snapshots/orders\_snapshot.sql

```sql
{% snapshot orders_snapshot %}

{% endsnapshot %}
```

3. Напишите `select`‑запрос внутри snapshot‑блока. Этот запрос определяет результат, который вы хотите отслеживать во времени. Здесь можно использовать `sources` или `refs`.

snapshots/orders\_snapshot.sql

```sql
{% snapshot orders_snapshot %}

select * from {{ source('jaffle_shop', 'orders') }}

{% endsnapshot %}
```

4. Проверьте, содержит ли результат запроса надёжную колонку с временной меткой, указывающую, когда запись была обновлена в последний раз. В нашем примере колонка `updated_at` надёжно отражает изменения, поэтому можно использовать стратегию `timestamp`. Если такой колонки нет, потребуется использовать стратегию `check`.

5. Добавьте конфигурации к снапшоту с помощью `config`‑блока. Также вы можете [настроить снапшот через файл `dbt_project.yml`](https://docs.getdbt.tech/reference/snapshot-configs.md).

(Версии dbt: v1.9 и новее)

snapshots/orders\_snapshot.sql

```sql
{% snapshot orders_snapshot %}

{{
    config(
      database='analytics',
      schema='snapshots',
      unique_key='id',

      strategy='timestamp',
      updated_at='updated_at',
    )
The following table outlines the configurations available for snapshots:

select * from {{ source('jaffle_shop', 'orders') }}

{% endsnapshot %}
```

6. Запустите [команду](https://docs.getdbt.tech/reference/commands/snapshot.md) `dbt snapshot`. В нашем примере будет создана новая таблица `analytics.snapshots.orders_snapshot`. Изменяя конфигурации `target_database`, `target_schema` и имя снапшота (заданное в `{% snapshot .. %}`), вы управляете тем, как dbt именует эту таблицу.

```dbt
Running with dbt=1.8.0

15:07:36 | Concurrency: 8 threads (target='dev')
15:07:36 |
15:07:36 | 1 of 1 START snapshot snapshots.orders_snapshot...... [RUN]
15:07:36 | 1 of 1 OK snapshot snapshots.orders_snapshot..........[SELECT 3 in 1.82s]
15:07:36 |
15:07:36 | Finished running 1 snapshots in 0.68s.

Completed successfully

Done. PASS=2 ERROR=0 SKIP=0 TOTAL=1
```

7. Проверьте результаты, выполнив `select` из таблицы, созданной dbt. После первого запуска вы увидите результат запроса, а также [метаполя снапшота](https://docs.getdbt.tech/docs/build/snapshots.md#snapshot-meta-fields).
8. Запустите `dbt snapshot` ещё раз и снова проверьте результаты. Если какие‑либо записи были обновлены, снапшот должен это отразить.
9. Используйте снапшот в downstream‑моделях с помощью функции `ref`.

models/changed\_orders.sql

```sql
select * from {{ ref('orders_snapshot') }}
```

10. Снапшоты полезны только при регулярном запуске — настройте выполнение команды `snapshot` по расписанию.

## Примеры

В этом разделе приведены примеры применения конфигураций к снапшотам с использованием устаревшего метода.

 Применение конфигураций только к одному снапшоту

Используйте `config`‑блоки, если нужно применить конфигурацию только к одному снапшоту.

snapshots/postgres\_app/orders\_snapshot.sql

```sql
{% snapshot orders_snapshot %}
    {{
        config(
          unique_key='id',
          strategy='timestamp',
          updated_at='updated_at'
        )
    }}
    -- Pro-Tip: Use sources in snapshots!
    select * from {{ source('jaffle_shop', 'orders') }}
{% endsnapshot %}
```

 Использование параметра updated\_at

Параметр `updated_at` обязателен при использовании стратегии timestamp. Это колонка в результате запроса снапшота, которая указывает, когда запись была обновлена в последний раз.

snapshots/orders.sql

```sql
{{ config(
  strategy="timestamp",
  updated_at="column_name"
) }}
```

#### Примеры

* #### Использование колонки `updated_at`:

  (Версии dbt: v1.9 и новее)

  snapshots/orders.sql

  ```sql
  {% snapshot orders_snapshot %}

  {{
      config(
        schema='snapshots',
        unique_key='id',

        strategy='timestamp',
        updated_at='updated_at'
      )
  }}

  select * from {{ source('jaffle_shop', 'orders') }}

  {% endsnapshot %}
  ```

* #### Объединение двух колонок для создания надёжного `updated_at`:

  Рассмотрим источник данных, в котором колонка `updated_at` заполняется только при обновлении записи (то есть значение `null` означает, что запись не обновлялась после создания).

  Поскольку параметр `updated_at` принимает только имя колонки, а не выражение, необходимо изменить запрос снапшота, добавив колонку с объединённым значением.

  (Версии dbt: v1.9 и новее)

  snapshots/orders.sql

  ```sql
  {% snapshot orders_snapshot %}

  {{
      config(
        schema='snapshots',
        unique_key='id',

        strategy='timestamp',
        updated_at='updated_at_for_snapshot'
      )
  }}

  select
      *,
      coalesce(updated_at, created_at) as updated_at_for_snapshot

  from {{ source('jaffle_shop', 'orders') }}

  {% endsnapshot %}
  ```

 Использование параметра unique\_key

Параметр `unique_key` — это имя колонки или выражение, уникальное для входных данных снапшота. dbt использует [`unique_key`](https://docs.getdbt.tech/reference/resource-configs/unique_key.md) для сопоставления записей между текущим результатом и существующим снапшотом, чтобы корректно фиксировать изменения.

snapshots/orders.sql

```sql
{{ config(
  unique_key="column_name"
) }}
```

#### Примеры

* Использование колонки `id` в качестве уникального ключа

  snapshots/orders.sql

  ```sql
  {{
      config(
        unique_key="id"
      )
  }}
  ```

  Это также можно задать в YAML. Это может быть удобно, если несколько снапшотов используют один и тот же `unique_key` (хотя мы предпочитаем задавать эту конфигурацию в `config`‑блоке, как показано выше).

* #### Использование комбинации двух колонок в качестве уникального ключа

  Эта конфигурация принимает допустимое колонковое выражение. Поэтому при необходимости можно объединить две колонки в один уникальный ключ. Рекомендуется использовать разделитель (например, `'-'`), чтобы обеспечить уникальность.

  snapshots/transaction\_items\_snapshot.sql

  ```sql
  {% snapshot transaction_items_snapshot %}

      {{
          config(
            unique_key="transaction_id||'-'||line_item_id",
            ...
          )
      }}

  select
      transaction_id||'-'||line_item_id as id,
      *
  from {{ source('erp', 'transactions') }}

  {% endsnapshot %}
  ```

  Однако, как правило, лучше сформировать эту колонку непосредственно в запросе и использовать её как `unique_key`:

  snapshots/transaction\_items\_snapshot.sql

  ```sql
  {% snapshot transaction_items_snapshot %}

      {{
          config(
            unique_key="id",
            ...
          )
      }}

  select
      transaction_id || '-' || line_item_id as id,
      *
  from {{ source('erp', 'transactions') }}

  {% endsnapshot %}
  ```
