Устаревшая конфигурация snapshot legacy
Используйте устаревшие SQL‑конфигурации снапшотов на основе Jinja‑блоков в любой версии dbt. В dbt v1.9 были представлены YAML‑конфигурации, которые обеспечивают лучшую читаемость и учитывают окружение.
В некоторых ситуациях вам может понадобиться использовать устаревший синтаксис для snapshots в любой версии или ветке релизов dbt. На этой странице описано, как при необходимости использовать устаревшие SQL‑конфигурации.
В dbt v1.9 этот синтаксис был заменён на конфигурацию на основе YAML в канале релизов v1 Latest dbt. Преимущества конфигураций на основе YAML заключаются в том, что снимки учитывают окружение, поэтому вам не нужно указывать schema или database, а синтаксис стал более лаконичным.
Для новых снапшотов мы рекомендуем использовать актуальные YAML‑конфигурации. Если вы хотите перейти на YAML‑конфигурацию для существующих снапшотов, вы можете выполнить миграцию.
Когда стоит использовать SQL‑синтаксис, а когда — YAML‑синтаксис?
-
SQL‑синтаксис:
- Определяется в файлах
.sqlвнутри snapshot Jinja‑блока, обычно расположенных в директорииsnapshots. Доступен во всех версиях. - Подходит для существующих снапшотов, которые уже используют этот синтаксис.
- Подходит для выполнения очень лёгких трансформаций (однако для лучшей поддерживаемости рекомендуется выносить трансформации в отдельную ephemeral‑модель).
- Определяется в файлах
-
Синтаксис на основе YAML:
- Определяется в файле
whatever_name.ymlв каталогеsnapshotsилиmodelsпо вашему выбору. Доступен в канале выпусков v1 Latest dbt и в dbt v1.9 и более поздних версиях. - Идеально подходит для новых снимков или существующих снимков, которые необходимо мигрировать.
- Определяйте преобразования отдельно от файла снимка: создайте эфемерную модель и укажите ссылку на неё в снимке с помощью поля
relation.
- Определяется в файле
Конфигурации снапшотов
Хотя вы можете использовать более производительную YAML‑конфигурацию, в некоторых случаях вам всё же может подойти устаревшая конфигурация для определения снапшотов.
Снапшоты можно настраивать двумя основными способами:
- с помощью специфичных для снапшотов конфигураций
- либо с помощью общих конфигураций
Эти конфигурации позволяют управлять тем, как dbt обнаруживает изменения в данных и где хранятся снапшоты. Оба типа конфигураций могут сосуществовать в одном проекте и даже в одном config‑блоке (либо задаваться через файл dbt_project.yml или properties.yaml).
Одной из самых важных настроек является выбор стратегии, которая определяет, каким образом dbt обнаруживает изменённые строки.
Специфичные для снапшотов конфигурации
Специфичные для снапшотов конфигурации применяются только к одному типу ресурсов dbt, а не к нескольким сразу. Эти настройки можно определить непосредственно в файле ресурса с помощью макроса {{ config() }} (а также в файле проекта dbt_project.yml или в property‑файле, например models/properties.yml для моделей — аналогично и для других ресурсов).
{ % 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‑блока.
Стратегии снапшотов
«Стратегии» снапшотов определяют, каким образом dbt понимает, что строка изменилась. В dbt встроены две стратегии, для которых требуется параметр strategy:
- Timestamp — использует колонку
updated_at, чтобы определить, изменилась ли строка. - Check — сравнивает список колонок между текущими и историческими значениями, чтобы определить изменения. Использует параметр
check_cols.
- Timestamp
- Check
Стратегия timestamp использует поле updated_at для определения изменений строки. Если значение updated_at для строки новее, чем время последнего запуска снапшота, dbt помечает старую запись как неактуальную и сохраняет новую. Если временные метки не изменились, dbt не предпринимает никаких действий.
Пример
{% 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 полезна для таблиц, в которых нет надёжной колонки updated_at. Она требует параметр check_cols, который представляет собой список колонок из результата запроса снапшота, по которым проверяются изменения. В качестве альтернативы можно указать значение all, чтобы использовать все колонки (однако это может быть менее производительно).
Пример
{% snapshot orders_snapshot_check %}
{{
config(
strategy='check',
unique_key='id',
check_cols=['status', 'is_cancelled'],
)
}}
select * from {{ source('jaffle_shop', 'orders') }}
{% endsnapshot %}
Примеры
Справочник конфигураций
Настройте снапшот, чтобы указать dbt, как определять изменения записей. Снапшоты — это select‑запросы, определённые внутри snapshot‑блока в .sql‑файле (обычно в директории snapshots или любой другой).
В таблице ниже перечислены конфигурации, доступные для снапшотов:
(Версии dbt: v1.9 и новее)| Config | Описание | Обязательно? | Пример |
|---|---|---|---|
| database | Указать пользовательскую базу данных для снапшота | Нет | analytics |
| schema | Указать пользовательскую схему для снапшота | Нет | snapshots |
| strategy | Стратегия снапшота: timestamp или check | Да | timestamp |
| unique_key | Колонка или выражение первичный ключ, идентифицирующее запись | Да | id |
| check_cols | Колонки для проверки при использовании стратегии check | Только при стратегии check | ["status"] |
| updated_at | Колонка с временной меткой при использовании стратегии timestamp | Только при стратегии timestamp | updated_at |
| invalidate_hard_deletes | Находить физически удалённые записи в источнике и устанавливать dbt_valid_to в текущее время, если запись больше не существует | Нет | True |
- Также поддерживается ряд других конфигураций (например,
tagsиpost-hook) — полный список смотрите здесь. - Снапшоты можно настраивать как через файл
dbt_project.yml, так и черезconfig‑блок — подробнее см. документацию по конфигурации. - Примечание: пользователи BigQuery могут использовать
target_projectиtarget_datasetкак алиасы дляtarget_databaseиtarget_schemaсоответственно. - До версии v1.9 параметры
target_schema(обязательный) иtarget_database(необязательный) задавали фиксированную схему или базу данных для снапшотов, что затрудняло разделение dev‑ и prod‑окружений. Начиная с v1.9target_schemaстал необязательным, что позволило использовать снапшоты с учётом окружения. По умолчанию снапшоты теперь используютgenerate_schema_nameилиgenerate_database_name, однако разработчики по‑прежнему могут указать пользовательское расположение с помощью schema и database, аналогично другим типам ресурсов.
Добавление снапшота в проект
Чтобы добавить снапшот в проект:
- Создайте файл в директории
snapshotsс расширением.sql. Например,snapshots/orders.sql. - Используйте блок
snapshot, чтобы определить начало и конец снапшота:
{% snapshot orders_snapshot %}
{% endsnapshot %}
- Напишите
select‑запрос внутри snapshot‑блока. Этот запрос определяет результат, который вы хотите отслеживать во времени. Здесь можно использоватьsourcesилиrefs.
{% snapshot orders_snapshot %}
select * from {{ source('jaffle_shop', 'orders') }}
{% endsnapshot %}
-
Проверьте, содержит ли результат запроса надёжную колонку с временной меткой, указывающую, когда запись была обновлена в последний раз. В нашем примере колонка
updated_atнадёжно отражает изменения, поэтому можно использовать стратегиюtimestamp. Если такой колонки нет, потребуется использовать стратегиюcheck. -
Добавьте конфигурации к снапшоту с помощью
config‑блока. Также вы можете настроить снапшот через файлdbt_project.yml.
{% 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 %}
- Запустите команду
dbt snapshot. В нашем примере будет создана новая таблицаanalytics.snapshots.orders_snapshot. Изменяя конфигурацииtarget_database,target_schemaи имя снапшота (заданное в{% snapshot .. %}), вы управляете тем, как 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
- Проверьте результаты, выполнив
selectиз таблицы, созданной dbt. После первого запуска вы увидите результат запроса, а также метаполя снапшота. - Запустите
dbt snapshotещё раз и снова проверьте результаты. Если какие‑либо записи были обновлены, снапшот должен это отразить. - Используйте снапшот в downstream‑моделях с помощью функции
ref.
select * from {{ ref('orders_snapshot') }}
- Снапшоты полезны только при регулярном запуске — настройте выполнение команды
snapshotпо расписанию.
Примеры
В этом разделе приведены примеры применения конфигураций к снапшотам с использованием устаревшего метода.