О dbt State

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

С dbt State при каждом запуске dbt сначала сравнивает логику и данные каждого узла с предыдущими построениями в разных средах — независимо от того, выполняется ли оркестрация в dbt platform, через ваш собственный оркестратор или в среде разработки. Если логика совпадает, а данные всё ещё актуальны, dbt повторно использует существующий объект. Вместо нового построения dbt либо клонирует существующий узел из другого расположения, либо пропускает выполнение уже существующей модели. Кроме того, dbt автоматически использует состояние производственной среды для разрешения ссылок, не требуя вручную задавать флаги --defer или --state.

dbt State может повторно использовать все типы узлов, которые создают объекты отношений в базе данных (например, SQL-модели, снимки и seeds), а также тесты данных. Обратите внимание, что следующие модели не подходят для повторного использования:

• Python-модели: dbt State строит Python-модели при каждом запуске, даже если их код и данные вышестоящих узлов не изменились.
• Модели с пользовательскими материализациями: dbt State строит эти модели при каждом запуске, поскольку пользовательские материализации могут иметь побочные эффекты (например, изменять свойства таблиц или записывать данные в другие схемы), и dbt State не может достоверно определить, даст ли пропуск выполнения тот же результат.

dbt State работает с dbt (v1 и v2) и dbt platform во всех средах и с любыми оркестраторами, обеспечивая гибкий подход независимо от способа запуска dbt. Для работы требуется аутентификация через учётную запись dbt platform. Сведения о ценах см. в разделе Использование и стоимость dbt State.

Преимущества

dbt State снижает затраты на вычисления в хранилище данных и упрощает разработку, оркестрацию и выполнение dbt:

• Более актуальные данные при меньших затратах: узлы перестраиваются только тогда, когда результат будет отличаться (при появлении новых данных или изменениях кода), что сокращает вычисления в хранилище и поддерживает актуальность данных в производственной среде.
• Более быстрая и простая разработка: без dbt State при разработке в новой схеме необходимо строить вышестоящие зависимости, поддерживать копии для разработки или настраивать --defer с манифестом состояния. С dbt State ничего из этого не требуется: dbt находит наиболее актуальное доступное состояние во всех средах, клонирует актуальные вышестоящие объекты данных и перестраивает только то, что изменилось.
• Более простая оркестрация: решения об оркестрации обычно принимаются на уровне заданий — какие узлы входят в задание и как часто оно должно выполняться. dbt State добавляет принятие решений на уровне узлов в рамках каждого запуска: вместо перестроения всех выбранных узлов dbt оценивает каждый из них отдельно и решает, следует ли его перестроить, клонировать или пропустить, исходя из его логики и актуальности данных. В отличие от стандартного механизма отложенного разрешения ссылок, который всегда строит выбранные узлы и использует внешнее состояние только для ссылок на невыбранные вышестоящие узлы, dbt State также может пропускать или клонировать выбранные узлы.
• Порог актуальности на уровне модели: настройка lag_tolerance определяет, сколько времени dbt State ожидает перед перестроением узла после изменения данных в вышестоящих узлах. Узел перестраивается только в том случае, если с его последнего построения прошло больше времени, чем допускает заданный интервал, и данные вышестоящих узлов изменились. Это позволяет нижестоящим моделям не зависеть от частых изменений вышестоящих узлов и предотвращает дорогостоящие перестроения на неизменившихся данных, когда вышестоящая зависимость не выполняет соглашение об уровне обслуживания (SLA) в отношении актуальности.

Как работает dbt State

При выполнении команды, например dbt build --select +my_model, dbt State оценивает каждый выбранный узел и применяет наиболее эффективный из доступных подходов:

