# Команды заданий

Платформа dbt

Задание dbt для производственной среды позволяет настроить систему для запуска задания dbt и его команд по расписанию вместо ручного выполнения команд dbt из командной строки или [Studio IDE](https://docs.getdbt.tech/docs/platform/studio-ide/develop-in-studio.md). Задание состоит из команд, объединённых в «цепочку» и выполняемых в виде шагов запуска. Каждый шаг запуска может завершиться успешно или с ошибкой, что может определять статус запуска задания (Success, Cancel или Error).

Каждая job позволяет вам:

* Настраивать job commands
* Просматривать детали запусков job, включая тайминги, артефакты и подробные шаги запуска
* Открывать логи, чтобы просматривать их, помогать с отладкой проблем и видеть историю запусков dbt
* Настраивать уведомления и [другое](https://docs.getdbt.tech/docs/deploy/deployments.md#%D1%80%D0%B0%D0%B7%D0%B2%D0%B5%D1%80%D1%82%D1%8B%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-%D1%81-dbt)

## Типы команд job

Job commands — это конкретные задачи, которые выполняются в рамках job. Их можно настроить двумя способами: добавлять [dbt-команды](https://docs.getdbt.tech/reference/dbt-commands.md) или использовать опции‑чекбоксы в разделе **Commands**.

Во время запуска job команды выполняются «цепочкой» и идут как run steps. При добавлении dbt-команды в разделе **Commands** вы можете ожидать иные результаты по сравнению с вариантом через чекбоксы.

[![Настройка флажка и списка команд](/img/docs/dbt-platform/using-dbt-platform/job-commands.gif?v=2 "Настройка флажка и списка команд")](#)Настройка флажка и списка команд

### Встроенные команды

Каждый запуск job автоматически включает команду [`dbt deps`](https://docs.getdbt.tech/reference/commands/deps.md), поэтому вам не нужно добавлять ее в список **Commands** в настройках job. Также вы заметите, что у каждой job есть шаг повторного клонирования репозитория и подключения к data platform — это может повлиять на статус job, если эти шаги не выполнятся успешно.

**Результат job** — Во время запуска job built-in commands выполняются «цепочкой». Это означает, что если один из шагов в цепочке падает, последующие команды не выполняются, а вся job завершается со статусом "Error".

[![Неудачное задание, в котором возникла ошибка на этапе выполнения dbt deps.](/img/docs/dbt-platform/using-dbt-platform/fail-dbtdeps.png?v=2 "Неудачное задание, в котором возникла ошибка на этапе выполнения dbt deps.")](#)Неудачное задание, в котором возникла ошибка на этапе выполнения dbt deps.

### Список команд

Вы можете добавлять или удалять столько команд dbt, сколько необходимо для каждого задания. Однако в задании должна быть хотя бы одна команда dbt. На странице [справочника команд dbt](https://docs.getdbt.tech/reference/dbt-commands.md) некоторые команды помечены как "dbt CLI" или "dbt v1". Это означает, что они предназначены для использования в dbt v1 или dbt CLI, а не в Studio IDE.

Чтобы запускать линтинг в задании, включите **Linting** при [настройке задания CI](https://docs.getdbt.tech/docs/deploy/ci-jobs.md#set-up-ci-jobs). В заданиях развертывания этот параметр недоступен, и добавить команду `dbt lint` в список **Commands** нельзя. Подробнее о том, как линтинг работает в v1 и v2, какие файлы он проверяет и что происходит при неудачной проверке, см. в разделе [Линтинг SQL](https://docs.getdbt.tech/docs/deploy/continuous-integration.md#sql-linting).

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

Для заданий v2:

* Добавлять команду для генерации документации не нужно. Каждый запуск задания автоматически обновляет метаданные [Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md). Подробнее см. в разделе [Настройка задания для генерации документации](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md?version=2#set-up-a-documentation-job).
* Чтобы перед построением моделей проверить актуальность исходных данных, добавьте `dbt source freshness` в список **Commands** или установите флажок **Run source freshness**. Подробнее см. в разделе [Актуальность источников](https://docs.getdbt.tech/docs/deploy/source-freshness.md).

Используйте selectors

Используйте [selectors](https://docs.getdbt.tech/reference/node-selection/syntax.md) как мощный способ выбирать и выполнять части проекта во время запуска job. Например, чтобы запускать тесты для `one_specific_model`, используйте селектор: `dbt test --select one_specific_model`. Job всё равно выполнится, даже если selector не совпадет ни с одной моделью.

#### Кастомные команды для Compare changes

Если у вас включена функция Advanced CI [compare changes](https://docs.getdbt.tech/docs/deploy/advanced-ci.md#compare-changes) и вы выбрали чекбокс **dbt compare**, вы можете добавить кастомные dbt-команды, чтобы оптимизировать выполнение сравнения (например, исключить большие модели или группы моделей по тегам). Сравнение на больших моделях может заметно увеличить время выполнения CI jobs.

[![Добавление кастомных dbt-команд при использовании dbt compare](/img/docs/deploy/dbt-compare.jpg?v=2 "Добавление кастомных dbt-команд при использовании dbt compare")](#)Добавление кастомных dbt-команд при использовании dbt compare

Ниже приведены примеры, показывающие, как можно кастомизировать поле команды dbt compare:

* Исключить большую модель `fct_orders` из сравнения, чтобы запускать CI job на меньшем количестве или меньшем размере моделей и сократить время/потребление ресурсов. Используйте следующую команду:

  ```sql
  --select state:modified --exclude fct_orders
  ```

* Исключите модели на основе тегов для сценариев, когда модели имеют общую функцию или характеристику. Используйте следующую команду:

  ```sql
     --select state:modified --exclude tag:tagname_a tag:tagname_b
  ```

* Включите модели, которые были непосредственно изменены, а также те, которые находятся на один шаг ниже по потоку, используя селектор `modified+1`. Используйте следующую команду:

  ```sql
  --select state:modified+1
  ```

#### Результат job

Во время запуска job команды выполняются «цепочкой» и идут как run steps. Если один из шагов в цепочке падает, последующие шаги не выполняются, и job завершится с ошибкой.

На изображении ниже первые четыре run steps успешны. Однако если пятый шаг (`dbt run --select state:modified+ --full-refresh --fail-fast`) падает, следующие шаги не выполняются, и вся job завершается с ошибкой. Неуспешная job возвращает ненулевой [exit code](https://docs.getdbt.tech/reference/exit-codes.md) и статус job "Error":

[![Неудачный запуск задания из-за ошибки на одном из этапов выполнения](/img/docs/dbt-platform/using-dbt-platform/skipped-jobs.png?v=2 "Неудачный запуск задания из-за ошибки на одном из этапов выполнения")](#)Неудачный запуск задания из-за ошибки на одном из этапов выполнения

## Ошибки выполнения job commands

Ошибки job commands могут означать разные вещи для разных команд. Некоторые распространенные причины, по которым job command может завершиться неуспешно:

* **Ошибка при выполнении `dbt run`** — [`dbt run`](https://docs.getdbt.tech/reference/commands/run.md) выполняет скомпилированные SQL-файлы моделей в текущей целевой базе данных. Команда завершится с ошибкой, если в любой из создаваемых моделей возникнет ошибка. По умолчанию, если выполнение модели завершается с ошибкой, зависимые от неё модели также пропускаются. В dbt v1.12+ можно задать для модели [`on_error: continue`](https://docs.getdbt.tech/reference/resource-configs/on_error.md), чтобы разрешить попытку выполнения зависимых от неё моделей, несмотря на ошибку.

* **Ошибка при выполнении `dbt test`** — [`dbt test`](https://docs.getdbt.tech/reference/commands/test.md) запускает тесты, определённые для моделей, источников, снимков и seed-файлов. Тест может пройти успешно, завершиться с ошибкой или выдать предупреждение в зависимости от его [уровня серьёзности](https://docs.getdbt.tech/reference/resource-configs/severity.md). Если вы не настроили [обработку предупреждений как ошибок](https://docs.getdbt.tech/reference/global-configs/warnings.md), только ошибка приводит к неуспешному завершению команды. Тесты вышестоящих ресурсов блокируют выполнение зависимых ресурсов, а при неуспешном тесте эти ресурсы пропускаются.

* **Ошибка при выполнении `dbt build`** — [`dbt build`](https://docs.getdbt.tech/reference/commands/build.md) запускает модели, тесты, снимки и seed-файлы. Эта команда выполняет ресурсы в порядке, заданном DAG. Если выполнение любого вышестоящего ресурса завершается с ошибкой, все зависимые ресурсы пропускаются, а команда завершается с кодом ошибки `1`. В dbt v1.12+ можно задать для модели [`on_error: continue`](https://docs.getdbt.tech/reference/resource-configs/on_error.md), чтобы разрешить попытку выполнения зависимых от неё моделей, если выполнение этой модели завершится с ошибкой.

* **Ошибки при использовании селекторов**

  * Если [`select`](https://docs.getdbt.tech/reference/node-selection/set-operators.md) выбирает несколько узлов и выполнение одного из них завершается с ошибкой, задание завершится с кодом `1`, а последующая команда завершится с ошибкой. Если указан флаг [`--fail-fast`](https://docs.getdbt.tech/reference/global-configs/failing-fast.md), первая же ошибка приведёт к закрытию всех соединений для моделей, выполнение которых ещё продолжается.

  * Если selector не совпадает ни с одной нодой, это не считается ошибкой.

## Связанные материалы

* [Рекомендации по созданию заданий](https://discourse.getdbt.com/t/job-creation-best-practices-in-dbt-cloud-feat-my-moms-lasagna/2980)
* [Справочник команд dbt](https://docs.getdbt.tech/reference/dbt-commands.md)
* [Уведомления о заданиях](https://docs.getdbt.tech/docs/deploy/job-notifications.md)
* [Актуальность источников](https://docs.getdbt.tech/docs/deploy/source-freshness.md)
* [Сборка и просмотр документации](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md)
