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

freshness

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

(Версии dbt: v2.0 и новее)

Выполните dbt freshness, чтобы проверить все источники и модели, для которых настроена проверка свежести данных.

примечание

dbt source freshness — это устаревшая команда, которая проверяет актуальность данных только в источниках. Она по-прежнему поддерживается для обратной совместимости и продолжает создавать sources.json, но в дальнейшем мы рекомендуем использовать dbt freshness.

Конфигурация​

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

ПолеОписание
warn_afterМаксимально допустимый возраст самых свежих данных, при превышении которого проверка свежести выдает предупреждение. Требует указания и count, и period.
error_afterМаксимально допустимый возраст самых свежих данных, при превышении которого проверка свежести выдает ошибку. Формат такой же, как у warn_after.
loaded_at_fieldСтолбец, к которому dbt обращается, чтобы определить временную метку последней загрузки. Обязателен, если метаданные адаптера недоступны.
loaded_at_querySQL-выражение, возвращающее временную метку последней загрузки. Альтернатива loaded_at_field. Одновременное указание loaded_at_query и loaded_at_field для одного ресурса вызывает ошибку разбора. Доступно в dbt v1.10 и более поздних версиях.
filterДобавляет условие WHERE в запрос проверки свежести, чтобы ограничить объем сканируемых данных. Полезно для секционированных таблиц BigQuery или больших таблиц в Snowflake, Databricks или Spark. Не влияет на другие способы использования источника или модели. Не применяется к loaded_at_query.

Можно указать один из параметров warn_after и error_after или оба. Если ни один из них не задан, dbt не будет проверять свежесть данных этого ресурса. Для каждого из параметров warn_after и error_after необходимо указать и count, и period; указание только одного из них приводит к предупреждению при разборе, но вызывает ошибку при выполнении dbt freshness.

Свежесть данных источников​

dbt_project.yml
sources:
  <resource-path>:
    +freshness:
warn_after:
        count: <positive_integer>
        period: minute | hour | day

Настройки актуальности применяются по иерархии:

  • Параметры freshness и loaded_at_field источника применяются ко всем его таблицам.
  • Параметры freshness и loaded_at_field на уровне таблицы источника переопределяют настройки источника.

Чтобы исключить источник из расчёта актуальности, явно укажите freshness: null.

Если у источника есть блок freshness:, dbt пытается рассчитать его актуальность:

  • При заданном loaded_at_field dbt выполняет запрос select.
  • Если loaded_at_field не задан, dbt по возможности использует таблицы метаданных хранилища.
(Версии dbt: v1.12 и новее)
Шаблоны в именах таблиц

В BigQuery проверка актуальности по метаданным ненадёжна для источников с подстановочными символами в имени таблицы, например events_*.

Чтобы избежать неверных результатов, включите флаг bigquery_reject_wildcard_metadata_source_freshness в dbt_project.yml. Тогда dbt выдаст ошибку, если проверка по метаданным используется с подстановочным символом в имени таблицы.

Чтобы проверять актуальность таблиц с такими именами, настройте loaded_at_field. Тогда проверка будет выполняться запросом.

Примеры​

Использование loaded_at_field​

sources:
  - name: jaffle_shop
    config:
      # Cast a date field to timestamp
      loaded_at_field: "completed_date::timestamp"

    tables:
      - name: orders
        config:
          # Cast a non-UTC timestamp to UTC
          loaded_at_field: "convert_timezone('Australia/Sydney', 'UTC', created_at_local)"
          freshness:
            warn_after: {count: 12, period: hour}

Использование loaded_at_query​

(Версии dbt: v1.10 и новее) 
sources:
  - name: jaffle_shop
    tables:
      - name: orders
        loaded_at_query: |
          select max(_sdc_batched_at) from (
            select * from {{ this }}
            where _sdc_batched_at > dateadd(day, -7, current_date)
            qualify count(*) over (partition by _sdc_batched_at::date) > 2000
          )
        config:
          freshness:
            warn_after: {count: 12, period: hour}

Полный пример​

models/<filename>.yml
sources:
  - name: jaffle_shop
    database: raw
    config:
      freshness: # default freshness for all tables
        warn_after: {count: 12, period: hour}
        error_after: {count: 24, period: hour}
      loaded_at_field: _etl_loaded_at

    tables:
      - name: customers # uses the freshness defined above

      - name: orders
        config:
          freshness: # more strict for orders
            warn_after: {count: 6, period: hour}
            error_after: {count: 12, period: hour}
            filter: datediff('day', _etl_loaded_at, current_timestamp) < 2

      - name: product_skus
        config:
          freshness: null # do not check freshness for this table
(Версии dbt: v2.0 и новее)

Команда dbt freshness выполнит для таблицы orders следующий запрос:

select
  max(_etl_loaded_at) as max_loaded_at,
  convert_timezone('UTC', current_timestamp()) as snapshotted_at
