freshness Private previewEnterpriseEnterprise +

💡Did you know...

Available from dbt v1.10 or with the dbt "Latest" release track.

YAML-файл проекта

dbt_project.yml

models:
  <resource-path>:
    +freshness:
      build_after:  # собирать эту модель не чаще, чем раз в X единиц времени, при условии наличия новых данных. Доступно только на Enterprise-тарифах dbt platform.
        count: <positive_integer>
        period: minute | hour | day
        updates_on: any | all # необязательная настройка

Properties YAML file

models/<filename>.yml

models:
  - name: stg_orders
    config:
      freshness:
        build_after:  # собирать эту модель не чаще, чем раз в X единиц времени, при условии наличия новых данных. Доступно только на Enterprise-тарифах dbt platform.
          count: <positive_integer>
          period: minute | hour | day
          updates_on: any | all # необязательная настройка

SQL file config

models/<filename>.sql

{{
    config(
      freshness={
        "build_after": {     # собирать эту модель не чаще, чем раз в X единиц времени, при условии наличия новых данных
        "count": <positive_integer>,
        "period": "minute" | "hour" | "day",
        "updates_on": "any" | "all" # необязательная настройка
        } 
      }
    )
}}

Определение

Конфигурация freshness для моделей обеспечивает state-aware orchestration, позволяя пересобирать модели только при появлении новых данных в источниках или апстрим-моделях. Это помогает сократить количество лишних сборок и оптимизировать затраты. Такой подход особенно полезен для моделей, которые зависят от других моделей, но требуют обновления лишь периодически.

freshness работает совместно с оркестрацией джобов dbt и помогает определить, когда модели действительно нужно пересобирать в рамках запланированного запуска. При каждом запуске джоба dbt гарантирует, что модели выполняются только при необходимости, что позволяет избежать избыточных сборок. Для этого dbt:

• Проверяет, появились ли новые данные для модели
• Убеждается, что с момента последней сборки прошло достаточно времени, на основе параметров count и period

Для источников и апстрим-моделей (в случае mesh) dbt определяет «новизну» данных на основе пользовательских вычислений freshness (если они настроены). Если freshness источника превышает заданный порог warning или error, dbt выдает предупреждение или ошибку во время сборки.

Конфигурация состоит из следующих частей:

Конфигурация	Описание
build_after	Доступно только на Enterprise-тарифах dbt platform. Настройка, вложенная в freshness. Используется для определения того, должна ли модель пересобираться при наличии новых данных, в зависимости от того, прошло ли указанное количество времени (count и period) с момента последней сборки модели. Хотя dbt проверяет наличие новых данных при каждом запуске джоба, build_after гарантирует, что модель будет пересобрана только если прошло достаточно времени и при этом появились новые данные.
count and period	Задают, как часто dbt должен проверять наличие новых данных. Например, count: 4, period: hour означает, что dbt будет выполнять проверку каждые 4 часа. Обратите внимание: для каждой конфигурации freshness необходимо либо задать значения и для count, и для period, либо указать freshness: null.
updates_on	Необязательный параметр. Определяет, при каких изменениях апстрим-данных должен запускаться билд. Возможные значения: - any: модель будет собираться, как только любой из прямых апстрим-узлов получит новые данные с момента последней сборки. Быстрее, но может увеличить затраты. - all: модель будет собираться только тогда, когда все прямые апстрим-узлы получат новые данные с момента последней сборки. Меньше затрат, но больше требований.

Loading table...

По умолчанию

Значение по умолчанию для ключа build_after:

build_after:
  count: 0
  period: minute
  updates_on: any

Это означает, что по умолчанию модель будет собираться при каждом запуске запланированного джоба при наличии любого объема новых данных.

Примеры

Ниже приведены примеры настройки моделей для более редкого, более частого или пользовательского расписания сборки.

Вы можете настроить freshness в YAML так, чтобы пропускать модели в процессе сборки, если только нет новых данных и не прошел указанный интервал времени.

Более редкая сборка

Вы можете настроить модель на более редкую сборку (что снижает затраты), указав, что она должна собираться не чаще, чем раз в X единиц времени, при условии наличия новых данных.

Добавьте конфигурацию freshness в модель с параметрами count: 4 и period: hour:

models:
  - name: stg_wizards
    config:
      freshness:
        build_after: 
          count: 4
          period: hour
          updates_on: all
  - name: stg_worlds
    config:
      freshness:
        build_after: 
          count: 4
          period: hour
          updates_on: all  

Когда срабатывает state-aware orchestration job, dbt проверяет два условия:

• Появились ли новые исходные данные во всех апстрим-моделях
• Были ли модели stg_wizards и stg_worlds собраны более 4 часов назад

Когда выполняются оба условия, dbt собирает модель. В этом случае используется настройка updates_on: all. Если источник raw.wizards получил новые данные, но stg_wizards и stg_worlds были собраны 3 часа назад, сборка не произойдет.

Если бы в предыдущем примере было указано updates_on: any, то при появлении новых данных в источнике raw.wizards dbt собрал бы модель, если только она не была собрана в течение последних 4 часов.

Более частая сборка

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

Добавьте конфигурацию build_after в freshness с параметрами count: 1 и period: hour:

models:
  - name: stg_wizards
    config: 
      freshness:
        build_after: 
          count: 1
          period: hour
          updates_on: any
  - name: stg_worlds
    config:
      freshness:
        build_after: 
          count: 1
          period: hour
          updates_on: any  

При запуске state-aware orchestration job dbt проверяет:

• Есть ли новые исходные данные хотя бы в одной апстрим-модели
• Не была ли stg_wizards или stg_worlds собрана в течение последнего часа

Если выполняются оба условия, dbt пересобирает модель. Это также означает, что если у любой модели (stg_wizards или stg_worlds) появились новые данные, dbt выполнит сборку. Если ни у одной модели нет новых данных, сборка не произойдет.

В этом примере, поскольку указано updates_on: any, даже если новые данные появились только в источнике raw.wizards, и при этом только stg_wizards была собрана в течение последнего часа (а stg_worlds — нет), dbt все равно выполнит сборку, потому что требуется лишь одно обновление источника и одна подходящая (устаревшая) модель.

Произвольная частота сборки

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

Если вы хотите выполнять сборку каждый час только в будние дни (с понедельника по пятницу), можно использовать Jinja-выражения в YAML- и SQL-файлах, применяя Python-функции, такие как weekday(), где понедельник — 0, а воскресенье — 6. Например:

Project file

dbt_project.yml

+freshness:
  build_after:
    # если сегодня суббота или воскресенье, ждать минимум 48 часов перед следующей сборкой
    # в противном случае — ждать минимум 1 час
    count: "{{ 48 if modules.datetime.datetime.today().weekday() in (5, 6) else 1 }}"
    period: hour
    updates_on: any

SQL file config

models/<filename>.sql

{{
    config(
      freshness={
        "build_after": {
        "count": 48 if modules.datetime.datetime.today().weekday() in (5, 6) else 1,
        "period": "hour",
        "updates_on": "any"
        } 
      }
    )
}}

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

Создать GitHub Issue