• Повторное использование узла из той же схемы (пропуск) — dbt проверяет, существует ли объект в целевой схеме, не изменилась ли его логика и не наступило ли время перестроения согласно его настройке lag_tolerance (либо с последнего построения ещё не истёк допустимый интервал, либо данные вышестоящих узлов не изменились). Если все условия выполнены, dbt полностью пропускает узел, как если бы он не был выбран. Для тестов данных, если проверяемые узлы не изменились с последнего запуска, повторно используется предыдущий результат теста без повторного выполнения тестового запроса.

  Если логика представления не изменилась, dbt State повторно использует его, даже если в вышестоящих узлах появились новые данные. Поскольку представления не хранят данные, новые данные вышестоящих узлов автоматически отражаются при запросе к представлению, даже без перестроения. Обратите внимание, что представления, использующие select * для вышестоящего узла, могут вести себя иначе — подробнее см. в разделе Представления с select *.

• Повторное использование узла из другой схемы (клонирование) — dbt State ищет во всех средах и заданиях подходящий объект с идентичной логикой и актуальными данными. В поиск включаются и схемы, в которых модель была построена до её первого запуска в производственной среде. Если найдено несколько кандидатов, dbt State клонирует объект с наиболее актуальными данными независимо от того, из какой среды он получен. Например, если в схеме CI данные актуальнее, чем в производственной среде, а логика идентична, dbt State клонирует объект оттуда. Узел помечается как Reused, а затраты на вычисления составляют лишь малую долю затрат на построение.

  Если вы хотите запретить клонирование в определённую целевую конфигурацию (например, в средах с нормативными ограничениями), задайте для неё allow_clones: false в profiles.yml или в качестве расширенного атрибута в dbt platform.

• Обычное построение — если повторное использование невозможно, dbt строит узел обычным способом, автоматически используя внешнее состояние для разрешения ссылок на невыбранные вышестоящие узлы.

В начале каждого запуска dbt State в фоновом режиме получает метаданные таблиц (например, временные метки последнего изменения). Любой узел, для которого уже определено действие — пропуск, клонирование или выполнение, — сразу переходит к нему; узлы с ещё не определённым действием ожидают завершения получения метаданных.

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

Чтобы после запуска узнать, какое решение dbt State принял для каждого узла и почему, выполните команду (Версии dbt: v2.0 и новее) dbt state explain. Если вы используете dbt platform, та же информация доступна без выполнения команды — перейдите на вкладку Explain на странице сведений о запуске задания, чтобы увидеть полный разбор решений для каждого узла.

Полный список доступных настроек см. в разделе Настройки dbt State.

 Как dbt State решает, нужно ли перестроить, клонировать или повторно использовать узел

Следующее дерево решений показывает, как dbt State выбирает наиболее эффективное допустимое действие для каждого узла.

Дерево решений dbt State для перестроения, клонирования и повторного использования

Основная идея заключается в том, что dbt State пропускает работу только тогда, когда может доказать достаточную эквивалентность существующего объекта для текущего запуска. Если SQL-логика, значимые настройки, схема или актуальность вышестоящих данных указывают на то, что результат может отличаться, dbt вместо этого выполняет перестроение.

Использование dbt State с селекторами state:* Бета-версия

В самостоятельно управляемых развёртываниях dbt State также можно использовать с селекторами state:*. Вместо сравнения с одним файлом manifest.json эти селекторы используют dbt State как источник для сравнения, причём состояние отслеживается для каждого узла отдельно. Подробнее см. в разделе Селекторы state:* на основе dbt State.

Регистрация для работы с dbt State

Для аутентификации dbt State требуется учётная запись dbt platform, даже если вы запускаете dbt локально или в неинтерактивной среде.

• Существующие пользователи dbt platform: ваши учётные данные dbt State совпадают с учётными данными платформы, а dbt State имеет доступ к вашим средам и заданиям на платформе.
• Новые пользователи dbt platform: создайте учётную запись на странице регистрации dbt platform. Пользователи dbt v2 и v1 могут начать процесс создания учётной записи из CLI, выполнив dbt login (v1.13/v2) или dbt run/dbt build (dbt v1.7–1.12). Эта команда откроет страницу регистрации, где можно создать бесплатную учётную запись.

Инструкции по настройке см. в разделе Настройка dbt State.

