Добавление снапшотов в ваш DAG
Связанная документация
- Конфигурации снимков
- Свойства снимков
- Команда
snapshot - Выбор между инкрементальными моделями и снимками — рекомендации по использованию снимков для отслеживания изменений данных (CDC)
Что такое снимки?
Аналитикам часто нужно "оглядываться назад" на предыдущие состояния данных в изменяемых таблицах. Хотя некоторые системы исходных данных построены таким образом, что доступ к историческим данным возможен, это не всегда так. 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 |
Конфигурирование снимков
(Версии dbt: v1.9 и новее)Настраивайте свои snapshots в YAML-файлах, чтобы указать dbt, как обнаруживать изменения записей. Определяйте конфигурации snapshots в YAML-файлах рядом с вашими моделями — это обеспечивает более чистую, быструю и согласованную настройку. Размещайте YAML-файлы snapshots в директории models или в директории snapshots.
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 | Указать пользовательскую базу данных для snapshot | No | analytics |
| schema | Указать пользовательскую схему для snapshot | No | snapshots |
| alias | Указать алиас для snapshot | No | your_custom_snapshot |
| strategy | Стратегия snapshot, которую следует использовать. Допустимые значения: timestamp или check | Yes | timestamp |
| unique_key | Колонка(и) первичный ключ (строка или массив) либо выражение, которое однозначно идентифицирует запись | Yes | id или [order_id, product_id] |
| check_cols | При использовании стратегии check — колонки, которые нужно проверять | Только для стратегии check | ["status"] |
| updated_at | Колонка в результатах snapshot‑запроса, которая указывает, когда каждая запись была обновлена в последний раз. Используется в стратегии timestamp. В зависимости от используемой платформы данных может поддерживать строки с датами в формате ISO и целочисленные значения unix epoch. | Только для стратегии timestamp | updated_at |
| dbt_valid_to_current | Задать пользовательское значение для поля dbt_valid_to в актуальных записях snapshot (например, дату в будущем). По умолчанию это значение равно NULL. Если настройка задана, dbt будет использовать указанное значение вместо NULL для dbt_valid_to у текущих записей в таблице snapshot. | No | string |
| snapshot_meta_column_names | Настроить имена мета‑полей snapshot | No | dictionary |
| hard_deletes | Указать, как обрабатывать удалённые строки из источника. Поддерживаемые варианты: 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иdatabase, как и для других типов ресурсов. - Также поддерживается ряд других конфигураций (например,
tagsиpost-hook). Полный список см. в разделе Конфигурации снимков. - Снимки можно настраивать как в файле
dbt_project.yml, так и в блокеconfig. Подробнее см. в документации по конфигурациям. - Начиная с dbt v1.12, вы можете просмотреть SQL, сгенерированный для снимков, выполнив команду
dbt compile. Скомпилированные SQL-файлы находятся в каталогеtarget/compiled/вашего проекта dbt.
Чтобы добавить снимок в ваш проект, выполните следующие шаги. Для пользователей версий 1.8 и ранее обратитесь к Настройка снимков в версиях 1.8 и ранее.
Чтобы добавить снимок в проект, выполните следующие шаги. Для dbt 1.8 и более ранних версий см. Настройки снимков в Jinja.
-
Создайте YAML-файл с настройками в каталоге
snapshots:snapshots/orders_snapshot.ymlи добавьте в него параметры конфигурации. Также вы можете настроить snapshot из YAML-файла проекта (dbt_project.yml) (docs).snapshots/orders_snapshot.ymlsnapshots:
- 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`. -
(Необязательно) Примените преобразования с помощью эфемерной модели. По умолчанию снимки ссылаются непосредственно на источник (как показано в YAML на предыдущем шаге). Если вам нужно применить преобразования (например, фильтрацию или дедупликацию), сначала определите эфемерную модель для выполнения этих преобразований и укажите ссылку на неё в поле relation снимка вместо прямого вызова
source().Например, вот модель с материализацией
ephemeral:models/ephemeral_orders.sql{{ config(materialized='ephemeral') }}
select * from {{ source('jaffle_shop', 'orders') }}Так можно сослаться на модель с материализацией
ephemeralв полеrelation:snapshots/orders_snapshot.ymlsnapshots:
- name: orders_snapshot
relation: ref('ephemeral_orders')
... rest of config... -
Проверьте, включает ли результирующий набор вашего запроса надежную колонку с временной меткой, которая указывает, когда запись была в последний раз обновлена. В нашем примере колонка
updated_atнадежно указывает изменения записей, поэтому мы можем использовать стратегиюtimestamp. Если в результирующем наборе вашего запроса нет надежной временной метки, вам нужно будет использовать стратегиюcheck— подробнее об этом ниже. -
Запустите команду
dbt snapshotcommand — в нашем примере будет создана новая таблица вanalytics.snapshots.orders_snapshot. Конфигурацияschemaбудет использовать макросgenerate_schema_name.$ 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
Начиная с dbt v1.12, вы можете просмотреть SQL, сгенерированный для этого снимка, выполнив dbt compile или dbt compile --select orders_snapshot.
Откройте скомпилированный SQL в target/compiled/, чтобы изучить сгенерированные запросы или выполнить их отладку. Каждый снимок компилируется в отдельный SQL-файл, даже если в одном исходном файле определено несколько снимков.
-
Проверьте результаты, выполнив запрос к таблице, созданной dbt (
analytics.snapshots.orders_snapshot). После первого запуска вы должны увидеть результаты вашего запроса, а также поля метаданных снимка, описанные ниже. -
Запустите команду
dbt snapshotснова и проверьте результаты. Если какие-либо записи были обновлены, снимок должен это отразить. -
Выберите из
snapshotв последующих моделях, используя функциюref.models/changed_orders.sqlselect * from {{ ref('orders_snapshot') }} -
Снимки полезны только в том случае, если вы запускаете их часто — запланируйте регулярный запуск команды
dbt snapshot.
Лучшие практики конфигурации
(Версии dbt: v1.9 и новее)Как работают снимки
Когда вы запускаете команду dbt snapshot:
- При первом запуске: dbt создаст исходную таблицу снимка — она будет содержать результат вашего оператора
selectс дополнительными столбцами, включаяdbt_valid_fromиdbt_valid_to. У всех записей будетdbt_valid_to = nullили значение, указанное вdbt_valid_to_current(доступно в 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, включающая узел снапшота, выполняет его в обычном режиме — таблица снапшота не удаляется и не создаётся заново, поэтому существующая история снапшота сохраняется.
Примечание
- Эти имена колонок могут быть настроены в соответствии с вашими командными или организационными соглашениями, используя конфигурацию snapshot_meta_column_names.
- Используйте конфигурацию
dbt_valid_to_current, чтобы установить пользовательский индикатор для значенияdbt_valid_toв текущих записях снимков (например, будущая дата, такая как9999-12-31). По умолчанию это значениеNULL. Когда установлено, dbt будет использовать это указанное значение вместоNULLдляdbt_valid_toдля текущих записей в таблице снимков. - Используйте конфигурацию
hard_deletes, чтобы отслеживать жесткие удаления, добавляя новую запись, когда строка становится "удаленной" в источнике. Поддерживаемые опции:ignore,invalidateиnew_record.
Снимки могут быть использованы в последующих моделях так же, как и модели — с помощью функции ref.
Обнаружение изменений строк
Стратегии снимков определяют, как dbt узнает, изменилась ли строка. В dbt встроены две стратегии:
- Timestamp — Использует колонку
updated_at, чтобы определить, изменилась ли строка. - Check — Сравнивает список колонок между их текущими и историческими значениями, чтобы определить, изменилась ли строка.
Стратегия 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:
- 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 может быть настроена для отслеживания изменений всех колонок, указав check_cols = 'all'. Лучше явно перечислить колонки, которые вы хотите проверить. Рассмотрите возможность использования суррогатный ключ для конденсации многих колонок в одну.
Пример использования
(Версии dbt: v1.9 и новее)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:
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 автоматически возвращается к использованию текущего времени для отслеживания изменений. - Используйте этот подход, если ваша колонка
updated_atне всегда надёжна для отслеживания обновлений записей, но вы всё равно хотите применять её — вместо времени выполнения снапшота — когда изменения строк всё же обнаружены.
Жёсткие удаления (opt-in)
(Версии dbt: v1.9 и новее)В dbt v1.9 и выше конфигурация hard_deletes заменяет конфигурацию invalidate_hard_deletes, чтобы дать вам больше контроля над тем, как обрабатывать удаленные строки из источника. Конфигурация hard_deletes не является отдельной стратегией, а дополнительной опцией, которую можно использовать с любой стратегией снимков.
Конфигурация hard_deletes имеет три опции/поля:
| Поле | Описание |
|---|---|
ignore (по умолчанию) | Нет действий для удаленных записей. |
invalidate | Ведет себя так же, как существующий invalidate_hard_deletes=true, где удаленные записи аннулируются, устанавливая dbt_valid_to. |
new_record | Отслеживает удаленные записи как новые строки, используя мета-поле dbt_is_deleted, когда записи удаляются. |
Пример использования
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):
- Имена этих столбцов можно настроить в соответствии с соглашениями вашей команды или организации с помощью параметра
snapshot_meta_column_names. - Используйте параметр
dbt_valid_to_current, чтобы задать собственное значениеdbt_valid_toдля текущих записей снимка (например, дату в будущем, такую как9999-12-31). По умолчанию это значение равноNULL. Если параметр задан, dbt будет использовать указанное значение вместоNULLдляdbt_valid_toв текущих записях таблицы снимка. - Используйте параметр
hard_deletesсо значениемhard_deletes='new_record', чтобы отслеживать удалённые записи, добавляя новые строки с полем метаданныхdbt_is_deleted.
| Field | Значение | Примечания | Пример |
|---|---|---|---|
dbt_valid_from | Метка времени, с которой эта строка снимка стала действительной. | Используется для упорядочивания версий записи. Для конкретной строки это значение часто совпадает с dbt_updated_at, но эти поля имеют разный смысл. Примеры для каждой стратегии см. в разделе Метки времени стратегии и метаполей. | 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. | snapshot_meta_column_names: {dbt_scd_id: scd_id} |
dbt_updated_at | Метка времени изменения исходной записи на момент вставки этой строки снимка. | Используется внутри dbt. В разделе Метки времени стратегии и метаполей описано, каким значением заполняется этот столбец для каждой стратегии. | 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. Подробнее см. в этом примере.
При вставке значения dbt_valid_from и dbt_updated_at устанавливаются на основе одного и того же значения. Они обозначают начало периода действия и время зарегистрированного изменения соответственно.
Стратегия и временные метки метаполей
Временные метки, используемые для каждого столбца, зависят от выбранной стратегии:
-
Для стратегии
timestampнастроенная колонкаupdated_atиспользуется для заполнения колонокdbt_valid_from,dbt_valid_toиdbt_updated_at. -
Для стратегии
checkтекущая временная метка используется для заполнения каждого столбца. Если настроено, стратегияcheckвместо этого использует столбецupdated_at, как и стратегия временных меток.