Предупреждения
Используйте --warn-error, чтобы повысить все предупреждения до ошибок
Включение конфигурации WARN_ERROR или установка флага --warn-error приведёт к тому, что все предупреждения dbt будут преобразованы в ошибки. Каждый раз, когда dbt обычно выдаёт предупреждение, вместо этого будет выброшена ошибка. Примеры таких ситуаций включают: критерии --select, которые не выбирают ни одного ресурса, устаревшие (deprecated) элементы, конфигурации без связанных моделей, некорректные конфигурации тестов, а также тесты и проверки свежести данных, которые настроены на возврат предупреждений.
dbt run --warn-error
Использование флага --warn-error или --warn-error-options '{"error": "all"}' приведёт к тому, что все текущие и будущие предупреждения будут трактоваться как ошибки.
Использование флага --warn-error или --warn-error-options '{"error": "all"}' приведёт к тому, что все текущие и будущие предупреждения будут обрабатываться как ошибки.
Это означает, что если в будущей версии dbt появится новое предупреждение, ваше задание в производственной среде может неожиданно начать завершаться с ошибкой. Рекомендуем с осторожностью использовать этот подход в производственных средах и явно перечислять только те предупреждения, которые вы хотите обрабатывать как ошибки в этих средах.
Используйте --warn-error-options для целевых предупреждений
В некоторых случаях вы можете захотеть преобразовать все предупреждения в ошибки. Однако, когда вы хотите, чтобы некоторые предупреждения оставались предупреждениями и повышать или подавлять только конкретные предупреждения, вы можете вместо этого использовать --warn-error-options. Конфигурация WARN_ERROR_OPTIONS или флаг --warn-error-options дают вам более детальный контроль над тем, какие именно типы предупреждений считаются ошибками.
WARN_ERROR и WARN_ERROR_OPTIONS являются взаимоисключающимиWARN_ERROR и WARN_ERROR_OPTIONS являются взаимоисключающими. Вы можете указать только один из них, даже если вы задаёте конфигурацию в нескольких местах (например, через переменную окружения или флаг), иначе вы увидите ошибку использования.
Предупреждения, которые следует считать ошибками, можно указать с помощью параметра error. Названия предупреждений можно найти следующими способами:
- В файле types.py в
dbt-labs/dbt, где имя каждого класса, наследующего отWarnLevel, соответствует названию предупреждения (например,AdapterDeprecationWarning,NoNodesForSelectionCriteria). - С помощью флага
--log-format json.
Начиная с версии 1.12, dbt v1 игнорирует названия, специфичные для dbt v2, в warn_error_options (например, StaticAnalysis и PackageParsingCompatibility), вместо того чтобы выдавать ошибку, и выводит примечание: <name> is not being used because it's specific to the dbt Fusion engine. Это позволяет использовать общие конфигурации warn_error_options для dbt v1 и dbt v2. При этом настоящие опечатки по-прежнему вызывают ошибку.
В dbt v2 у каждого предупреждения есть как числовой код (например, 1092), так и имя события (например, NoNodesForSelectionCriteria).
Сообщения во время выполнения содержат и то и другое, но warn_error_options принимает только имя. Используйте имя события, имя, используемое в v2, или поддерживаемую группу (all, *). Числовые коды не принимаются и вызывают ошибку.
Чтобы найти имя по коду из журналов, обратитесь к разделу Поддерживаемые псевдонимы устаревших имен событий dbt-Core.
Параметру error можно присвоить значение "all" или "*", чтобы считать все предупреждения ошибками (это поведение аналогично использованию флага --warn-error), либо список конкретных названий предупреждений, которые следует считать исключениями.
- Если
errorзадан как"all"или"*", через необязательный параметрwarnможно указать предупреждения, которые не нужно превращать в ошибки. - Используйте параметр
silence, чтобы игнорировать предупреждения. Чтобы подавить определённые предупреждения, которые вы хотите игнорировать, вы можете указать их в параметреsilence. Это полезно в крупных проектах, где некоторые предупреждения не являются критичными и могут быть проигнорированы, чтобы снизить уровень шума и сохранить логи чистыми.
Вот как вы можете использовать флаг --warn-error-options, чтобы повышать конкретные предупреждения до ошибок:
- Предупреждения тестов с флагом
--warn-error-options '{"error": ["LogTestResult"]}'. - Jinja предупреждения об исключениях с
--warn-error-options '{"error": ["JinjaLogWarning"]}'. - Отсутствие выбранных узлов с
--warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'. - Предупреждения об устаревании с
--warn-error-options '{"error": ["Deprecations"]}'(новое в v1.10).
Конфигурация
Вы можете настраивать предупреждения как ошибки или определять, какие предупреждения следует подавлять, с помощью warn error options через флаг командной строки, переменную окружения или dbt_project.yml.
Можно выбрать один из вариантов:
- Повышайте все предупреждения до ошибок, используя
{"error": "all"}или флаг--warn-error. - Повышайте конкретные предупреждения до ошибок, используя
error, и при необходимости исключайте другие из обработки как ошибки с помощью флага--warn-error-options.warnуказывает dbt продолжать обрабатывать предупреждения как предупреждения. - Игнорируйте предупреждения, используя
silenceс флагом--warn-error-options.
В следующем примере мы отключаем предупреждение NoNodesForSelectionCriteria в файле dbt_project.yml, добавляя его в параметр silence:
...
flags:
warn_error_options:
error: # ранее называлось "include"
warn: # ранее называлось "exclude"
silence: # чтобы заглушать или игнорировать предупреждения
- NoNodesForSelectionCriteria
Примеры
Вот несколько примеров, которые показывают, как настроить warn_error_options с помощью флагов или файловой конфигурации.
Целевые предупреждения
В некоторых примерах используется NoNodesForSelectionCriteria — это конкретное предупреждение, которое возникает, когда ваш флаг --select не соответствует ни одному узлу/ресурсу в вашем проекте dbt:
-
Эта команда повышает все предупреждения до ошибок, за исключением
NoNodesForSelectionCriteria:dbt run --warn-error-options '{"error": "all", "warn": ["NoNodesForSelectionCriteria"]}' -
Эта команда повышает все предупреждения до ошибок, за исключением предупреждений об устаревании:
dbt run --warn-error-options '{"error": "all", "warn": ["Deprecations"]}' -
Эта команда повышает только
NoNodesForSelectionCriteriaдо уровня ошибки:dbt run --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}' -
Это переводит в категорию ошибок только
(Версии dbt: v1.11 и новее)NoNodesForSelectionCriteriaс помощью переменной окружения:DBT_ENGINE_WARN_ERROR_OPTIONS='{"error": ["NoNodesForSelectionCriteria"]}' dbt run
Значения для error, warn и/или silence следует передавать в виде массивов. Например, dbt run --warn-error-options '{"error": "all", "warn": ["NoNodesForSelectionCriteria"]}', а не dbt run --warn-error-options '{"error": "all", "warn": "NoNodesForSelectionCriteria"}'.
Следующий пример показывает, как повысить все предупреждения до ошибок, за исключением предупреждения NoNodesForSelectionCriteria, используя параметры silence и warn в файле dbt_project.yml:
...
flags:
warn_error_options:
error: all # ранее называлось "include"
warn: # ранее называлось "exclude"
- NoNodesForSelectionCriteria
silence: # чтобы заглушать или игнорировать предупреждения
- NoNodesForSelectionCriteria
Повышение всех предупреждений до ошибок
Несколько примеров того, как повысить все предупреждения до ошибок:
используя флаги команд dbt
dbt run --warn-error
dbt run --warn-error-options '{"error": "all"}'
dbt run --warn-error-options '{"error": "*"}'
используя переменные окружения
(Версии dbt: v1.11 и новее)WARN_ERROR=true dbt run
DBT_ENGINE_WARN_ERROR_OPTIONS='{"error": "all"}' dbt run
DBT_ENGINE_WARN_ERROR_OPTIONS='{"error": "*"}' dbt run
Обратите внимание: использование warn_error_options: error: "all" приведёт к тому, что все текущие и будущие предупреждения будут обрабатываться как ошибки.
Это означает, что если в будущей версии dbt появится новое предупреждение, ваше задание в производственной среде может неожиданно начать завершаться с ошибкой. Мы рекомендуем с осторожностью применять такой подход в производственных средах и явно перечислять только те предупреждения, которые вы хотите считать ошибками в этих средах.
Поведение dbt v2 и коды предупреждений
dbt v2 полностью поддерживает warn_error_options. Ниже описаны важные отличия от dbt v1.
Имена событий dbt Core делятся на три категории:
- Поддерживаются: сопоставляются с аналогичными предупреждениями dbt v2 и работают примерно так же.
- Не будут поддерживаться: события, поддержку которых не планируется добавлять.
- Пока не поддерживаются: имена распознаются, но пока ничего не меняют.
Коды предупреждений в dbt v2
В dbt v2 у каждого предупреждения есть числовой код, например 1092, и имя события, например NoNodesForSelectionCriteria. При выполнении dbt показывает и код, и имя, но warn_error_options принимает только имена событий:
flags:
warn_error_options:
error:
- NothingToDo # by name
silence:
- FreshnessConfigProblem # by name
Если указать неподдерживаемое имя события, неподдерживаемую группу или числовой код, dbt v2 завершится ошибкой при запуске. Допустимы поддерживаемые имена из Core или v2, а также группы all и *. Например, {error: [1092]} не сработает, а {error: [NoNodesForSelectionCriteria]} сработает.
В таблицах на этой странице перечислены не все допустимые имена. У dbt v2 есть собственные предупреждения, например SemanticModelDeprecated с кодом dbt1157. Для настройки используйте имя из сообщения при выполнении.
Поддерживаемые псевдонимы событий dbt Core
Если в журнале появился код предупреждения, найдите в таблице соответствующее имя события для warn_error_options. Столбец с кодом нужен только для поиска предупреждений при выполнении. В самой настройке код использовать нельзя.
| Код dbt v2 (только при выполнении) | Имя события dbt Core (для конфигурации) | Описание |
|---|---|---|
| 1601 | NoNodesSelected | Нет выбранных узлов |
| 1601 | NothingToDo | Нет выбранных узлов (псевдоним) |
| 1087 | NodeNotFoundOrDisabled | Тест или зависимость экспозиции ссылается на отсутствующий или отключённый узел |
| 1085 | DeprecatedModel | Дата прекращения поддержки модели прошла, модель следует удалить |
| 1072 | DeprecatedReference | Ссылка на модель, поддержка которой уже прекращена |
| 1073 | UpcomingReferenceDeprecation | Ссылка на модель, поддержка которой прекратится в будущем |
| 1074 | JinjaLogWarning | В макросе Jinja вызван exceptions.warn() |
| 1075 | SnapshotTimestampWarning | Не совпадает тип столбца с меткой времени снимка |
| 1076 | PackageRedirectDeprecation | Пакет перенаправлен на новое имя. Обновите packages.yml |
| 1077 | DepsUnpinned | Для Git-пакета не закреплена ревизия (HEAD, main или master) |
| 1078 | FreshnessConfigProblem | Для источника не настроена актуальность, проверка пропущена |
| 1084 | WarnStateTargetEqual | Пути каталогов --state и --target совпадают |
| 1086 | WEOIncludeExcludeDeprecation | В warn_error_options использованы устаревшие ключи include или exclude. Используйте error и warn |
| 1089 | NoNodeForYamlKey | Ключ YAML ссылается на узел, которого нет в проекте |
| 1090 | MacroNotFoundForPatch | Запись patches: в YAML ссылается на отсутствующий макрос |
| 1091 | InvalidConcurrentBatchesConfig | Задан concurrent_batches, но модель его не поддерживает |
| 1092 | NoNodesForSelectionCriteria | Критерии --select не выбрали ни одного узла |
| 1093 | MicrobatchModelNoEventTimeInputs | У microbatch-модели нет входных ресурсов с настроенным event_time |
| 1094 | UnversionedBreakingChange | В модель без версии внесено несовместимое изменение |
| 1095 | UnsupportedConstraintMaterialization | Ограничение задано для материализации, которая его не поддерживает |
| 1097 | UnusedResourceConfigPath | Путь +config в dbt_project.yml не соответствует ни одному ресурсу |
| 1098 | DepsScrubbedPackageName | Из имени пакета при установке удалены недопустимые символы |
| 1099 | DepsFoundDuplicatePackage | Один пакет указан в packages.yml несколько раз |
| 1506 | InvalidMacroAnnotation | Имя или тип аргумента в YAML-аннотации макроса не соответствует его определению Jinja |
| без кода | LogTestResult | Результат теста данных (успех, предупреждение или ошибка) |
| без кода | RunResultWarning | Модель или тест завершились со статусом warn |
| без кода | RunResultWarningMessage | Сообщение к результату запуска со статусом warn |
Неподдерживаемые имена событий dbt v1
В dbt v2 действительны только прежние имена из списка Поддерживаемые псевдонимы событий dbt Core. У dbt v1 есть и другие имена событий, которые dbt v2 не принимает. Если указать другое имя в warn_error_options, при запуске появится предупреждение.
Таблица перечисляет только те неподдерживаемые имена событий dbt v1, которые dbt v2 распознаёт, чтобы при запуске объяснить, почему они не действуют. Удалите эти записи: соответствующее поведение dbt v1 удалено, заменено или применяется в dbt v2 безусловно. Другие неподдерживаемые имена тоже вызывают предупреждение при проверке warn_error_options на старте.
| Имя события dbt Core | Сообщение |
|---|---|
MicrobatchMacroOutsideOfBatchesDeprecation | dbt v2 поддерживает только новое поведение, при котором это ошибка. |
SeedExceedsLimitSamePath | Предупреждение относится к частичному разбору в dbt v1. dbt v2 не поддерживает частичный разбор. |
SeedIncreased | Предупреждение относится к частичному разбору в dbt v1. dbt v2 не поддерживает частичный разбор. |
GenerateSchemaNameNullValueDeprecation | dbt v2 поддерживает только новое поведение, при котором это ошибка. |
GenericSemanticLayerDeprecation | dbt v2 уже использует новую спецификацию семантического слоя, поэтому предупреждение неприменимо. |
MFCumulativeTypeParamsDeprecation | dbt v2 уже использует новую спецификацию семантического слоя, поэтому предупреждение неприменимо. |
MFTimespineWithoutYamlConfigurationDeprecation | dbt v2 уже использует новую спецификацию семантического слоя, поэтому предупреждение неприменимо. |
MetricAttributesRenamed | dbt v2 уже использует новую спецификацию семантического слоя, поэтому предупреждение неприменимо. |
TimeDimensionsRequireGranularityDeprecation | dbt v2 уже использует новую спецификацию семантического слоя, поэтому предупреждение неприменимо. |
SourceFreshnessProjectHooksNotRun | dbt v2 уже использует новое поведение проверок актуальности источников, поэтому предупреждение неприменимо. |
SemanticValidationFailure | dbt v2 не поддерживает семантические модели, поэтому предупреждение неприменимо. |
ValidationWarning | dbt v2 уже строго проверяет допустимые ключи YAML, поэтому предупреждение избыточно. |
PackageMaterializationOverrideDeprecation | dbt v2 уже применяет новое поведение, запрещающее пакетам переопределять встроенные материализации. |
TestsConfigDeprecation | dbt v2 по умолчанию не показывает предупреждение, как и текущая версия dbt v1. |
ProjectFlagsMovedDeprecation | dbt v2 выдаёт ошибку для этой конфигурации, как и более новые версии dbt v1. |
ConfigSourcePathDeprecation | Эта настройка окончательно устарела в dbt v2. |
ConfigLogPathDeprecation | Эта настройка окончательно устарела в dbt v2. |
ConfigTargetPathDeprecation | Эта настройка окончательно устарела в dbt v2. |
ConfigDataPathDeprecation | Эта настройка окончательно устарела в dbt v2. |
EnvironmentVariableNamespaceDeprecation | dbt v2 резервирует префикс DBT_ENGINE_ и отклоняет неизвестные переменные окружения с таким префиксом. |
UnusedTables | dbt v2 не разрешает переопределять источники. Пакетам нужно явно отключать источник. |
WrongResourceSchemaFile | dbt v2 сообщает об этом через NoNodeForYamlKey. |
PackageNodeDependsOnRootProjectNode | dbt v2 поддерживает только новое поведение require_ref_searches_node_package_before_root, при котором это ошибка. |
Предупреждения, которые в dbt v2 являются ошибками
Некоторые предупреждения dbt v1 в dbt v2 всегда считаются ошибками разбора. Если указать их имена в warn_error_options, dbt v2 предупредит об этом при запуске. Перенос конфигурации из Core не прерывает запуск, но такие записи не действуют, помечаются как unsupported и подлежат удалению:
| Имя события dbt Core | Поведение dbt v2 | Код ошибки dbt v2 |
|---|---|---|
DuplicateYAMLKeysDeprecation | Парсер YAML в dbt v2 отклоняет повторяющиеся ключи с ошибкой разбора | DuplicateConfigKey (1059) |
CustomKeyInConfigDeprecation | Строгая проверка схемы отклоняет неизвестные ключи конфигурации | UnusedConfigKey (1060) |
CustomTopLevelKeyDeprecation | Неизвестные ключи верхнего уровня вызывают ошибку разбора | UnusedConfigKey (1060) |
ResourceNamesWithSpacesDeprecation | Имена ресурсов с пробелами отклоняются при проверке имён | SchemaError |
InvalidValueForField | Недопустимые значения полей вызывают ошибку разбора при десериализации | SerializationError |
GenericJSONSchemaValidationDeprecation | Сбой проверки схемы JSON вызывает ошибку разбора | SerializationError |
DuplicateNameDistinctNodeTypesDeprecation | При разрешении узлов возникает ошибка | SchemaError |
Флаг --warn-error при статическом анализе в режиме baseline
Если статический анализ выдаёт предупреждения и включён --warn-error, превращающий все предупреждения в ошибки, запуск может неожиданно завершиться сбоем. Лучше явно перечислить категории предупреждений, которые нужно считать ошибками. В режиме baseline не используйте для этой цели error: all.
Устаревшие ключи include и exclude
Ключи include и exclude в warn_error_options устарели в dbt v1.8, но по-прежнему распознаются в dbt v2. При их использовании dbt v2 выдаёт предупреждение WEOIncludeExcludeDeprecation (код 1086) и игнорирует эти ключи. Перейдите на error, warn и silence:
# Before (dbt ≤1.7)
flags:
warn_error_options:
include: all
exclude:
- NoNodesForSelectionCriteria
# After (dbt ≥1.8 and v2)
flags:
warn_error_options:
error: all
warn:
- NoNodesForSelectionCriteria