Приложение dbt State больше не поддерживается

Отдельное приложение dbt State (app.state.dbt.com) больше не принимает новых пользователей. Если у вас уже есть учетная запись в приложении dbt State, создайте бесплатную учетную запись dbt platform, чтобы продолжить использовать dbt State — ваш бесплатный пробный период будет продлен при создании учетной записи.

Часто задаваемые вопросы

Что произошло с оркестрацией с учетом состояния?

1 июня 2026 года dbt Labs и Fivetran представили dbt State — новую улучшенную версию оркестрации с учетом состояния. Одна из ключевых возможностей — lag_tolerance: этот параметр определяет, сколько времени должно пройти с момента последнего изменения данных в вышестоящих узлах, прежде чем узел можно будет пересобрать.

dbt State расширяет возможности оркестрации с учётом состояния в нескольких ключевых аспектах:

• Работает везде — dbt State работает с dbt v1, dbt v2 и dbt platform, а также с внешними оркестраторами как в средах разработки, так и в средах развёртывания.
• Более точное отслеживание актуальности данных — dbt State отслеживает актуальность данных во всём DAG и автоматически передаёт сведения о ней через модели, материализованные как представления. В отличие от параметра build_after в оркестрации с учётом состояния, который выполняет сравнение относительно последнего успешного выполнения модели, параметр lag_tolerance в dbt State выполняет сравнение относительно актуальности исходных данных.
• Расширенное обнаружение изменений — dbt State может обнаруживать и игнорировать изменения файлов, которые не влияют на фактическую логику преобразований, например добавление комментария или удаление лишних пробелов.

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

Чтобы начать работу, обратитесь к руководству Переход с оркестрации с учетом состояния.

Чем dbt State отличается от использования state:modified?

Сам по себе state:modified требует ручного управления файлом manifest.json, что неудобно и чревато ошибками. dbt State полностью управляется автоматически, практически не требует настройки и не меняет рабочие процессы. В развертываниях с самостоятельным управлением dbt State также может напрямую обеспечивать работу селекторов state:* — см. последний пункт ниже.

state:modified проверяет только то, изменился ли файл. dbt State понимает семантику SQL, поэтому несущественные изменения, такие как пробелы или псевдонимы таблиц, не учитываются — это позволяет dbt State точнее определять, что действительно нужно пересоздать.

state:modified не учитывает изменения данных в вышестоящих источниках. dbt State проверяет все источники на наличие новых данных или изменений схемы. Это позволяет dbt State пропускать выполнение моделей, если результат будет таким же, как прежде. Например, если дважды выполнить dbt run с state:modified, все измененные модели будут выполнены оба раза. dbt State повторно выполнит модели во второй раз только в том случае, если вышестоящие источники изменились.

dbt State также может автоматически перенаправлять ссылки ref на объекты из другого окружения и автоматически клонировать таблицы, когда результат клонирования будет таким же, как при полноценном выполнении модели.

У state:modified есть ограничение для seed-файлов размером более 1 МБ, а у dbt State такого ограничения нет.

Когда dbt State включен в развертывании с самостоятельным управлением, все селекторы state:* могут использовать dbt State как источник состояния для сравнения. Это обеспечивает детализацию на уровне отдельных узлов — каждый узел сравнивается с состоянием после его собственного последнего выполнения в окружении defer_to_target, а не все узлы сравниваются с одним файлом manifest.json из последнего задания. Это применяется автоматически, если манифест не был явно указан с помощью --state. Подробнее см. в разделе Селекторы state:* на базе dbt State.

Поддерживает ли dbt State инкрементальные модели?

dbt State работает с инкрементальными моделями. Когда вы изменяете инкрементальную модель и запускаете её в среде разработки, dbt State автоматически клонирует модель из производственной среды, если она там существует, а затем выполняет новую логику модели на основе этого клона.

Если вы хотите вернуться к стандартному поведению dbt и полностью обновить инкрементальную модель, передайте флаг --full-refresh.

Поддерживает ли dbt State модели Python?

