Программные вызовы
Программные вызовы позволяют вызывать команды dbt из скриптов и приложений на Python, а не запускать их в командной оболочке. Это полезно, когда нужно встроить запуски dbt в более крупное приложение или рабочий процесс, используя при этом тот же набор команд, что и в dbt CLI.
Типичные сценарии использования:
- Запуск dbt как части приложения или сервиса на Python
- Интеграция запусков dbt в процессы оркестрации
- Создание внутренних инструментов, которым нужно выполнять команды dbt и анализировать результаты
Если вы ещё не установили официальный пакет Python для dbt v1, перейдите на страницу пакета dbt v1 на PyPI для его установки.
(Версии dbt: v2.0 и новее)from dbt.cli.main import dbtRunner, dbtRunnerResult
# initialize
dbt = dbtRunner()
# create CLI args as a list of strings
cli_args = ["run", "--select", "tag:my_tag"]
# run the command
res: dbtRunnerResult = dbt.invoke(cli_args)
# inspect the results
for r in res.result:
print(f"{r.unique_id}: {r.status}")
Подробности реализации см. в крейте dbt-python в репозитории dbt v1.
Поддерживаемые аргументы
dbtRunner.invoke принимает те же аргументы, что и dbt CLI. Первый позиционный аргумент — это команда (например, run, build, test), за которой следуют флаги и параметры, которые вы обычно передаёте в командной строке.
Например, dbt.invoke(["run", "--select", "tag:my_tag"]) эквивалентен выполнению dbt run --select tag:my_tag. Отдельного списка аргументов для dbtRunner нет; официальным источником информации о доступных параметрах служат справка CLI (dbt --help, dbt run --help и т. д.) и справочник команд dbt.
from dbt.cli.main import dbtRunner
dbt = dbtRunner()
# equivalent ways to pass arguments
dbt.invoke(["run", "--select", "tag:my_tag"])
dbt.invoke(["run"], select="tag:my_tag")
Параллельное выполнение не поддерживается
dbt не поддерживает безопасное параллельное выполнение нескольких вызовов в одном процессе. Одновременное выполнение нескольких команд dbt в одном процессе небезопасно и официально не рекомендуется; для этого требуется процесс-обёртка, управляющий подпроцессами. Причины следующие:
- Одновременно выполняемые команды могут непредвиденным образом взаимодействовать с платформой данных. Например, одновременное выполнение
dbt runиdbt buildдля одних и тех же моделей может привести к непредсказуемым результатам. - Каждая команда
dbtвзаимодействует с глобальными переменными Python. Для безопасной работы команды необходимо выполнять в отдельных процессах, например создавая подпроцессы или используя Celery для оркестрации.
Для безопасного параллельного выполнения можно использовать dbt platform CLI или Studio IDE: оба инструмента берут на себя дополнительную работу по управлению одновременным выполнением в нескольких процессах.
(Версии dbt: v2.0 и новее)В v2 вызовы выполняются последовательно благодаря блокировкам на уровне потоков, поэтому несколько вызовов не могут выполняться одновременно в одном процессе. (В v1 параллельное выполнение не поддерживалось, но блокировок не было, поэтому вызовы всё же могли выполняться в многопоточном режиме.) Как и в v1, вы по-прежнему можете распараллеливать выполнение, используя несколько процессов и выполняя каждый вызов в отдельном процессе.
dbtRunnerResult
Каждая команда возвращает объект dbtRunnerResult со следующими атрибутами:
success(bool): Указывает, успешно ли выполнена команда.result: Когда команда завершается (успешно или с обработанными ошибками), содержит результат или результаты команды. Тип возвращаемого значения зависит от команды.exception: Когда при вызове dbt возникает необработанная ошибка и выполнение не завершается, содержит возникшее исключение.catalog(только v2): Каталог, который команда создаёт при запросе генерации каталога.
Движок v2 реализован на Rust, поэтому exception больше не содержит исходный объект исключения Python, возникшего в dbt. Вместо этого перехваченное сообщение об ошибке передаётся в исключении соответствующего типа:
- Если вызов завершается с ошибкой на границе интерфейса внешних функций (FFI), прежде чем движок начнёт его обрабатывать,
exceptionсодержит исключение без дополнительной обёртки, напримерValueErrorилиRuntimeError. - Если вызов завершается с ошибкой внутри движка,
exceptionсодержитDbtRunnerError.
В v2 в dbtRunnerResult также добавляется атрибут верхнего уровня catalog, если запрошена генерация каталога.
В v1 файл catalog.json создавался только при запуске dbt docs generate. В v2 каталог можно сгенерировать при выполнении любой команды, передав флаг --write-catalog. Например, dbt run --write-catalog заполняет и dbtRunnerResult.result, и dbtRunnerResult.catalog.
Между кодами завершения CLI и объектом dbtRunnerResult, возвращаемым при программном вызове, существует взаимно однозначное соответствие:
| Сценарий | Код завершения CLI | success | result | exception |
|---|---|---|---|---|
| Вызов завершился без ошибок | 0 | True | зависит от команды | None |
| Вызов завершился как минимум с одной обработанной ошибкой (например, сбоем теста или ошибкой построения модели) | 1 | False | зависит от команды | None |
| Необработанная ошибка. Вызов не завершился и не возвращает результатов. | 2 | False | None | Исключение |
Обязательства и оговорки
Мы берём на себя долгосрочное обязательство предоставлять точку входа Python, функционально эквивалентную CLI dbt v1. Мы оставляем за собой право менять внутреннюю реализацию, используемую для достижения этой цели. Мы ожидаем, что текущая реализация позволит решать реальные задачи в краткосрочной и среднесрочной перспективе, пока мы работаем над набором стабильных, долгосрочных интерфейсов, которые в конечном итоге её заменят.
В частности, для объектов, возвращаемых каждой командой в dbtRunnerResult.result, не определён полный контракт, поэтому они могут изменяться. Некоторые из возвращаемых объектов частично документированы, поскольку отчасти совпадают с содержимым артефактов dbt. Как объекты Python, они содержат гораздо больше полей и методов, чем доступно в сериализованных артефактах JSON. Эти дополнительные поля и методы следует считать внутренними и подлежащими изменению в будущих версиях dbt.
Расширенные шаблоны использования
Синтаксис и поддержка этих подходов могут измениться в будущих версиях dbt.
Цель dbtRunner — обеспечить в программной среде те же возможности, что и при работе через CLI. Существует несколько продвинутых подходов к использованию, которые расширяют возможности CLI.
Повторное использование объектов
Передача готового манифеста не поддерживается в v2. Вы не можете передать предварительно созданный объект Manifest в dbtRunner.
Регистрация обработчиков обратного вызова
Регистрация обработчиков обратного вызова в EventManager dbt не поддерживается в v2.
Переопределение параметров
Передавайте параметры как именованные аргументы, а не в виде списка строк в стиле CLI. В настоящее время dbt не выполняет проверку или приведение типов входных значений. Команда должна быть указана в виде списка в первом позиционном аргументе.
from dbt.cli.main import dbtRunner
dbt = dbtRunner()
# эти команды эквивалентны
dbt.invoke(["--fail-fast", "run", "--select", "tag:my_tag"])
dbt.invoke(["run"], select=["tag:my_tag"], fail_fast=True)