Обзор синтаксиса
Синтаксис выбора узлов в dbt позволяет запускать только определенные ресурсы в конкретном вызове dbt. Этот синтаксис выбора используется для следующих подкоманд:
| команда | аргумент(ы) |
|---|---|
| run | --select, --exclude, --selector, --defer |
| test | --select, --exclude, --selector, --defer |
| seed | --select, --exclude, --selector |
| snapshot | --select, --exclude --selector |
| ls (list) | --select, --exclude, --selector, --resource-type |
| compile | --select, --exclude, --selector, --inline |
| freshness | --select, --exclude, --selector |
| build | --select, --exclude, --selector, --resource-type, --defer |
| docs generate | --select, --exclude, --selector |
Мы используем термины "узлы" и "ресурсы" взаимозаменяемо. Они охватывают все модели, тесты, источники, семена, снимки, экспозиции и анализы в вашем проекте. Это объекты, которые составляют DAG (ориентированный ациклический граф) dbt.
Указание ресурсов
По умолчанию, dbt run выполняет все модели в графе зависимостей; dbt seed создает все семена, dbt snapshot выполняет каждый снимок. Флаг --select используется для указания подмножества узлов для выполнения.
Чтобы следовать стандартам POSIX и упростить понимание, мы рекомендуем пользователям CLI использовать кавычки при передаче аргументов в опции --select или --exclude (включая один или несколько аргументов, разделенных пробелами или запятыми). Неиспользование кавычек может не работать надежно на всех операционных системах, терминалах и пользовательских интерфейсах. Например, dbt run --select "my_dbt_project_name" запускает все модели в вашем проекте.
Как работает выбор?
-
dbt собирает все ресурсы, которые соответствуют одному или нескольким критериям
--select, в порядке методов выбора (например,tag:), затем операторов графа (например,+), и, наконец, операторов множеств (объединения, пересечения, исключения). -
Выбранные ресурсы могут быть моделями, источниками, семенами, снимками, тестами. (Тесты также могут быть выбраны "косвенно" через их родительские элементы; см. примеры выбора тестов для подробностей.)
-
Теперь у dbt есть список все еще выбранных ресурсов различных типов. На последнем этапе он отбрасывает любой ресурс, который не соответствует типу ресурса текущей задачи. (Только семена сохраняются для
dbt seed, только модели дляdbt run, только тесты дляdbt testи так далее.)
Сокращения
Выберите ресурсы для сборки (запуска, тестирования, семени, снимка) или проверки свежести: --select, -s
Примеры
По умолчанию, dbt run выполнит все модели в графе зависимостей. Во время разработки (и развертывания) полезно указать только подмножество моделей для запуска. Используйте флаг --select с dbt run, чтобы выбрать подмножество моделей для запуска. Обратите внимание, что следующие аргументы (--select, --exclude и --selector) также применимы к другим задачам dbt, таким как test и build.
- Примеры флага select
- Примеры подмножеств узлов
Флаг --select принимает один или несколько аргументов. Каждый аргумент может быть одним из:
- имя пакета
- имя модели
- полностью квалифицированный путь к каталогу моделей
- метод выбора (
path:,tag:,config:,test_type:,test_name:)
Примеры:
dbt run --select "my_dbt_project_name" # запускает все модели в вашем проекте
dbt run --select "my_dbt_model" # запускает конкретную модель
dbt run --select "path/to/my/models" # запускает все модели в конкретном каталоге
dbt run --select "my_package.some_model" # запускает конкретную модель в конкретном пакете
dbt run --select "tag:nightly" # запускает модели с тегом "nightly"
dbt run --select "path/to/models" # запускает модели, содержащиеся в path/to/models
dbt run --select "path/to/my_model.sql" # запускает конкретную модель по ее пути
dbt поддерживает сокращенный язык для определения подмножеств узлов. Этот язык использует следующие символы:
Примеры:
# несколько аргументов могут быть переданы в --select
dbt run --select "my_first_model my_second_model"
# выбрать my_model и всех его потомков
dbt run --select "my_model+"
# выбрать my_model, его потомков и родителей его потомков
dbt run --models @my_model
# эти аргументы могут быть проектами, моделями, путями к каталогам, тегами или источниками
dbt run --select "tag:nightly my_model finance.base.*"
# используйте методы и пересечения для более сложных селекторов
dbt run --select "path:marts/finance,tag:nightly,config.materialized:table"
Когда ваша логика выбора становится более сложной и неудобной для ввода в виде аргументов командной строки, рассмотрите возможность использования yaml-селектора. Вы можете использовать предопределенное определение с флагом --selector. Обратите внимание, что при использовании --selector большинство других флагов (а именно --select и --exclude) будут игнорироваться.
Устранение неполадок с командой ls
Создание и отладка вашего синтаксиса выбора может быть сложной задачей. Чтобы получить "предварительный просмотр" того, что будет выбрано, мы рекомендуем использовать команду list. Эта команда, в сочетании с вашим синтаксисом выбора, выведет список узлов, которые соответствуют этим критериям выбора. Команда dbt ls поддерживает все типы аргументов синтаксиса выбора, например:
dbt ls --select "path/to/my/models" # Список всех моделей в конкретном каталоге.
dbt ls --select "source_status:fresher+" # Показывает источники, обновленные с момента последнего запуска dbt source freshness.
dbt ls --select state:modified+ # Отображает узлы, измененные по сравнению с предыдущим состоянием.
dbt ls --select "result:<status>+" state:modified+ --state ./<dbt-artifact-path> # Список узлов, которые соответствуют определенным статусам результата и изменены.
Вопросы от сообщества
Выбор состояния
Одно из основных предположений о dbt заключается в том, что его операции должны быть без состояния и . То есть, не имеет значения, сколько раз модель была запущена ранее, или была ли она когда-либо запущена ранее. Не имеет значения, запускаете ли вы ее один раз или тысячу раз. При наличии одинаковых исходных данных вы можете ожидать одинаковый преобразованный результат. Конкретный запуск dbt не нуждается в "знании" о любом другом запуске; ему нужно знать только о коде в проекте и объектах в вашей базе данных, как они существуют прямо сейчас.
Тем не менее, dbt действительно хранит "состояние" — детальный, моментальный снимок ресурсов проекта (также называемых узлами), объектов базы данных и результатов вызова — в виде своих артефактов. Если вы выберете, dbt может использовать эти артефакты для информирования определенных операций. Важно, что сами операции остаются без состояния и : при наличии одинакового манифеста и одинаковых исходных данных dbt произведет одинаковый преобразованный результат.
dbt может использовать артефакты из предыдущего вызова, если их путь к файлу передан флагу --state. Это является предварительным условием для:
- Селектора
state, с помощью которого dbt может идентифицировать ресурсы, которые являются новыми или измененными, сравнивая код в текущем проекте с манифестом состояния. - Отложение в другую среду, с помощью которого dbt может идентифицировать вышестоящие, невыбранные ресурсы, которые не существуют в вашей текущей среде, и вместо этого "отложить" их ссылки на среду, предоставленную манифестом состояния.
- Команды
dbt clone, с помощью которой dbt может клонировать узлы на основе их расположения в манифесте, предоставленном флагу--state.
Вместе, селектор state и отложение позволяют "тонкому CI". Мы ожидаем добавить больше функций в будущих выпусках, которые смогут использовать артефакты, переданные флагу --state.
Установление состояния
Состояние и отложение могут быть установлены с помощью переменных окружения, а также флагов CLI:
--stateилиDBT_STATE: путь к файлу--deferилиDBT_DEFER: булево значение
В dbt v1.5 мы устарели оригинальный синтаксис для состояния (DBT_ARTIFACT_STATE_PATH) и отложения (DBT_DEFER_TO_STATE). Хотя dbt поддерживает обратную совместимость со старым синтаксисом, мы удалим его в будущем выпуске, который еще не определен.
--stateилиDBT_STATE: путь к файлу--deferилиDBT_DEFER: булево значение--defer-stateилиDBT_DEFER_STATE: путь к файлу для использования только для отложения (необязательно)
Если --defer-state не указан, отложение будет использовать артефакты, предоставленные --state. Это позволяет более детально контролировать случаи, когда вы хотите сравнить с логическим состоянием из одной среды или прошлого момента времени и отложить до примененного состояния из другой среды или момента времени.
Если предоставлены и флаг, и переменная окружения, флаг имеет приоритет.
Примечания:
- Артефакты
--stateдолжны быть схемами ве рсий, совместимых с текущей версией dbt. - Это мощные, сложные функции. Прочтите о известных оговорках и ограничениях для сравнения состояния.
Статус "result"
Еще один элемент состояния задания — это result предыдущего вызова dbt. После выполнения dbt run, например, dbt создает артефакт run_results.json, который содержит время выполнения и статус успеха / ошибки для моделей dbt. Вы можете прочитать больше о run_results.json на странице 'результаты выполнения'.
Следующие команды dbt создают артефакты run_results.json, результаты которых могут быть использованы в последующих вызовах dbt:
dbt rundbt testdbt build(новое в версии dbt v0.21.0)dbt seed
После выполнения одной из вышеуказанных команд вы можете ссылаться на результаты, добавляя селектор к последующей команде следующим образом:
# Вы также можете установить переменную окружения DBT_STATE вместо флага --state.
dbt run --select "result:<status>" --defer --state path/to/prod/artifacts
Доступные опции зависят от типа ресурса (узла):
result:\<status> | модель | семя | снимок | тест |
|---|---|---|---|---|
result:error | ✅ | ✅ | ✅ | ✅ |
result:success | ✅ | ✅ | ✅ | |
result:skipped | ✅ | ✅ | ✅ | |
result:fail | ✅ | |||
result:warn | ✅ | |||
result:pass | ✅ |
Комбинирование селекторов state и result
Селекторы состояния и результата также могут быть объединены в одном вызове dbt для захвата ошибок из предыдущего запуска ИЛИ любых новых или измененных моделей.
dbt run --select "result:<status>+" state:modified+ --defer --state ./<dbt-artifact-path>
Статус "source_status"
Еще один элемент состояния задания — это source_status предыдущего вызова dbt. После выполнения dbt source freshness, например, dbt создает артефакт sources.json, который содержит время выполнения и даты max_loaded_at для источников dbt. Вы можете прочитать больше о sources.json на странице 'источники'.
Команда dbt source freshness создает артефакт sources.json, результаты которого могут быть использованы в последующих вызовах dbt.
Когда задание выбрано, dbt Cloud отобразит артефакты из последнего успешного запуска этого задания. Затем dbt использует эти артефакты для определения набора свежих источников. В ваших командах задания вы можете указать dbt запускать и тестировать только на более свежих источниках и их потомках, включив аргумент source_status:fresher+. Это требует, чтобы как предыдущее, так и текущее состояния имели доступный артефакт sources.json. Или, проще говоря, оба состояния задания должны запускать dbt source freshness.
После выполнения команды dbt source freshness вы можете ссылаться на результаты свежести источников, добавляя селектор к последующей команде:
# В ы также можете установить переменную окружения DBT_ARTIFACT_STATE_PATH вместо флага --state.
dbt source freshness # необходимо запустить снова для сравнения текущего и предыдущего состояния
dbt build --select "source_status:fresher+" --state path/to/prod/artifacts
Для получения дополнительных примеров команд обратитесь к Советы для рабочих пр оцессов.