Настройка и использование dbt platform CLI

Узнайте, как настроить dbt platform CLI для вашего проекта dbt, чтобы выполнять команды dbt, например dbt environment show для просмотра конфигурации dbt или dbt compile для компиляции проекта и проверки моделей и тестов. Вы также получите следующие преимущества:

• Безопасное хранение учетных данных в dbt platform.
• Автоматическое перенаправление ссылок с использованием артефактов сборки из производственной среды вашего проекта.
• Более быстрые сборки с меньшими затратами.
• Поддержка Mesh (межпроектные ссылки ref) и другие возможности.

Предварительные требования

• Необходимо настроить проект в dbt.
  • Примечание — Если вы используете dbt platform CLI, вы можете подключиться к своей платформе данных непосредственно в интерфейсе dbt platform; файл profiles.yml при этом не требуется.
• В разделе Account settings необходимо настроить личные учетные данные пользователя для этого проекта. dbt platform CLI будет использовать эти учетные данные, безопасно хранящиеся в dbt, для взаимодействия с вашей платформой данных.
• Необходимо использовать dbt версии 1.5 или выше. Инструкции по обновлению см. в разделе Версии dbt.

Настройка dbt platform CLI

После установки dbt platform CLI необходимо настроить его для подключения к проекту dbt.

1. В dbt выберите проект, для которого вы хотите настроить dbt platform CLI. В проекте уже должна быть настроена среда разработки.

2. Скачайте файл учетных данных dbt_cloud.yml и сохраните его в каталоге .dbt (~/.dbt/dbt_cloud.yml в macOS/Linux, C:\Users\yourusername\.dbt\dbt_cloud.yml в Windows). Инструкции по скачиванию, полную структуру файла и справочник полей см. в разделе dbt_cloud.yml.

3. После скачивания файла конфигурации и создания каталога перейдите в каталог проекта в терминале:

   cd ~/dbt-projects/jaffle_shop

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

4. Убедитесь, что в файле dbt_project.yml есть блок dbt-cloud с полем project-id, указывающим на ваш проект dbt, или добавьте его.

   # dbt_project.yml
   dbt-cloud:
       project-id: PROJECT_ID

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

5. Теперь вы можете использовать dbt platform CLI и выполнять команды dbt, например dbt environment show для просмотра подробной информации о конфигурации dbt или dbt compile для компиляции моделей в вашем проекте dbt.

После повторного клонирования репозитория вы можете добавлять и редактировать файлы, а также синхронизировать их с репозиторием.

Настройка переменных окружения

Чтобы настроить переменные окружения в dbt platform CLI для вашего проекта dbt:

1. В dbt нажмите на имя своей учетной записи в левом боковом меню и выберите Account settings.
2. В разделе Your profile выберите Credentials.
3. Нажмите на свой проект и прокрутите страницу до раздела Environment variables.
4. Нажмите Edit в правом нижнем углу, затем задайте переменные окружения на уровне пользователя.

Использование dbt platform CLI

dbt platform CLI использует тот же набор команд dbt и команд MetricFlow, что и dbt v1, для выполнения указанных вами команд. Например, используйте команду dbt environment, чтобы просмотреть подробную информацию о конфигурации dbt. С помощью dbt platform CLI вы можете:

• Выполнять несколько вызовов параллельно, обеспечивая безопасное параллельное выполнение.
• Автоматически перенаправлять ссылки, используя артефакты сборки из производственной среды вашего проекта.
• Использовать зависимости между проектами, которые позволяют вашему проекту зависеть от другого проекта с помощью сервиса метаданных в dbt.
  • Зависимости между проектами позволяют сразу подключаться к публичным моделям, определенным в других проектах, и ссылаться на них (с помощью ref). Вам не нужно самостоятельно выполнять или анализировать эти вышестоящие модели. Вместо этого вы работаете с ними как с API, возвращающим набор данных.

Используйте флаг --help

Полезный совет: большинство инструментов командной строки поддерживают флаг --help для просмотра доступных команд и аргументов. Используйте флаг --help с dbt двумя способами:

• dbt --help: выводит список доступных команд dbt
  
• dbt run --help: выводит список флагов, доступных для команды run

Проверка SQL-файлов линтером

Из dbt platform CLI можно вызывать SQLFluff — модульный настраиваемый SQL-линтер, который предупреждает о сложных функциях, ошибках синтаксиса, форматирования и компиляции. Многие флаги, которые можно передавать SQLFluff, также доступны в dbt platform CLI.

Доступны следующие команды SQLFluff:

• lint — Проверяет SQL-файлы линтером, принимая список файлов или данные из стандартного ввода (stdin).
• fix — Исправляет SQL-файлы.
• format — Автоматически форматирует SQL-файлы.

Чтобы проверить SQL-файлы линтером, выполните следующую команду:

dbt sqlfluff lint [PATHS]... [flags]

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

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

Чтобы просмотреть подробную информацию обо всех командах и флагах, поддерживаемых dbt, выполните команду dbt sqlfluff -h.