dbt State строит модели Python, но не использует повторно результаты их выполнения. Он выполняет модели Python при каждом запуске, даже если их код и данные вышестоящих зависимостей не изменились.

Как хранятся данные в dbt State?

dbt State отправляет на серверы dbt Labs следующие метаданные:

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

Сами данные из вашего хранилища не передаются.

Сервис dbt State работает в единственном многопользовательском (MT) экземпляре, размещённом в США. Сервис никогда не подключается к вашему хранилищу данных. Сами данные из вашего хранилища не передаются. Единственное подключение — к вашему работающему процессу dbt (CLI или платформа) для обмена описанными выше метаданными. Подробную информацию о сроках хранения данных см. в политике конфиденциальности dbt Labs.

Откуда берутся метаданные о времени последнего обновления?

Временные метки последнего обновления поступают непосредственно из хранилища данных, например из таблиц INFORMATION_SCHEMA.

Как dbt State определяет, что модель изменилась?

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

По умолчанию dbt State сравнивает SQL-код, полученный после рендеринга, для обнаружения изменений кода. Любое изменение такого SQL-кода — в том числе вызванное недетерминированными макросами или переменными окружения — приводит к пересборке.

Вы можете включить compare_unrendered_code, чтобы дополнительно проверять шаблон Jinja (код до рендеринга). При включённой настройке пересборка происходит только тогда, когда изменились и шаблон, и SQL-код после рендеринга. Недетерминированные значения (например, {{ env_var('AIRFLOW_RUN_ID') }} или макрос, вызывающий uuid()) не приводят к пересборке, пока сам шаблон остаётся неизменным, что помогает избежать ненужных затрат на вычисления в хранилище данных.

Почему моя модель пересоздаётся, а не используется повторно?

dbt State решает, можно ли повторно использовать модель, разбирая SQL-код, полученный после рендеринга, в синтаксическое дерево и сравнивая хеш. Если хеш изменился (что указывает на изменение логики модели), dbt State пересоздаёт модель.

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

Следующие ситуации часто приводят к неожиданному пересозданию моделей:

• Представления с select *
• Недетерминированные шаблоны Jinja
• Модели с внешними источниками в BigQuery
• Модели с пользовательскими материализациями

Представления с select *

dbt State повторно использует модель, когда хеш её скомпилированного SQL-кода совпадает с сохранённым хешем. Если представление использует select * непосредственно для ref() или source(), dbt не может определить список столбцов на этапе разбора — с момента последнего запуска в вышестоящей модели или исходной таблице могли появиться или исчезнуть столбцы. Чтобы избежать риска, dbt State принудительно пересоздаёт модель.

Например, это представление будет пересоздано, даже если stg_orders не изменилась, поскольку на этапе разбора dbt не может определить, остались ли в stg_orders те же столбцы, что и раньше:

-- stg_orders_view.sql (materialized: view)
select * from {{ ref('stg_orders') }}

Сообщить об ошибке в коде

Однако если использовать select * для CTE, dbt может определить столбцы из определения CTE и безопасно использовать представление повторно:

with renamed as (
    select order_id, customer_id, order_total from {{ ref('stg_orders') }}
)

select * from renamed

Сообщить об ошибке в коде

Если в CTE явно указаны имена столбцов, запрос select *, читающий из этого CTE, не приведёт к принудительному пересозданию, даже если в предыдущем CTE использовался select * для ref() или source(). Модель с типичной структурой слоя staging будет использоваться повторно:

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

renamed as (
    select
        id as order_id,
        user_id as customer_id,
        amount as order_total
    from source
)

select * from renamed

Сообщить об ошибке в коде

подсказка

Чтобы избежать принудительного пересоздания, явно указывайте имена столбцов при выборке непосредственно из ref() или source(). Также можно исключить представления из выполнения с помощью --exclude config.materialized:view.

Недетерминированные шаблоны Jinja

