Добавление снимков в ваш DAG

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

• Конфигурации снимков
• Свойства снимков
• Команда snapshot

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

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

Снимки реализуют тип-2 медленно изменяющихся измерений в изменяемых исходных таблицах. Эти медленно изменяющиеся измерения (или 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

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

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

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

Эта стратегия лучше обрабатывает добавление и удаление колонок, чем стратегия check.

 Используйте dbt_valid_to_current для упрощения запросов по диапазону дат

По умолчанию dbt_valid_to равно NULL для текущих записей. Однако, если вы установите конфигурацию dbt_valid_to_current (доступно в dbt Core v1.9+), dbt_valid_to будет установлено в указанное вами значение (например, 9999-12-31) для текущих записей.

Это позволяет легко фильтровать по диапазону дат.

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

Уникальный ключ используется dbt для сопоставления строк, поэтому крайне важно убедиться, что этот ключ действительно уникален! Если вы делаете снимок источника, я рекомендую добавить тест на уникальность в ваш источник (пример).

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

Когда вы запускаете команду dbt snapshot:

• При первом запуске: dbt создаст начальную таблицу снимков — это будет результирующий набор вашего select запроса с дополнительными колонками, включая dbt_valid_from и dbt_valid_to. Все записи будут иметь dbt_valid_to = null или значение, указанное в dbt_valid_to_current (доступно в dbt Core 1.9+), если настроено.
• При последующих запусках: dbt проверит, какие записи изменились или были созданы новые записи:
  • Колонка dbt_valid_to будет обновлена для всех существующих записей, которые изменились.
  • Обновленная запись и любые новые записи будут вставлены в таблицу снимков. Эти записи теперь будут иметь dbt_valid_to = null или значение, настроенное в dbt_valid_to_current (доступно в dbt Core v1.9+).

Снимки могут быть использованы в последующих моделях так же, как и модели — с помощью функции ref.

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

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

• Timestamp — Использует колонку updated_at, чтобы определить, изменилась ли строка.
• Check — Сравнивает список колонок между их текущими и историческими значениями, чтобы определить, изменилась ли строка.

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

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

Стратегия 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 Core v1.9+ (или доступно раньше в релизном треке "Latest" в dbt Cloud):

• Эти имена колонок могут быть настроены в соответствии с вашими командными или организационными соглашениями, используя конфигурацию snapshot_meta_column_names.
• Используйте конфигурацию dbt_valid_to_current, чтобы установить пользовательский индикатор для значения dbt_valid_to в текущих записях снимков (например, будущая дата, такая как 9999-12-31). По умолчанию это значение NULL. Когда установлено, dbt будет использовать это указанное значение вместо NULL для dbt_valid_to для текущих записей в таблице снимков.
• Используйте конфигурацию hard_deletes, чтобы отслеживать удаленные записи как новые строки с мета-полем dbt_is_deleted, когда используется поле hard_deletes='new_record'.

Поле	Значение	Использование
dbt_valid_from	Временная метка, когда эта строка снимка была впервые вставлена	Эта колонка может быть использована для упорядочивания различных "версий" записи.
dbt_valid_to	Временная метка, когда эта строка стала недействительной. Для текущих записей это NULL по умолчанию	Самая последняя запись снимка будет иметь dbt_valid_to, установленное в NULL
dbt_scd_id	Уникальный ключ, сгенерированный для каждой записи снимка.	Это используется внутренне dbt
dbt_updated_at	Временная метка updated_at исходной записи, когда эта строка снимка была вставлена.	Это используется внутренне dbt
dbt_is_deleted	Логическое значение, указывающее, была ли запись удалена. True, если удалена, False в противном случае.	Добавляется, когда настроено hard_deletes='new_record'. Это используется внутренне dbt

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

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

Подробности для стратегии timestamp

Результаты запроса снимка на 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

Результаты снимка (обратите внимание, что 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

Результаты снимка с 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 вместо этого, как и в стратегии timestamp.

Подробности для стратегии check

Результаты запроса снимка на 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

Настройка снимков в версиях 1.8 и ранее

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

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

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

$ dbt snapshot --select order_snapshot

Ознакомьтесь с документацией по синтаксису выбора моделей для получения информации о других операторах и примерах.

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

Снимки (snapshots) — это пакетный подход к захвату изменений данных. Команда dbt snapshot должна выполняться по расписанию, чтобы гарантировать, что изменения в таблицах действительно фиксируются! Хотя отдельные случаи использования могут различаться, снимки предназначены для выполнения с интервалом от часа до дня. Если вы обнаружите, что делаете снимки чаще, чем это, подумайте, нет ли более подходящего способа фиксировать изменения в ваших исходных таблицах данных.

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

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

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

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

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

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

• pre-hooks
• post-hooks
• on-run-start
• on-run-end

Могу ли я хранить свои снимки в каталоге, отличном от каталога `snapshot` в моем проекте?

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

Чтобы изменить это, обновите конфигурацию snapshot-paths в вашем файле dbt_project.yml, следующим образом:

dbt_project.yml

snapshot-paths: ["snapshots"]

Обратите внимание, что вы не можете размещать снимки и модели в одном и том же каталоге.

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

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

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

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

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

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

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

Это указывает на необходимость изменить конфигурацию materialized на snapshot. Но когда вы вносите это изменение, вы можете столкнуться с сообщением об ошибке, указывающим на отсутствие таких полей, как dbt_scd_id. Эта ошибка возникает потому, что ранее, когда dbt обрабатывал снимки как таблицы, он не включал необходимые мета-поля снимков в вашу целевую таблицу. Поскольку эти мета-поля отсутствуют, dbt правильно определяет, что вы пытаетесь создать снимок в таблице, которая на самом деле не является снимком.

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