Особенности использования

При выполнении dbt sqlfluff из dbt platform CLI важно учитывать следующие особенности поведения:

• dbt считывает пользовательские настройки из файла .sqlfluff, если он существует.
• Для рабочих процессов непрерывной интеграции и непрерывной разработки (CI/CD) в проекте должен быть файл dbt_cloud.yml, а команды из каталога этого проекта dbt должны быть успешно выполнены хотя бы один раз.
• Команда SQLFluff возвращает код завершения 0, даже если при ее выполнении обнаружены нарушения в файлах. Это поведение dbt отличается от поведения SQLFluff, где нарушение, обнаруженное линтером, приводит к ненулевому коду завершения. dbt Labs планирует исправить это в одном из будущих выпусков.

Особенности использования

dbt platform CLI в настоящее время не поддерживает относительные пути в файле packages.yml. Вместо этого используйте Studio IDE, который поддерживает относительные пути в этом случае.

Ниже приведён пример конфигурации локального пакета в файле packages.yml, которая не будет работать с dbt platform CLI:

# repository_root/my_dbt_project_in_a_subdirectory/packages.yml

packages:
  - local: ../shared_macros

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

В этом примере ../shared_macros — это относительный путь, который указывает dbt:

• .. — перейти на один уровень вверх (в repository_root);
• /shared_macros — найти папку shared_macros в корневом каталоге.

Чтобы обойти это ограничение, используйте Studio IDE, который полностью поддерживает относительные пути в packages.yml.

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

 Как создать каталог .dbt и переместить в него файл

Если у вас ещё нет директории .dbt, рекомендуется выполнить следующие шаги, чтобы создать её. Если директория .dbt у вас уже есть, переместите файл dbt_cloud.yml внутрь неё. Ниже приведена справочная информация о директории .dbt:

• Директория .dbt — это скрытая папка в корне вашей файловой системы. Она используется для хранения конфигурационных файлов dbt. Префикс . делает папку скрытой, поэтому по умолчанию она не отображается в Finder или File Explorer.
• Чтобы увидеть скрытые файлы и папки, нажмите Command + Shift + G на macOS или Ctrl + Shift + G на Windows. Это откроет диалог «Go to Folder», в котором можно перейти к директории .dbt.

Создать каталог .dbt

1. Клонируйте репозиторий вашего проекта dbt на локальный компьютер.
2. Используйте команду mkdir, указав после неё имя папки, которую хотите создать.

• Если вы используете macOS, добавьте префикс ~, чтобы создать папку .dbt в корне вашей файловой системы:
  • macOS: mkdir ~/.dbt
  • Windows: mkdir %USERPROFILE%\.dbt

Переместить файл dbt_cloud.yml

Вы можете переместить файл dbt_cloud.yml в директорию .dbt, используя команду mv, либо просто перетащить файл мышью в папку .dbt, открыв папку Downloads через диалог «Go to Folder» и воспользовавшись drag-and-drop в интерфейсе.

Чтобы переместить файл с помощью терминала, используйте команду mv (или move в Windows). Эта команда перемещает dbt_cloud.yml из папки Downloads в папку .dbt. Если файл dbt_cloud.yml находится в другом месте, скорректируйте путь соответствующим образом.

Mac или Linux

В командной строке используйте команду mv, чтобы переместить файл dbt_cloud.yml в директорию .dbt. Если вы только что скачали файл dbt_cloud.yml и он находится в папке Downloads, команда может выглядеть так:

mv ~/Downloads/dbt_cloud.yml ~/.dbt/dbt_cloud.yml

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

Windows

В командной строке используйте команду move. Если предположить, что файл находится в папке Downloads, команда может выглядеть следующим образом:

move %USERPROFILE%\Downloads\dbt_cloud.yml %USERPROFILE%\.dbt\dbt_cloud.yml

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

 Как отключить скачивание артефактов

По умолчанию dbt platform CLI скачивает все артефакты при выполнении команд dbt. Чтобы отключить скачивание этих файлов, добавьте --download-artifacts=false к команде, которую хотите выполнить. Это может ускорить выполнение, но способно нарушить рабочие процессы, зависящие от таких ресурсов, как manifest.

 Что делать при ошибке `Session occupied` в dbt platform CLI?

Если вы получаете ошибку Session occupied в dbt platform CLI или сеанс выполняется слишком долго, вы можете использовать команду dbt invocation list в отдельном окне терминала, чтобы просмотреть состояние активного сеанса. Это поможет разобраться в проблеме и определить аргументы, из-за которых сеанс выполняется слишком долго.

Чтобы отменить активный сеанс, используйте сочетание клавиш Ctrl + Z.

Подробнее о команде dbt invocation см. в справочнике по команде dbt invocation.

Вы также можете повторно подключиться к существующему сеансу с помощью dbt reattach, затем нажать Control-C и выбрать отмену вызова.

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

Создать GitHub Issue