Перейти к основному содержимому

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

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

В некоторых ситуациях вам может понадобиться использовать устаревший синтаксис для snapshots в любой версии или ветке релизов dbt. На этой странице описано, как при необходимости использовать устаревшие SQL‑конфигурации.

В dbt v1.9 этот синтаксис был заменён на YAML‑конфигурацию в ветке релизов dbt "Latest" (/docs/dbt-versions/cloud-release-tracks). Преимущество YAML‑конфигураций заключается в том, что снапшоты становятся чувствительными к окружению: вам не нужно указывать schema или database, а сам синтаксис становится более лаконичным.

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

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

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

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

  • YAML‑синтаксис:

    • Определяется в файлах whatever_name.yml или в директориях snapshots или models — на ваш выбор. Доступен в ветке релизов dbt "Latest" и в dbt v1.9 и выше.
    • Идеален для новых снапшотов или существующих снапшотов, которые нужно мигрировать.
    • Трансформации выносятся за пределы файла снапшота путём создания ephemeral‑модели и ссылки на неё в снапшоте с помощью поля relation.

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

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

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

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

Одной из самых важных настроек является выбор стратегии, которая определяет, каким образом dbt обнаруживает изменённые строки.

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

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

snapshots/orders_snapshot.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
{{ 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 — использует колонку updated_at, чтобы определить, изменилась ли строка.
  • Check — сравнивает список колонок между текущими и историческими значениями, чтобы определить изменения. Использует параметр check_cols.

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

Пример​

snapshots/timestamp_example.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 %}

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

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

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

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

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

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

{% endsnapshot %}
  1. Напишите select‑запрос внутри snapshot‑блока. Этот запрос определяет результат, который вы хотите отслеживать во времени. Здесь можно использовать sources или refs.
snapshots/orders_snapshot.sql
{% snapshot orders_snapshot %}

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

{% endsnapshot %}

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

  2. Добавьте конфигурации к снапшоту с помощью config‑блока. Также вы можете настроить снапшот через файл dbt_project.yml.

  1. Запустите команду 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
  1. Проверьте результаты, выполнив select из таблицы, созданной dbt. После первого запуска вы увидите результат запроса, а также метаполя снапшота.
  2. Запустите dbt snapshot ещё раз и снова проверьте результаты. Если какие‑либо записи были обновлены, снапшот должен это отразить.
  3. Используйте снапшот в downstream‑моделях с помощью функции ref.
models/changed_orders.sql
select * from {{ ref('orders_snapshot') }}
  1. Снапшоты полезны только при регулярном запуске — настройте выполнение команды snapshot по расписанию.

Примеры​

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

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

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

snapshots/postgres_app/orders_snapshot.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
{{ config(
  strategy="timestamp",
  updated_at="column_name"
) }}

Примеры​

  • Использование колонки updated_at:​

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

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

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

 Использование параметра unique_key

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

snapshots/orders.sql
{{ config(
  unique_key="column_name"
) }}

Примеры​

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

    snapshots/orders.sql
    {{
        config(
          unique_key="id"
        )
    }}

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

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

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

    snapshots/transaction_items_snapshot.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
    {% snapshot transaction_items_snapshot %}

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

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

    {% endsnapshot %}

Нашли ошибку?

0
Loading