Пакеты
Программисты часто модульно организуют код в библиотеки. Эти библиотеки помогают программистам работать более эффективно: они могут тратить больше времени на уникальную бизнес-логику и меньше времени на реализацию кода, который кто-то другой уже довел до совершенства.
В dbt такие библиотеки называются пакетами. Пакеты dbt настолько мощные, потому что многие аналитические проблемы, с которыми мы сталкиваемся, общие для разных организаций, например:
- преобразование данных из структурированного SaaS-набора данных, например:
- преобразование просмотров страниц Snowplow или Segment в сессии
- преобразование данных о расходах AdWords или Facebook Ads в единый формат.
- написание макросов dbt, выполняющих аналогичные функции, например:
- генерация SQL для объединения двух отношений, поворота столбцов или создания surrogate key
- создание пользовательских тестов схем
- написание аудиторских запросов
- создание моделей и макросов для конкретного инструмента, используемого в вашем стеке данных, например:
Пакеты dbt на самом деле являются автономными проектами dbt, с моделями, макросами и другими ресурсами, которые решают конкретную проблему. Как пользователь dbt, добавляя пакет в свой проект, все ресурсы пакета станут частью вашего собственного проекта. Это означает:
- Модели в пакете будут материализованы, когда вы выполните
dbt run. - Вы можете использовать
refв своих моделях для ссылки на модели из пакета. - Вы можете использовать
sourceдля ссылки на источники в пакете. - Вы можете использовать макросы из пакета в своем собственном проекте.
- Важно отметить, что определение и установка пакетов dbt отличается от определения и установки пакетов Python.
Варианты использования
Следующая настройка подойдет для любого dbt-проекта:
- Добавьте зависимости от пакетов в
packages.yml - Добавьте зависимости от проектов в
dependencies.yml
Однако, возможно, вы сможете объединить всё в один файл dependencies.yml. Прочитайте следующий раздел, чтобы узнать больше.
О packages.yml и dependencies.yml
Файл dependencies.yml может содержать оба типа зависимостей: зависимости от пакетов ("package") и от проектов ("project").
- Зависимости от пакетов позволяют добавлять в ваш проект исходный код из dbt-проекта другого автора — как библиотеку.
- Зависимости от проектов (project dependencies) предоставляют другой способ строить решения поверх чужой работы в dbt.
Если вашему dbt-проекту не требуется использовать Jinja в спецификациях пакетов, вы можете просто переименовать существующий packages.yml в dependencies.yml. Однако важно учитывать: если спецификации пакетов в вашем проекте используют Jinja (особенно в сценариях вроде добавления переменной окружения или метода Git token method в спецификации приватного Git-пакета), стоит продолжать использовать имя файла packages.yml.
Используйте переключатели ниже, чтобы понять различия и решить, когда использовать dependencies.yml или packages.yml (или оба). Подробнее см. FAQ.
Как создать пакет?
Создание пакетов — это продвинутый сценарий использования dbt, однако на практике это может быть относительно простой задачей. Единственное строгое требование — наличие файла dbt_project.yml.
Наиболее распространённые сценарии использования пакетов:
- Распространение models для повторного использования в нескольких проектах.
- Распространение macros для повторного использования в нескольких проектах.
Обратите внимание, что пакеты могут быть приватными — их не обязательно публиковать в открытом доступе. Приватные пакеты можно размещать в собственном Git‑провайдере (например, GitHub или GitLab).
Инструкции по созданию пакетов dbt и дополнительную информацию вы найдёте в нашем руководстве Building dbt packages.
Как добавить пакет в проект?
- Добавьте в ваш dbt‑проект файл с именем
dependencies.ymlилиpackages.yml. Он должен находиться на том же уровне, что и файлdbt_project.yml. - Укажите пакет(ы), которые вы хотите добавить, используя один из поддерживаемых синтаксисов, например:
packages:
- package: dbt-labs/snowplow
version: 0.7.0
- git: "https://github.com/dbt-labs/dbt-utils.git"
revision: 0.9.2
- local: /opt/dbt/redshift
По умолчанию packages-install-path — это dbt_packages.
- Запустите
dbt deps, чтобы установить пакет(ы). Пакеты устанавливаются в директориюdbt_packages— по умолчанию эта директория игнорируется git, чтобы избежать дублирования исходного кода пакета.
Как указать пакет?
Вы можете указать пакет, используя один из следующих методов, в зависимости от того, где хранится ваш пакет.
Hub-пакеты (рекомендуется)
dbt Labs предоставляет Package hub, реестр для пакетов dbt, в качестве услуги для сообщества dbt, но не сертифицирует и не подтверждает целостность, работоспособность, эффективность или безопасность любых пакетов. Пожалуйста, прочитайте отказ от ответственности dbt Labs Package перед установкой hub-пакетов.
Вы можете установить доступные hub-пакеты следующим образом:
packages:
- package: dbt-labs/snowplow
version: 0.7.3 # номер версии
Для hub-пакетов требуется указание версии — вы можете найти последний номер релиза на dbt Hub. Поскольку hub-пакеты используют семантическое версионирование, мы рекомендуем закрепить ваш пакет на последней патч-версии из конкретного минорного релиза, например:
packages:
- package: dbt-labs/snowplow
version: [">=0.7.0", "<0.8.0"]
dbt deps "закрепляет" каждый пакет по умолчанию. Подробности см. в разделе "Закрепление пакетов".
По возможности, мы рекомендуем устанавливать пакеты через dbt Hub, так как это позволяет dbt обрабатывать дублирующиеся зависимости. Это полезно в таких ситуациях, как:
- Ваш проект использует как пакеты dbt-utils, так и Snowplow, и пакет Snowplow также использует пакет dbt-utils.
- Ваш проект использует как пакеты Snowplow, так и Stripe, оба из которых используют пакет dbt-utils.
В сравнении, другие методы установки пакетов не могут обрабатывать дублирующийся пакет dbt-utils.
Продвинутые пользователи могут выбрать размещение внутренней версии hub-пакета на основе этого репозитория и установку переменной окружения DBT_PACKAGE_HUB_URL.
Предрелизные версии
Некоторые поддерживающие пакеты могут захотеть выложить предрелизные версии пакетов на dbt Hub, чтобы протестировать новую функциональность или совместимость с новой версией dbt. Предрелизная версия обозначается суффиксом, таким как a1 (первая альфа), b2 (вторая бета) или rc3 (третий кандидат на релиз).
По умолчанию, dbt deps не будет включать предрелизные версии при разрешении зависимостей пакетов. Вы можете включить установку предрелизов одним из двух способов:
- Явно указав предрелизную версию в ваших критериях
version - Установив
install_prereleaseвtrueи предоставив совместимый диапазон версий
Например, обе следующие конфигурации успешно установят 0.4.5-a2 для dbt_artifacts пакета:
packages:
- package: brooklyn-data/dbt_artifacts
version: 0.4.5-a2
packages:
- package: brooklyn-data/dbt_artifacts
version: [">=0.4.4", "<0.4.6"]
install_prerelease: true
Git-пакеты
Пакеты, хранящиеся на Git-сервере, могут быть установлены с использованием синтаксиса git, например:
packages:
- git: "https://github.com/dbt-labs/dbt-utils.git" # git URL
revision: 0.9.2 # имя тега или ветки
Добавьте URL для пакета с помощью <Constant name="git" /> и при необходимости укажите ревизию. Ревизией может быть:
- имя ветки
- тег релиза
- конкретный коммит (полный 40-символьный хэш)
Пример ревизии, указывающей 40-символьный хэш:
packages:
- git: "https://github.com/dbt-labs/dbt-utils.git"
revision: 4e28d6da126e2940d17f697de783a717f2503188
По умолчанию, dbt deps "закрепляет" каждый пакет. Подробности см. в разделе "Закрепление пакетов".
URL tarball, размещённый во внутренней инфраструктуре
В некоторых организациях существуют требования безопасности, согласно которым загрузка ресурсов допускается только из внутренних сервисов. Чтобы удовлетворить потребность в установке пакетов из размещённых сред, таких как Artifactory или облачные хранилища (cloud storage buckets), dbt Core позволяет устанавливать пакеты из tarball-файлов, доступных по URL и размещённых во внутренней инфраструктуре.
Некоторые организации имеют требования безопасности, чтобы загружать ресурсы только из внутренних сервисов. Чтобы удовлетворить необходимость установки пакетов из размещенных сред, таких как Artifactory или облачные хранилища, dbt Core позволяет устанавливать пакеты из внутренне размещенных URL-адресов tarball.
packages:
- tarball: https://codeload.github.com/dbt-labs/dbt-utils/tar.gz/0.9.6
name: 'dbt_utils'
Где name: 'dbt_utils' указывает подпапку dbt_packages, которая создается для установки исходного кода пакета.
Приватные пакеты
Нативные приватные пакеты Beta
dbt поддерживает приватные пакеты из поддерживаемых репозиториев Git, используя уже существующую конфигурацию в вашем окружении. Ранее для получения пакетов из приватных репозиториев требовалось настраивать токен.
Предварительные условия
- У вас должен быть включён соответствующий feature flag. Чтобы запросить доступ, обратитесь к вашей аккаунт-команде.
- Для использования нативных приватных пакетов у вас должен быть настроен один из следующих провайдеров Git в разделе Integrations в Account settings:
- GitHub
- Azure DevOps
- Приватные пакеты работают только в рамках одного проекта Azure DevOps. Если ваши репозитории находятся в разных проектах внутри одной организации, в настоящий момент вы не сможете ссылаться на них с помощью ключа
private. - Для Azure DevOps используйте путь вида
org/repo(а неorg_name/project_name/repo_name), при этом уровень проекта наследуется от подключённого исходного репозитория.
- Приватные пакеты работают только в рамках одного проекта Azure DevOps. Если ваши репозитории находятся в разных проектах внутри одной организации, в настоящий момент вы не сможете ссылаться на них с помощью ключа
- Gitlab
- Каждый репозиторий Gitlab с приватными пакетами также должен быть проектом dbt.
Configuration
Используйте ключ private в файле packages.yml или dependencies.yml, чтобы клонировать репозитории пакетов через уже настроенную интеграцию dbt с Git — без необходимости создавать access token или настраивать переменную окружения dbt.
packages:
- private: dbt-labs/awesome_repo # your-org/your-repo path
- package: normal packages
[...]
- В настоящее время приватные пакеты работают только в том случае, если репозиторий пакета находится в том же проекте Azure DevOps, что и исходный репозиторий.
- В ключе
privateнеобходимо использовать путь форматаorg/repo(а не стандартный для ADO путьorg_name/project_name/repo_name). - Репозитории, расположенные в разных проектах Azure DevOps, в данный момент не поддерживаются и будут доступны только в одном из будущих обновлений.
Вы можете использовать приватные пакеты, указав org/repo в ключе private:
packages:
- private: my-org/my-repo # Works if your ADO source repo and package repo are in the same project
Вы можете закреплять версии приватных пакетов так же, как и у обычных пакетов dbt:
packages:
- private: dbt-labs/awesome_repo
revision: "0.9.5" # Закрепить на теге, ветке или полном 40-символьном хэше коммита
Если вы используете несколько интеграций Git или используете движок dbt Fusion, добавьте ключ провайдера:
packages:
- private: dbt-labs/awesome_repo
provider: "github" # В настоящее время поддерживаются GitHub и Azure. Поддержка GitLab скоро появится.
С помощью этого метода вы можете получать приватные пакеты из интегрированного провайдера Git без каких‑либо дополнительных шагов по подключению.
Использование provider вместе с Fusion предполагает, что на вашей машине настроен SSH‑ключ, который будет использоваться для клонирования репозиториев git.
Метод SSH-ключа (только командная строка)
Если вы используете командную строку, приватные пакеты могут быть клонированы через SSH и SSH-ключ.
Когда вы используете SSH-ключи для аутентификации на вашем удаленном сервере git, вам не нужно вводить ваше имя пользователя и пароль каждый раз. Подробнее о SSH-ключах, как их сгенерировать и как добавить их в ваш git-провайдер, читайте здесь: Github и GitLab.
packages:
- git: "git@github.com:dbt-labs/dbt-utils.git" # git SSH URL
Если вы используете dbt platform, метод с SSH‑ключом работать не будет, но вы можете использовать метод HTTPS с Git‑токеном.
Метод Git-токена
dbt имеет нативную поддержку приватных пакетов Git, размещённых в GitHub и Azure DevOps (поддержка GitLab появится в ближайшее время). Если вы используете поддерживаемую интегрированную среду Git, вам больше не нужно настраивать токены Git для получения приватных пакетов.
Этот метод позволяет пользователю клонировать через HTTPS, передавая git-токен через переменную окружения. Будьте осторожны с датой истечения срока действия любого токена, который вы используете, так как истекший токен может привести к сбою запланированного запуска. Кроме того, пользовательские токены могут создать проблему, если пользователь когда-либо потеряет доступ к конкретному репозиторию.
Если вы используете dbt, необходимо соблюдать соглашения об именовании переменных окружения. Переменные окружения в dbt должны иметь префикс DBT_ или DBT_ENV_SECRET. Ключи переменных окружения пишутся в верхнем регистре и чувствительны к регистру. При обращении к {{env_var('DBT_KEY')}} в коде вашего проекта ключ должен точно совпадать с переменной, определённой в интерфейсе dbt.
:::
В GitHub:
packages:
# используйте этот формат при доступе к вашему репозиторию через токен приложения github
- git: "https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/dbt-labs/awesome_repo.git" # git HTTPS URL
# используйте этот формат при доступе к вашему репозиторию через классический личный токен доступа
- git: "https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/dbt-labs/awesome_repo.git" # git HTTPS URL
# используйте этот формат при доступе к вашему репозиторию через личный токен доступа с тонкой настройкой (иногда требуется имя пользователя)
- git: "https://GITHUB_USERNAME:{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/dbt-labs/awesome_repo.git" # git HTTPS URL
Подробнее о создании личного токена доступа GitHub читайте здесь. Вы также можете использовать токен установки приложения GitHub здесь.
В GitLab:
packages:
- git: "https://{{env_var('DBT_USER_NAME')}}:{{env_var('DBT_ENV_SECRET_DEPLOY_TOKEN')}}@gitlab.example.com/dbt-labs/awesome_project.git" # git HTTPS URL
Подробнее о создании токена развертывания GitLab читайте здесь и о том, как правильно построить ваш HTTPS URL здесь. Токены развертывания могут управляться только Мейнтейнерами.
В Azure DevOps:
packages:
- git: "https://{{env_var('DBT_ENV_SECRET_PERSONAL_ACCESS_TOKEN')}}@dev.azure.com/dbt-labs/awesome_project/_git/awesome_repo" # git HTTPS URL
Подробнее о создании личного токена доступа читайте здесь.
В Bitbucket:
packages:
- git: "https://{{env_var('DBT_USER_NAME')}}:{{env_var('DBT_ENV_SECRET_PERSONAL_ACCESS_TOKEN')}}@bitbucketserver.com/scm/awesome_project/awesome_repo.git" # для Bitbucket Server
Подробнее о создании личного токена доступа читайте здесь.
Настройка подкаталога для упакованных проектов
В общем случае, dbt ожидает, что dbt_project.yml будет расположен как файл верхнего уровня в пакете. Если упакованный проект вместо этого вложен в подкаталог — возможно, в рамках гораздо большего монорепозитория — вы можете опционально указать путь к папке как subdirectory. dbt попытается выполнить разреженную проверку только файлов, расположенных в этом подкаталоге. Обратите внимание, что вы должны использовать недавнюю версию git (>=2.26.0).
packages:
- git: "https://github.com/dbt-labs/dbt-labs-experimental-features" # git URL
subdirectory: "materialized-views" # имя подкаталога, содержащего `dbt_project.yml`
Local packages
«Локальный» пакет — это dbt‑проект, доступный из вашей локальной файловой системы. Такие пакеты лучше всего подходят для случаев, когда у вас есть общий набор моделей и макросов, который вы хотите использовать в нескольких downstream‑проектах dbt (при этом каждый downstream‑проект всё равно имеет свои собственные уникальные модели, макросы и т.д.).
Вы можете устанавливать локальные пакеты, указав путь к проекту. Лучше всего это работает, когда проект размещён во вложенном подкаталоге относительно директории вашего текущего проекта.
packages:
- local: relative/path/to/subdirectory
Другие шаблоны могут работать в некоторых случаях, но не всегда. Например, если вы установите этот проект как пакет в другом месте или попытаетесь запустить его на другой системе, относительные и абсолютные пути дадут одинаковые результаты.
packages:
# не рекомендуется - поддержка этих шаблонов варьируется
- local: /../../redshift # относительный путь к родительскому каталогу
- local: /opt/dbt/redshift # абсолютный путь на системе
Существуют несколько конкретных случаев использования, когда мы рекомендуем использовать "локальный" пакет:
- Монорепозиторий — Когда у вас есть несколько проектов, каждый вложен в подкаталог, в рамках монорепозитория. "Локальные" пакеты позволяют объединять проекты для координированной разработки и развертывания.
- Тестирование изменений — Чтобы протестировать изменения в одном проекте или пакете в контексте нисходящего проекта или пакета, который его использует. Временно переключив установку на "локальный" пакет, вы можете вносить изменения в первый и сразу тестировать их во втором для более быстрой итерации. Это похоже на редактируемые установки в Python.
- Вложенный проект — Когда у вас есть вложенный проект, который определяет фикстуры и тесты для проекта утилитарных макросов, как интеграционные тесты в пакете
dbt-utils.
Какие пакеты доступны?
Чтобы посмотреть библиотеку опубликованных пакетов dbt, загляните в dbt package hub!
Совместимость пакетов с Fusion
Чтобы определить, совместим ли пакет с dbt Fusion Engine, посетите dbt package hub и найдите бейдж совместимости с Fusion, либо изучите конфигурацию пакета require-dbt-version.
-
Пакеты с
require-dbt-version, который равен2.0.0или включает его, совместимы с Fusion. Например:require-dbt-version: ">=1.10.0,<3.0.0".Даже если пакет не отражает совместимость в package hub, он всё равно может работать с Fusion. Рекомендуется взаимодействовать с мейнтейнерами пакета, чтобы отслеживать обновления, и тщательно тестировать пакеты, совместимость которых не очевидна, перед развертыванием.
-
Мейнтейнеры пакетов, которые хотят сделать свой пакет совместимым с Fusion, могут обратиться к руководству по обновлению пакетов для Fusion с подробными инструкциями.
Особенности пакетов Fivetran:
- Пакеты Fivetran
sourceиtransformationбыли объединены в один пакет. - Если вы устанавливали source-пакеты вручную, например
fivetran/github_source, необходимо убедиться, что установленfivetran/github, и отключить модели трансформации.
Сообщения о совместимости пакетов
dbt-autofixПредупреждения Fusion и логи dbt-autofix могут содержать разные сообщения о совместимости пакетов.
Если вы используете dbt-autofix при обновлении до Fusion в Studio IDE или в расширении dbt для VS Code, вы можете увидеть различающиеся сообщения о совместимости пакетов между dbt-autofix и предупреждениями Fusion.
Вот почему это происходит:
- Предупреждения Fusion формируются на основе параметра пакета
require-dbt-versionи того, содержит лиrequire-dbt-versionверсию2.0.0. - Некоторые пакеты уже совместимы с Fusion, даже если их мейнтейнеры ещё не обновили значение
require-dbt-version. dbt-autofixзнает о таких совместимых пакетах и не пытается обновлять пакет, если он уже считается совместимым.
Это означает, что даже если вы видите предупреждение Fusion для пакета, который dbt-autofix определяет как совместимый, вам не нужно менять этот пакет.
Расхождение в сообщениях является временным и будет устранено по мере внедрения и распространения улучшенного механизма определения совместимости из dbt-autofix в предупреждениях Fusion.
Ниже приведён пример предупреждения Fusion в Studio IDE, которое сообщает, что пакет не совместим с Fusion, тогда как dbt-autofix указывает, что он совместим:
dbt1065: Package 'dbt_utils' requires dbt version [>=1.30,<2.0.0], but current version is 2.0.0-preview.72. This package may not be compatible with your dbt version. dbt(1065) [Ln 1, Col 1]
Удаление пакета
Когда вы удаляете пакет из вашего файла packages.yml, он не удаляется автоматически из вашего проекта dbt, так как он все еще существует в вашей директории dbt_packages/. Если вы хотите полностью удалить пакет, вам следует либо:
- удалить директорию пакета в
dbt_packages/; или - запустить
dbt clean, чтобы удалить все пакеты (и любые скомпилированные модели), а затемdbt deps.
Закрепление пакетов
Начиная с версии v1.7, выполнение dbt deps "закрепляет" каждый пакет, создавая или обновляя файл package-lock.yml в корне проекта, где записан packages.yml.
Запуск dbt deps «закрепляет» каждую зависимость, создавая или обновляя файл package-lock.yml в project_root, где расположен packages.yml.
Например, если вы используете имя ветки, файл package-lock.yml закрепляет на коммите head. Если вы используете диапазон версий, он закрепляет на последнем релизе. В любом случае, последующие коммиты или версии не будут установлены. Чтобы получить новые коммиты или версии, выполните dbt deps --upgrade или добавьте package-lock.yml в ваш .gitignore файл.
Начиная с версии v0.14.0, dbt предупредит вас, если вы установите пакет, используя синтаксис git, без указания ревизии (см. ниже).
dbt выдаст предупреждение, если вы устанавливаете пакет, используя синтаксис git, не указав ревизию (см. ниже).
Configuring packages
Вы можете настраивать модели и seeds в пакете из файла dbt_project.yml, например:
vars:
snowplow:
'snowplow:timezone': 'America/New_York'
'snowplow:page_ping_frequency': 10
'snowplow:events': "{{ ref('sp_base_events') }}"
'snowplow:context:web_page': "{{ ref('sp_base_web_page_context') }}"
'snowplow:context:performance_timing': false
'snowplow:context:useragent': false
'snowplow:pass_through_columns': []
models:
snowplow:
+schema: snowplow
seeds:
snowplow:
+schema: snowplow_seeds
Например, при использовании пакета, специфичного для набора данных, вам может потребоваться настроить переменные для имен таблиц, содержащих ваши необработанные данные.
Конфигурации, заданные в YAML-файле вашего проекта (dbt_project.yml), будут переопределять любые конфигурации в пакете (как в YAML-файле проекта самого пакета, так и в блоках config).
Указание незафиксированных Git-пакетов
Если в вашем проекте указан «незафиксированный» пакет Git, вы можете увидеть предупреждение вида:
Git-пакет "https://github.com/dbt-labs/dbt-utils.git" не закреплен.
Это может привести к внесению изменений, нарушающих работу вашего проекта, без предупреждения!
Это предупреждение можно отключить, установив warn-unpinned: false в спецификации пакета. Примечание: Это не рекомендуется.
packages:
- git: https://github.com/dbt-labs/dbt-utils.git
warn-unpinned: false