Некоторые макросы и переменные окружения могут приводить к неожиданному пересозданию моделей. Например, dbt_utils.get_relations_by_pattern (макрос для анализа метаданных) в сочетании с dbt_utils.union_relations может возвращать объекты базы данных в разном порядке при каждом запуске, формируя разный SQL-код после рендеринга, даже если логика проекта не изменилась. Аналогично, переменные окружения, значения которых меняются между запусками, приводят к формированию разного SQL-кода после рендеринга при каждом запуске:

select '{{ env_var("AIRFLOW_RUN_ID") }}' as airflow_run_id, ...

Сообщить об ошибке в коде

Поскольку порядок результатов запроса или значение переменной окружения меняется, хеш SQL-кода после рендеринга отличается от сохранённого хеша при каждом запуске. dbt State считает это изменением кода и пересоздаёт модель, хотя основная логика проекта не изменилась. Эта ситуация может затронуть модели любого типа, а не только представления: если базовая модель или модель слоя staging пересоздаётся при каждом запуске, все зависящие от неё модели также пересоздаются.

Чтобы избежать этих ненужных пересозданий, включите compare_unrendered_code. При включённом параметре dbt State проверяет и шаблон Jinja, и SQL-код после рендеринга; недетерминированные значения, которые не меняют шаблон, не вызывают пересоздания. Например:

{{ config(state={"compare_unrendered_code": true}) }}

select '{{ env_var("AIRFLOW_RUN_ID") }}' as airflow_run_id, ...

Сообщить об ошибке в коде

Модели с внешними источниками в BigQuery

В BigQuery модели, использующие внешние источники (например, Google Sheets), всегда пересоздаются, поскольку BigQuery не предоставляет временные метки изменения внешних источников, и dbt State не может определить актуальность данных.

подсказка

Чтобы внешние источники не считались устаревшими при каждом запуске, настройте loaded_at_field или loaded_at_query в определении источника, указав поле с временной меткой. Это позволит dbt State запрашивать поле с временной меткой напрямую для определения актуальности данных, а не полагаться на метаданные хранилища.

Модели с пользовательскими материализациями

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

Как провести диагностику

После запуска используйте (Версии dbt: v2.0 и новее) dbt state explain, чтобы узнать, почему dbt State пересоздал, повторно использовал или клонировал конкретную модель. Для подробного разбора используйте флаг --verbose вместе с -s, чтобы выбрать нужную модель:

примечание

Название команды зависит от версии: в dbt v2 используется dbt state explain (с пробелом), а в dbt v1 — dbt-state explain (с дефисом).

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

dbt state explain --verbose -s my_model_name

Сообщить об ошибке в коде

Если вы используете dbt platform, та же информация доступна без выполнения команды — перейдите на вкладку Explain на странице сведений о запуске задания, чтобы увидеть полный разбор принятого решения для каждого узла.

Что происходит при сбое серверов dbt State?

Если серверы dbt State недоступны, dbt автоматически возвращается к обычному режиму работы.

Что делать, если я работаю над несколькими проектами, каждый из которых использует собственный dbt State?

Вы можете указать идентификатор своей организации в dbt_project.yml:

dbt-cloud:
  state-org-id: <your-org-id>

Сообщить об ошибке в коде

Что делать, если моя среда prod называется не prod?

Вы можете указать среду для перенаправления ссылок с помощью настройки defer_to_target в profiles.yml:

my_project:
  outputs:
    prod:
      type: snowflake
      defer_to_target: production

Сообщить об ошибке в коде

defer_to_target применяется только к самостоятельно управляемым развертываниям. Если вы используете платформу dbt, перенаправление ссылок настраивается в параметрах среды в пользовательском интерфейсе. Подробнее см. в разделе Настройка перенаправления ссылок.

Связанная документация

• Настройка dbt State
• Мониторинг работы dbt State
• Настройка аутентификации для неинтерактивных сред
• Настройки dbt State
• Переход с оркестрации с учётом состояния
• Пробный период и оплата dbt State
• Использование и стоимость dbt State

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

Создать GitHub Issue