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

## Связанная документация

* [Конфигурации снимков](https://docs.getdbt.tech/reference/snapshot-configs.md)
* [Свойства снимков](https://docs.getdbt.tech/reference/snapshot-properties.md)
* [Команда `snapshot`](https://docs.getdbt.tech/reference/commands/snapshot.md)
* [Выбор между инкрементальными моделями и снимками](https://docs.getdbt.tech/best-practices/how-we-handle-cdc/2-choosing-incremental-or-snapshots.md) — рекомендации по использованию снимков для отслеживания изменений данных (CDC)

Учитесь с помощью видео!

Чтобы посмотреть видеоуроки по теме Snapshots, перейдите в dbt Learn и ознакомьтесь с курсом [Snapshots](https://learn.getdbt.com/courses/snapshots).

## Что такое снимки?

Аналитикам часто нужно "оглядываться назад" на предыдущие состояния данных в изменяемых таблицах. Хотя некоторые системы исходных данных построены таким образом, что доступ к историческим данным возможен, это не всегда так. dbt предоставляет механизм, **снимки**, который фиксирует изменения в изменяемой таблица с течением времени.

Снимки реализуют [тип-2 медленно изменяющихся измерений](https://en.wikipedia.org/wiki/Slowly_changing_dimension#Type_2:_add_new_row) в изменяемых исходных таблицах. Эти медленно изменяющиеся измерения (или SCD) определяют, как строка в таблице изменяется с течением времени. Представьте, что у вас есть таблица `orders`, где поле `status` может быть перезаписано по мере обработки заказа.

| id | status  | updated\_at |
| -- | ------- | ----------- |
| 1  | pending | 2024-01-01  |

Теперь представьте, что заказ переходит из состояния "pending" в "shipped". Эта же запись теперь будет выглядеть так:

| id | status  | updated\_at |
| -- | ------- | ----------- |
| 1  | shipped | 2024-01-02  |

Этот заказ теперь в состоянии "shipped", но мы потеряли информацию о том, когда заказ в последний раз находился в состоянии "pending". Это затрудняет (или делает невозможным) анализ того, сколько времени потребовалось для отправки заказа. dbt может "сделать снимок" этих изменений, чтобы помочь вам понять, как значения в строке изменяются с течением времени. Вот пример таблицы снимков для предыдущего примера:

| id | status  | updated\_at | dbt\_valid\_from | dbt\_valid\_to |
| -- | ------- | ----------- | ---------------- | -------------- |
| 1  | pending | 2024-01-01  | 2024-01-01       | 2024-01-02     |
| 1  | shipped | 2024-01-02  | 2024-01-02       | `null`         |

## Конфигурирование снимков

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

Настраивайте свои snapshots в YAML-файлах, чтобы указать dbt, как обнаруживать изменения записей. Определяйте конфигурации snapshots в YAML-файлах рядом с вашими моделями — это обеспечивает более чистую, быструю и согласованную настройку. Размещайте YAML-файлы snapshots в директории models или в директории snapshots.

snapshots/orders\_snapshot.yml

```yaml
snapshots:
  - name: string
    relation: relation # source('my_source', 'my_table') или ref('my_model')
    description:  markdown_string
    config:
      database: string
      schema: string
      alias: string
      strategy: timestamp | check
      unique_key: column_name_or_expression
      check_cols: [column_name] | all
      updated_at: column_name
      snapshot_meta_column_names: dictionary
      dbt_valid_to_current: string
      hard_deletes: ignore | invalidate | new_record 
```

Следующая таблица описывает доступные конфигурации для снимков:

| Конфигурация                                                                                                        | Описание                                                                                                                                                                                                                                                                                           | Обязательно?                     | Пример                            |
| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | --------------------------------- |
| [database](https://docs.getdbt.tech/reference/resource-configs/database.md)                                        | Указать пользовательскую базу данных для snapshot                                                                                                                                                                                                                                                  | No                               | analytics                         |
| [schema](https://docs.getdbt.tech/reference/resource-configs/schema.md)                                            | Указать пользовательскую схему для snapshot                                                                                                                                                                                                                                                        | No                               | snapshots                         |
| [alias](https://docs.getdbt.tech/reference/resource-configs/alias.md)                                              | Указать алиас для snapshot                                                                                                                                                                                                                                                                         | No                               | your\_custom\_snapshot            |
| [strategy](https://docs.getdbt.tech/reference/resource-configs/strategy.md)                                        | Стратегия snapshot, которую следует использовать. Допустимые значения: `timestamp` или `check`                                                                                                                                                                                                     | Yes                              | timestamp                         |
| [unique\_key](https://docs.getdbt.tech/reference/resource-configs/unique_key.md)                                   | Колонка(и) первичный ключ (строка или массив) либо выражение, которое однозначно идентифицирует запись                                                                                                                                                                                             | Yes                              | `id` или `[order_id, product_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)                                   | Колонка в результатах snapshot‑запроса, которая указывает, когда каждая запись была обновлена в последний раз. Используется в стратегии `timestamp`. В зависимости от используемой платформы данных может поддерживать строки с датами в формате ISO и целочисленные значения unix epoch.          | Только для стратегии `timestamp` | updated\_at                       |
| [dbt\_valid\_to\_current](https://docs.getdbt.tech/reference/resource-configs/dbt_valid_to_current.md)             | Задать пользовательское значение для поля `dbt_valid_to` в актуальных записях snapshot (например, дату в будущем). По умолчанию это значение равно `NULL`. Если настройка задана, dbt будет использовать указанное значение вместо `NULL` для `dbt_valid_to` у текущих записей в таблице snapshot. | No                               | string                            |
| [snapshot\_meta\_column\_names](https://docs.getdbt.tech/reference/resource-configs/snapshot_meta_column_names.md) | Настроить имена мета‑полей snapshot                                                                                                                                                                                                                                                                | No                               | dictionary                        |
| [hard\_deletes](https://docs.getdbt.tech/reference/resource-configs/hard-deletes.md)                               | Указать, как обрабатывать удалённые строки из источника. Поддерживаемые варианты: `ignore` (по умолчанию), `invalidate` (заменяет устаревший `invalidate_hard_deletes=true`) и `new_record`.                                                                                                       | No                               | string                            |

* В v1.9 параметр `target_schema` стал необязательным, что позволяет снимкам учитывать окружение. По умолчанию, если `target_schema` и `target_database` не заданы, снимки теперь используют макросы `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), как и для других типов ресурсов.
* Также поддерживается ряд других конфигураций (например, `tags` и `post-hook`). Полный список см. в разделе [Конфигурации снимков](https://docs.getdbt.tech/reference/snapshot-configs.md).
* Снимки можно настраивать как в файле `dbt_project.yml`, так и в блоке `config`. Подробнее см. в [документации по конфигурациям](https://docs.getdbt.tech/reference/snapshot-configs.md).
* Начиная с dbt v1.12, вы можете просмотреть SQL, сгенерированный для снимков, выполнив команду [`dbt compile`](https://docs.getdbt.tech/reference/commands/compile.md). Скомпилированные SQL-файлы находятся в каталоге `target/compiled/` вашего проекта dbt.

Чтобы добавить снимок в ваш проект, выполните следующие шаги. Для пользователей версий 1.8 и ранее обратитесь к [Настройка снимков в версиях 1.8 и ранее](#configuring-snapshots).

Чтобы добавить снимок в проект, выполните следующие шаги. Для dbt 1.8 и более ранних версий см. [Настройки снимков в Jinja](https://docs.getdbt.tech/reference/resource-configs/snapshots-jinja-legacy.md).

1. Создайте YAML-файл с настройками в каталоге `snapshots`: `snapshots/orders_snapshot.yml` и добавьте в него параметры конфигурации. Также вы можете настроить snapshot из YAML-файла проекта (`dbt_project.yml`) ([docs](https://docs.getdbt.tech/reference/snapshot-configs.md)).

   snapshots/orders\_snapshot.yml

   ```yaml
   snapshots:
     - name: orders_snapshot
       relation: source('jaffle_shop', 'orders')
       config:
         schema: snapshots
         database: analytics
         unique_key: id
         strategy: timestamp
         updated_at: updated_at
         dbt_valid_to_current: "to_date('9999-12-31')" # Указывает, что текущие записи должны иметь `dbt_valid_to`, установленное в `'9999-12-31'` вместо `NULL`.
   ```

2. (Необязательно) Примените преобразования с помощью эфемерной модели. По умолчанию снимки ссылаются непосредственно на источник (как показано в YAML на предыдущем шаге). Если вам нужно применить преобразования (например, фильтрацию или дедупликацию), сначала определите эфемерную модель для выполнения этих преобразований и укажите ссылку на неё в поле relation снимка вместо прямого вызова `source()`.

   Например, вот модель с материализацией `ephemeral`:

   models/ephemeral\_orders.sql

   ```sql
   {{ config(materialized='ephemeral') }}

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

   Так можно сослаться на модель с материализацией `ephemeral` в поле `relation`:

   snapshots/orders\_snapshot.yml

   ```yaml
     snapshots:
       - name: orders_snapshot
         relation: ref('ephemeral_orders')
         ... rest of config...
   ```

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

4. Запустите команду `dbt snapshot` [command](https://docs.getdbt.tech/reference/commands/snapshot.md) — в нашем примере будет создана новая таблица в `analytics.snapshots.orders_snapshot`. Конфигурация [`schema`](https://docs.getdbt.tech/reference/resource-configs/schema.md) будет использовать макрос `generate_schema_name`.

   ```text
   $ dbt snapshot
   Running with dbt=1.9.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
   ```

Скомпилированный SQL для снимков

Начиная с dbt v1.12, вы можете просмотреть SQL, сгенерированный для этого снимка, выполнив [`dbt compile`](https://docs.getdbt.tech/reference/commands/compile.md) или `dbt compile --select orders_snapshot`.

Откройте скомпилированный SQL в `target/compiled/`, чтобы изучить сгенерированные запросы или выполнить их отладку. Каждый снимок компилируется в отдельный SQL-файл, даже если в одном исходном файле определено несколько снимков.

5. Проверьте результаты, выполнив запрос к таблице, созданной dbt (`analytics.snapshots.orders_snapshot`). После первого запуска вы должны увидеть результаты вашего запроса, а также [поля метаданных снимка](#snapshot-meta-fields), описанные ниже.

6. Запустите команду `dbt snapshot` снова и проверьте результаты. Если какие-либо записи были обновлены, снимок должен это отразить.

7. Выберите из `snapshot` в последующих моделях, используя функцию `ref`.

   models/changed\_orders.sql

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

8. Снимки полезны только в том случае, если вы запускаете их часто — запланируйте регулярный запуск команды `dbt snapshot`.

### Лучшие практики конфигурации

 Используйте стратегию timestamp, где это возможно

Стратегия `timestamp` рекомендуется, потому что она более эффективно обрабатывает добавление и удаление колонок по сравнению со стратегией `check`. Это связано с тем, что она более устойчива к изменениям схемы, особенно когда со временем в таблице появляются новые колонки или удаляются существующие.

Стратегия `timestamp` опирается на одно поле `updated_at`, что позволяет избежать необходимости постоянно обновлять конфигурацию snapshot’а по мере эволюции исходной таблицы.

Почему `timestamp` — предпочтительная стратегия:

* Требуется отслеживать только одну колонку (`updated_at`)
* Автоматически обрабатывает появление новых или удаление существующих колонок в исходной таблице
* Меньше подвержена ошибкам при изменении схемы таблицы со временем (например, при использовании стратегии `check` может потребоваться обновлять параметр `check_cols`)

 Используйте dbt\_valid\_to\_current для упрощения запросов по диапазону дат

По умолчанию `dbt_valid_to` равно `NULL` для текущих записей. Однако, если вы установите [конфигурацию `dbt_valid_to_current`](https://docs.getdbt.tech/reference/resource-configs/dbt_valid_to_current.md) (доступно в dbt Core v1.9+), `dbt_valid_to` будет установлено в указанное вами значение (например, `9999-12-31`) для текущих записей.

По умолчанию `dbt_valid_to` имеет значение `NULL` для текущих записей. Однако если вы зададите [конфигурацию `dbt_valid_to_current`](https://docs.getdbt.tech/reference/resource-configs/dbt_valid_to_current.md) (доступна в dbt v1.9 и новее), для текущих записей `dbt_valid_to` будет принимать указанное вами значение (например, `9999-12-31`).

Это упрощает фильтрацию по диапазону дат.

 Убедитесь, что ваш уникальный ключ действительно уникален

Уникальный ключ используется dbt для сопоставления строк, поэтому крайне важно убедиться, что этот ключ действительно уникален! Если вы делаете снимок источника, я рекомендую добавить тест на уникальность в ваш источник ([пример](https://github.com/dbt-labs/jaffle_shop/blob/8e7c853c858018180bef1756ec93e193d9958c5b/models/staging/schema.yml#L26)).

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

 Используйте схему, отличную от схемы ваших моделей

Снимки не могут быть перестроены. Поэтому, хорошей идеей будет поместить снимки в отдельную схему, чтобы конечные пользователи знали, что они особенные. Оттуда вы можете установить разные привилегии на ваши снимки по сравнению с вашими моделями, и даже запускать их как другой пользователь (или роль, в зависимости от вашего хранилища данных), чтобы сделать очень сложным удаление снимка, если вы действительно этого не хотите.

 Используйте эфемерную модель для очистки или трансформации данных перед созданием снимка

Если вам нужно очистить или трансформировать ваши данные перед созданием снимка, создайте эфемерную модель или модель стадии, которая применяет необходимые трансформации. Затем, ссылайтесь на эту модель в вашей конфигурации снимка. Этот подход позволяет держать ваши определения снимков чистыми и позволяет тестировать и запускать трансформации отдельно.

### Как работают снимки

Когда вы запускаете команду [`dbt snapshot`](https://docs.getdbt.tech/reference/commands/snapshot.md):

* **При первом запуске:** dbt создаст исходную таблицу снимка — она будет содержать результат вашего оператора `select` с дополнительными столбцами, включая `dbt_valid_from` и `dbt_valid_to`. У всех записей будет `dbt_valid_to = null` или значение, указанное в [`dbt_valid_to_current`](https://docs.getdbt.tech/reference/resource-configs/dbt_valid_to_current.md) (доступно в dbt 1.9+), если этот параметр настроен.

* **При последующих запусках:** dbt проверит, какие записи изменились и появились ли новые записи:

  * Для всех существующих записей, которые изменились, будет обновлён столбец `dbt_valid_to`.
  * Обновлённая запись и все новые записи будут вставлены в таблицу снимка. У этих записей будет `dbt_valid_to = null` или значение, настроенное в `dbt_valid_to_current` (доступно в dbt v1.9+).

Снапшоты игнорируют полное обновление

Снапшоты игнорируют как параметр конфигурации `full_refresh`, так и флаг `--full-refresh`. Команда, например `dbt build --full-refresh` или `dbt snapshot --full-refresh`, включающая узел снапшота, выполняет его в обычном режиме — таблица снапшота не удаляется и не создаётся заново, поэтому существующая история снапшота сохраняется.

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

#### Примечание

* Эти имена колонок могут быть настроены в соответствии с вашими командными или организационными соглашениями, используя конфигурацию [snapshot\_meta\_column\_names](#snapshot-meta-fields).
* Используйте конфигурацию `dbt_valid_to_current`, чтобы установить пользовательский индикатор для значения `dbt_valid_to` в текущих записях снимков (например, будущая дата, такая как `9999-12-31`). По умолчанию это значение `NULL`. Когда установлено, dbt будет использовать это указанное значение вместо `NULL` для `dbt_valid_to` для текущих записей в таблице снимков.
* Используйте конфигурацию [`hard_deletes`](https://docs.getdbt.tech/reference/resource-configs/hard-deletes.md), чтобы отслеживать жесткие удаления, добавляя новую запись, когда строка становится "удаленной" в источнике. Поддерживаемые опции: `ignore`, `invalidate` и `new_record`.

Снимки могут быть использованы в последующих моделях так же, как и модели — с помощью функции [ref](https://docs.getdbt.tech/reference/dbt-jinja-functions/ref.md).

## Обнаружение изменений строк

Стратегии снимков определяют, как dbt узнает, изменилась ли строка. В dbt встроены две стратегии:

* [Timestamp](#timestamp-strategy-recommended) — Использует колонку `updated_at`, чтобы определить, изменилась ли строка.
* [Check](#check-strategy) — Сравнивает список колонок между их текущими и историческими значениями, чтобы определить, изменилась ли строка.

### Стратегия Timestamp (рекомендуется)

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

Почему рекомендуется использовать `timestamp`?

* Требуется отслеживать только одну колонку (`updated_at`)
* Автоматически обрабатывает появление новых или удаление существующих колонок в исходной таблице
* Меньше подвержен ошибкам при эволюции схемы таблицы со временем (например, при использовании стратегии `check` может потребоваться обновлять конфигурацию `check_cols`)

Стратегия `timestamp` требует следующих настроек:

| Конфигурация | Описание                                                                                                                                                                                      | Пример       |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| updated\_at  | Столбец, который отражает момент последнего обновления строки источника. В зависимости от используемой платформы данных может поддерживать строки дат в формате ISO и целые числа unix epoch. | `updated_at` |

**Пример использования:**

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

snapshots/orders\_snapshot.yml

```yaml
snapshots:
  - name: orders_snapshot_timestamp
    relation: source('jaffle_shop', 'orders')
    config:
      schema: snapshots
      unique_key: id
      strategy: timestamp
      updated_at: updated_at
```

### Стратегия Check

Стратегия `check` полезна для таблиц, которые не имеют надежной колонки `updated_at`. Эта стратегия работает, сравнивая список колонок между их текущими и историческими значениями. Если какая-либо из этих колонок изменилась, то dbt аннулирует старую запись и запишет новую. Если значения колонок идентичны, то dbt не предпримет никаких действий.

Стратегия `check` требует следующих конфигураций:

| Конфигурация | Описание                                                                  | Пример              |
| ------------ | ------------------------------------------------------------------------- | ------------------- |
| check\_cols  | Список колонок для проверки изменений или `all` для проверки всех колонок | `["name", "email"]` |

check\_cols = 'all'

Стратегия снимков `check` может быть настроена для отслеживания изменений *всех* колонок, указав `check_cols = 'all'`. Лучше явно перечислить колонки, которые вы хотите проверить. Рассмотрите возможность использования суррогатный ключ для конденсации многих колонок в одну.

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

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

snapshots/orders\_snapshot.yml

```yaml
snapshots:
  - name: orders_snapshot_check
    relation: source('jaffle_shop', 'orders')
    config:
      schema: snapshots
      unique_key: id
      strategy: check
      check_cols:
        - status
        - is_cancelled
```

#### Пример использования с `updated_at`

При использовании стратегии `check` dbt отслеживает изменения, сравнивая значения в `check_cols`. По умолчанию dbt использует текущее время выполнения, чтобы заполнять поля `dbt_updated_at`, `dbt_valid_from` и `dbt_valid_to`. При этом вы можете дополнительно указать колонку `updated_at`:

* Если `updated_at` настроена, стратегия `check` будет использовать эту колонку вместо времени выполнения, аналогично стратегии `timestamp`.
* Если значение `updated_at` равно null, dbt по умолчанию использует текущее время.

Рассмотрим следующий пример, который показывает, как использовать стратегию `check` с `updated_at`:

```yaml
snapshots:
  - name: orders_snapshot
    relation: ref('stg_orders')
    config:
      schema: snapshots
      unique_key: order_id
      strategy: check
      check_cols:
        - status
        - is_cancelled
      updated_at: updated_at
```

В этом примере:

* Если изменяется хотя бы одно из указанных значений в `check_cols`, снапшот создаёт новую строку. Если колонка `updated_at` содержит значение (не равна null), снапшот использует его; в противном случае используется текущее время.
* Если `updated_at` не задана, dbt автоматически возвращается к [использованию текущего времени](#check-strategy) для отслеживания изменений.
* Используйте этот подход, если ваша колонка `updated_at` не всегда надёжна для отслеживания обновлений записей, но вы всё равно хотите применять её — вместо времени выполнения снапшота — когда изменения строк всё же обнаружены.

### Жёсткие удаления (opt-in)

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

В dbt v1.9 и выше конфигурация [`hard_deletes`](https://docs.getdbt.tech/reference/resource-configs/hard-deletes.md) заменяет конфигурацию `invalidate_hard_deletes`, чтобы дать вам больше контроля над тем, как обрабатывать удаленные строки из источника. Конфигурация `hard_deletes` не является отдельной стратегией, а дополнительной опцией, которую можно использовать с любой стратегией снимков.

Конфигурация `hard_deletes` имеет три опции/поля:

| Поле                    | Описание                                                                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `ignore` (по умолчанию) | Нет действий для удаленных записей.                                                                                                 |
| `invalidate`            | Ведет себя так же, как существующий `invalidate_hard_deletes=true`, где удаленные записи аннулируются, устанавливая `dbt_valid_to`. |
| `new_record`            | Отслеживает удаленные записи как новые строки, используя мета-поле `dbt_is_deleted`, когда записи удаляются.                        |

 Когда использовать конфигурации hard\_deletes и invalidate\_hard\_deletes?

**Используйте `invalidate_hard_deletes` (v1.8 и ранее), если:**

* Пробелы в истории снимков (отсутствие записей для удаленных строк) допустимы.
* Вы хотите аннулировать удаленные строки, установив для их временной метки `dbt_valid_to` текущее время (неявное удаление).
* Вы работаете с небольшими наборами данных, где отслеживание удалений как отдельного состояния не требуется.

**Используйте `hard_deletes: new_record` (v1.9 и выше), если:**

* Вы хотите поддерживать непрерывную историю снимков без пробелов.
* Вы хотите явно отслеживать удаления, добавляя новые строки с колонкой `dbt_is_deleted` (явное удаление).
* Вы работаете с большими наборами данных, где явное отслеживание удаленных записей улучшает ясность происхождения данных.

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

snapshots/orders\_snapshot.yml

```yaml
snapshots:
  - name: orders_snapshot_hard_delete
    relation: source('jaffle_shop', 'orders')
    config:
      schema: snapshots
      unique_key: id
      strategy: timestamp
      updated_at: updated_at
      hard_deletes: new_record  # опции: 'ignore', 'invalidate' или 'new_record'
```

В этом примере конфигурация `hard_deletes: new_record` добавит новую строку для удаленных записей с колонкой `dbt_is_deleted`, установленной в `True`. Любые восстановленные записи добавляются как новые строки с полем `dbt_is_deleted`, установленным в `False`.

Результирующая таблица будет выглядеть так:

| id | status   | updated\_at      | dbt\_valid\_from | dbt\_valid\_to   | dbt\_is\_deleted |
| -- | -------- | ---------------- | ---------------- | ---------------- | ---------------- |
| 1  | pending  | 2024-01-01 10:47 | 2024-01-01 10:47 | 2024-01-01 11:05 | False            |
| 1  | shipped  | 2024-01-01 11:05 | 2024-01-01 11:05 | 2024-01-01 11:20 | False            |
| 1  | deleted  | 2024-01-01 11:20 | 2024-01-01 11:20 |                  | True             |
| 1  | restored | 2024-01-01 12:00 | 2024-01-01 12:00 |                  | False            |

## Метаполя snapshot

Таблицы снимков создаются как копия исходного набора данных с дополнительными полями метаданных.

В dbt версии 1.9 и выше (или раньше — в [канале обновлений **v1 Latest** на dbt platform](https://docs.getdbt.tech/docs/dbt-versions/dbt-release-tracks.md)):

* Имена этих столбцов можно настроить в соответствии с соглашениями вашей команды или организации с помощью параметра [`snapshot_meta_column_names`](https://docs.getdbt.tech/reference/resource-configs/snapshot_meta_column_names.md).
* Используйте [параметр `dbt_valid_to_current`](https://docs.getdbt.tech/reference/resource-configs/dbt_valid_to_current.md), чтобы задать собственное значение `dbt_valid_to` для текущих записей снимка (например, дату в будущем, такую как `9999-12-31`). По умолчанию это значение равно `NULL`. Если параметр задан, dbt будет использовать указанное значение вместо `NULL` для `dbt_valid_to` в текущих записях таблицы снимка.
* Используйте параметр [`hard_deletes`](https://docs.getdbt.tech/reference/resource-configs/hard-deletes.md) со значением `hard_deletes='new_record'`, чтобы отслеживать удалённые записи, добавляя новые строки с полем метаданных `dbt_is_deleted`.

| Field            | Значение                                                                                                                                                                    | Примечания                                                                                                                                                                                                                                                                   | Пример                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `dbt_valid_from` | Метка времени, с которой эта строка снимка стала действительной.                                                                                                            | Используется для упорядочивания версий записи. Для конкретной строки это значение часто совпадает с `dbt_updated_at`, но эти поля имеют разный смысл. Примеры для каждой стратегии см. в разделе [Метки времени стратегии и метаполей](#strategy-and-meta-field-timestamps). | `snapshot_meta_column_names: {dbt_valid_from: start_date}`    |
| `dbt_valid_to`   | Метка времени, с которой эта строка перестала быть действительной. Для текущих записей по умолчанию имеет значение `NULL` или значение, указанное в `dbt_valid_to_current`. | У самой последней записи снимка поле `dbt_valid_to` будет иметь значение `NULL` или указанное значение.                                                                                                                                                                      | `snapshot_meta_column_names: {dbt_valid_to: end_date}`        |
| `dbt_scd_id`     | Уникальный ключ, генерируемый для каждой строки снимка.                                                                                                                     | Используется внутри dbt для идентификации каждой SCD-версии. О том, как dbt формирует этот ключ, см. в разделе [Как вычисляется dbt\_scd\_id](https://docs.getdbt.tech/reference/resource-configs/snapshot_meta_column_names.md#how-dbtscdid-is-calculated).                | `snapshot_meta_column_names: {dbt_scd_id: scd_id}`            |
| `dbt_updated_at` | Метка времени изменения исходной записи на момент вставки этой строки снимка.                                                                                               | Используется внутри dbt. В разделе [Метки времени стратегии и метаполей](#strategy-and-meta-field-timestamps) описано, каким значением заполняется этот столбец для каждой стратегии.                                                                                        | `snapshot_meta_column_names: {dbt_updated_at: modified_date}` |
| `dbt_is_deleted` | Строковое значение, указывающее, удалена ли запись. (`True`, если удалена, `False`, если не удалена).                                                                       | Добавляется, если настроено `hard_deletes='new_record'`.                                                                                                                                                                                                                     | `snapshot_meta_column_names: {dbt_is_deleted: is_deleted}`    |

Все эти имена колонок можно настроить с помощью конфига `snapshot_meta_column_names`. Подробнее см. в этом [примере](https://docs.getdbt.tech/reference/resource-configs/snapshot_meta_column_names.md#example).

При вставке значения `dbt_valid_from` и `dbt_updated_at` устанавливаются на основе одного и того же значения. Они обозначают начало периода действия и время зарегистрированного изменения соответственно.

### Стратегия и временные метки метаполей

Временные метки, используемые для каждого столбца, зависят от выбранной стратегии:

* Для стратегии `timestamp` настроенная колонка `updated_at` используется для заполнения колонок `dbt_valid_from`, `dbt_valid_to` и `dbt_updated_at`.

   Пример результатов для стратегии timestamp

  Результаты snapshot‑запроса на момент `2024-01-01 11:00`

  | id | status  | updated\_at      |
  | -- | ------- | ---------------- |
  | 1  | pending | 2024-01-01 10:47 |

  Результаты снапшота (обратите внимание, что `11:00` нигде не используется):

  | id | status  | updated\_at      | dbt\_valid\_from | dbt\_valid\_to | dbt\_updated\_at |
  | -- | ------- | ---------------- | ---------------- | -------------- | ---------------- |
  | 1  | pending | 2024-01-01 10:47 | 2024-01-01 10:47 |                | 2024-01-01 10:47 |

  Результаты запроса на момент `2024-01-01 11:30`:

  | id | status  | updated\_at      |
  | -- | ------- | ---------------- |
  | 1  | shipped | 2024-01-01 11:05 |

  Результаты snapshot (обратите внимание, что `11:30` нигде не используется):

  | id | status  | updated\_at      | dbt\_valid\_from | dbt\_valid\_to   | dbt\_updated\_at |
  | -- | ------- | ---------------- | ---------------- | ---------------- | ---------------- |
  | 1  | pending | 2024-01-01 10:47 | 2024-01-01 10:47 | 2024-01-01 11:05 | 2024-01-01 10:47 |
  | 1  | shipped | 2024-01-01 11:05 | 2024-01-01 11:05 |                  | 2024-01-01 11:05 |

  Результаты snapshot при `hard_deletes='new_record'`:

  | id | status  | updated\_at      | dbt\_valid\_from | dbt\_valid\_to   | dbt\_updated\_at | dbt\_is\_deleted |
  | -- | ------- | ---------------- | ---------------- | ---------------- | ---------------- | ---------------- |
  | 1  | pending | 2024-01-01 10:47 | 2024-01-01 10:47 | 2024-01-01 11:05 | 2024-01-01 10:47 | False            |
  | 1  | shipped | 2024-01-01 11:05 | 2024-01-01 11:05 | 2024-01-01 11:20 | 2024-01-01 11:05 | False            |
  | 1  | deleted | 2024-01-01 11:20 | 2024-01-01 11:20 |                  | 2024-01-01 11:20 | True             |

* Для стратегии `check` текущая временная метка используется для заполнения каждого столбца. Если настроено, стратегия `check` вместо этого использует столбец `updated_at`, как и стратегия временных меток.

 Пример результатов для стратегии check

Результаты snapshot-запроса на момент `2024-01-01 11:00`

| id | status  |
| -- | ------- |
| 1  | pending |

Результаты снимка:

| id | status  | dbt\_valid\_from | dbt\_valid\_to | dbt\_updated\_at |
| -- | ------- | ---------------- | -------------- | ---------------- |
| 1  | pending | 2024-01-01 11:00 |                | 2024-01-01 11:00 |

Результаты запроса на момент `2024-01-01 11:30`:

| id | status  |
| -- | ------- |
| 1  | shipped |

Результаты снимка:

| id | status  | dbt\_valid\_from | dbt\_valid\_to   | dbt\_updated\_at |
| -- | ------- | ---------------- | ---------------- | ---------------- |
| 1  | pending | 2024-01-01 11:00 | 2024-01-01 11:30 | 2024-01-01 11:00 |
| 1  | shipped | 2024-01-01 11:30 |                  | 2024-01-01 11:30 |

Результаты снимка с `hard_deletes='new_record'`:

| id | status  | dbt\_valid\_from | dbt\_valid\_to   | dbt\_updated\_at | dbt\_is\_deleted |
| -- | ------- | ---------------- | ---------------- | ---------------- | ---------------- |
| 1  | pending | 2024-01-01 11:00 | 2024-01-01 11:30 | 2024-01-01 11:00 | False            |
| 1  | shipped | 2024-01-01 11:30 | 2024-01-01 11:40 | 2024-01-01 11:30 | False            |
| 1  | deleted | 2024-01-01 11:40 |                  | 2024-01-01 11:40 | True             |

## Часто задаваемые вопросы

Как запустить один снимок за раз?

Чтобы запустить один снимок, используйте флаг `--select`, за которым следует имя снимка:

```shell
$ dbt snapshot --select order_snapshot
```

Ознакомьтесь с [документацией по синтаксису выбора моделей](https://docs.getdbt.tech/reference/node-selection/syntax.md) для получения информации о других операторах и примерах.

Как часто следует запускать команду snapshot?

Снимки — это подход к [отслеживанию изменений данных](https://en.wikipedia.org/wiki/Change_data_capture), основанный на пакетной обработке. Команду `dbt snapshot` необходимо запускать по расписанию, чтобы изменения в таблицах действительно фиксировались! Хотя конкретные сценарии использования могут различаться, снимки рассчитаны на запуск с периодичностью от одного раза в час до одного раза в сутки. Если вы создаёте снимки чаще, подумайте, нет ли более подходящего способа фиксировать изменения в таблицах исходных данных.

Рекомендации о том, когда использовать снимки, а когда — инкрементальные модели, приведены в разделе [Выбор между инкрементальными моделями и снимками](https://docs.getdbt.tech/best-practices/how-we-handle-cdc/2-choosing-incremental-or-snapshots.md).

Что произойдет, если я добавлю новые столбцы в запрос снимка?

Когда столбцы вашего исходного запроса изменяются, dbt попытается урегулировать это изменение в целевом снимке таблица. dbt делает это следующим образом:

1. Создает новые столбцы из исходного запроса в целевой таблице
2. Расширяет размер строковых типов, где это необходимо (например, `varchar` в Redshift)

dbt *не будет* удалять столбцы в целевой таблице снимка, если они удалены из исходного запроса. Он также не будет изменять тип столбца, за исключением увеличения размера столбцов типа varchar. То есть, если столбец `string` изменен на столбец `date` в исходном запросе снимка, dbt не будет пытаться изменить тип столбца в целевой таблице.

Выполняются ли хуки со снапшотами?

Да! Для снапшотов доступны следующие хуки:

* [pre-hooks](https://docs.getdbt.tech/reference/resource-configs/pre-hook-post-hook.md)
* [post-hooks](https://docs.getdbt.tech/reference/resource-configs/pre-hook-post-hook.md)
* [on-run-start](https://docs.getdbt.tech/reference/project-configs/on-run-start-on-run-end.md)
* [on-run-end](https://docs.getdbt.tech/reference/project-configs/on-run-start-on-run-end.md)

Могу ли я хранить snapshot’ы в директории, отличной от директории \`snapshot\` в моем проекте?

По умолчанию dbt ожидает, что файлы snapshot’ов будут находиться в поддиректории `snapshots` вашего проекта.

Чтобы изменить это, обновите настройку [snapshot-paths](https://docs.getdbt.tech/reference/project-configs/snapshot-paths.md) в файле `dbt_project.yml` следующим образом:

dbt\_project.yml

```yml
snapshot-paths: ["snapshots"]
```

Обратите внимание, что нельзя размещать snapshot’ы и модели в одной и той же директории.

Ошибка: Целевая таблица снимка не является таблицей снимков

Если вы видите следующую ошибку при попытке выполнить команду snapshot:

> Целевая таблица снимка не является таблицей снимков (отсутствуют `dbt_scd_id`, `dbt_valid_from`, `dbt_valid_to`)

Убедитесь, что вы случайно не заставили ваш снимок вести себя как материализация таблицы, установив его конфигурацию `materialized` в значение `table`. До версии dbt 1.4 было возможно создать снимок следующим образом:

```sql
{% snapshot snappy %}
  {{ config(materialized = 'table', ...) }}
  ...
{% endsnapshot %}
```

dbt обрабатывал снимки как таблицы (выполняя команды `create or replace table ...`) **без предупреждения**, вместо того чтобы фактически создавать снимки данных (SCD2 через команды `insert` / `merge`). При обновлении до версий dbt 1.4 и выше, dbt теперь выдает ошибку разбора (вместо того чтобы молча обрабатывать снимки как таблицы), которая гласит:

```text
Снимок должен иметь значение materialized 'snapshot'
```

Это указывает на необходимость изменить конфигурацию `materialized` на `snapshot`. Но когда вы вносите это изменение, вы можете столкнуться с сообщением об ошибке, указывающим на отсутствие таких полей, как `dbt_scd_id`. Эта ошибка возникает потому, что ранее, когда dbt обрабатывал снимки как таблицы, он не включал необходимые [мета-поля снимков](https://docs.getdbt.tech/docs/build/snapshots.md#snapshot-meta-fields) в вашу целевую таблицу. Поскольку эти мета-поля отсутствуют, dbt правильно определяет, что вы пытаетесь создать снимок в таблице, которая на самом деле не является снимком.

Когда это происходит, вам нужно начать с нуля — повторно создать снимок ваших исходных данных, как если бы это было в первый раз, удалив ваш "снимок", который не является настоящей таблицей снимков. Затем dbt snapshot создаст новый снимок и вставит мета-поля снимка, как и ожидалось.