from raw.jaffle_shop.orders
where datediff('day', _etl_loaded_at, current_timestamp) < 2
(Версии dbt: v2.0 и новее)

Актуальность модели​

Настройка модели freshness позволяет:

  • Задать пороги актуальности: укажите warn_after и error_after, чтобы задать допустимый возраст данных. Затем запустите dbt freshness, чтобы проверить модели и получить предупреждение или ошибку при превышении порогов.
  • Запланировать сборки (build_after): задайте, как часто перестраивать модель после появления новых данных выше по графу. Доступно только на тарифах Enterprise платформы dbt. Параметр build_after относится к прежней оркестрации с учётом состояния, которую заменил dbt State.
dbt_project.yml
models:
  <resource-path>:
    +loaded_at_field: <column_name>    # or loaded_at_query
    +loaded_at_query: <sql_expression> # alternative to loaded_at_field
    +freshness:
      warn_after: {count: <positive_integer>, period: minute | hour | day}
      error_after: {count: <positive_integer>, period: minute | hour | day}

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

Материализацияloaded_at_field / loaded_at_queryПоведение
table, incremental, materialized_view, dynamic_tableНеобязательноЕсли не задано, dbt использует метаданные адаптера (например, время последнего изменения таблицы).
view, externalОбязательноПредставления не предоставляют метаданные на уровне строк. Задайте loaded_at_field или loaded_at_query для оценки свежести данных. Пустая строка (loaded_at_field: "") считается отсутствующим значением и вызывает ошибку разбора.
ephemeralНе поддерживаетсяНичего не материализуется, поэтому оценить свежесть данных невозможно. Вызывает ошибку разбора.

Неполное правило актуальности, например warn_after с count без period, вызывает предупреждение при разборе для всех материализаций. Команды dbt run и dbt build выдают предупреждение, но выполняются. Только dbt freshness считает это ошибкой. Для моделей view и external нужен loaded_at_field или loaded_at_query. Если не указан ни один из них, разбор завершается ошибкой для dbt run, dbt build и dbt freshness независимо от полноты правила.

Проверка свежести данных между проектами​

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

Например, project_a содержит публичную модель orders с настроенной проверкой свежести данных:

# project_a: models/orders.yml
models:
  - name: orders
    access: public
    config:
      loaded_at_field: updated_at
      freshness:
        warn_after: {count: 24, period: hour}
        error_after: {count: 48, period: hour}

project_b зависит от orders. Чтобы проверить свежесть данных в orders, выполните dbt freshness из project_b — повторно запускать project_a не нужно:

# run from project_b
dbt freshness --select project_a.orders

Примеры​

Использование только warn_after​

models:
  - name: stg_orders
    config:
      materialized: table
      freshness:
        warn_after: {count: 24, period: hour}

Использование loaded_at_query​

models:
  - name: stg_events
    config:
      materialized: table
      freshness:
        warn_after: {count: 6, period: hour}
        error_after: {count: 12, period: hour}
      loaded_at_query: "select max(_loaded_at) from {{ this }} where _batch_complete = true"

Планирование сборок​

Оркестрация с учетом состояния теперь называется dbt State

dbt State работает со всеми движками и средами: dbt v1, dbt platform и dbt v2

Если вы использовали оркестрацию с учетом состояния до 1 июня 2026 года, вы можете продолжать ее использовать. Когда вы начнете бесплатный пробный период dbt State, он будет продлен сверх стандартных 30 дней. Если продление не применено к вашей учетной записи, обратитесь к команде по работе с вашим аккаунтом. Чтобы начать, ознакомьтесь с разделом Переход с оркестрации с учетом состояния.

dbt_project.yml
models:
  <resource-path>:
    +freshness:
      build_after: # Available only on dbt platform Enterprise tiers
        count: <positive_integer>
        period: minute | hour | day
        updates_on: any | all # optional, default is `any`

Параметр конфигурации build_after применяется к оркестрации с учётом состояния (SAO), которая теперь считается устаревшей. build_after выполняет повторную сборку моделей только при наличии новых данных в источниках или вышестоящих моделях. Это полезно для моделей, которые зависят от других моделей, но требуют лишь периодического обновления.

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

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

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

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

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

Если вы используете dbt State, настройки build_after перенесены из блока freshness в блок state:

Оркестрация с учётом состоянияdbt State
freshness.build_after.count + freshness.build_after.periodstate.lag_tolerance
freshness.build_after.updates_onstate.require_fresh_data_from

Дополнительную информацию см. в разделе Миграция с оркестрации с учётом состояния.

Значение по умолчанию​

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

build_after:
  count: 0
  period: minute
  updates_on: any

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

Примеры​

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

Реже​

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

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 часа назад, сборка не произойдет.

Более частые запуски​

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

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 перестраивает модель. Если ни у одной из моделей нет новых данных, ничего построено не будет.

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

Настраиваемая периодичность​

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

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

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

0
Loading