Перейти к основному содержимому

Пакеты

Программисты часто модульно организуют код в библиотеки. Эти библиотеки помогают программистам работать более эффективно: они могут тратить больше времени на уникальную бизнес-логику и меньше времени на реализацию кода, который кто-то другой уже довел до совершенства.

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

  • преобразование данных из структурированного SaaS-набора данных, например:
    • преобразование просмотров страниц Snowplow или Segment в сессии
    • преобразование данных о расходах AdWords или Facebook Ads в единый формат.
  • написание макросов dbt, выполняющих аналогичные функции, например:
  • создание моделей и макросов для конкретного инструмента, используемого в вашем стеке данных, например:
    • Модели для понимания привилегий Redshift.
    • Макросы для работы с данными, загруженными Stitch.

Пакеты dbt на самом деле являются автономными проектами dbt, с моделями, макросами и другими ресурсами, которые решают конкретную проблему. Как пользователь dbt, добавляя пакет в свой проект, все ресурсы пакета станут частью вашего собственного проекта. Это означает:

  • Модели в пакете будут материализованы, когда вы выполните dbt run.
  • Вы можете использовать ref в своих моделях для ссылки на модели из пакета.
  • Вы можете использовать source для ссылки на источники в пакете.
  • Вы можете использовать макросы из пакета в своем собственном проекте.
  • Важно отметить, что определение и установка пакетов dbt отличается от определения и установки пакетов Python.

Примеры использования​

Следующая настройка будет работать для каждого проекта dbt:

Однако, вы можете объединить оба файла в один dependencies.yml. Прочтите следующий раздел, чтобы узнать больше.

О файлах packages.yml и dependencies.yml​

Файл dependencies.yml может содержать оба типа зависимостей: "зависимости пакетов" и "зависимости проектов".

  • Зависимости пакетов позволяют добавлять исходный код из чужого проекта dbt в ваш собственный, как библиотеку.
  • Зависимости проектов предоставляют другой способ использовать наработки других в dbt.

Если вашему проекту dbt не требуется использование Jinja в спецификациях пакетов, вы можете просто переименовать ваш существующий packages.yml в dependencies.yml. Однако, стоит отметить, что если спецификации пакетов вашего проекта используют Jinja, особенно в сценариях, таких как добавление переменной окружения или метод Git-токена в спецификации частного Git-пакета, вам следует продолжать использовать имя файла packages.yml.

Используйте следующие переключатели, чтобы понять различия и определить, когда использовать dependencies.yml или packages.yml (или оба). Обратитесь к Часто задаваемым вопросам для получения дополнительной информации.

 Когда использовать зависимости проекта
 Когда использовать зависимости пакетов

Как добавить пакет в мой проект?​

  1. Добавьте файл с именем dependencies.yml или packages.yml в ваш проект dbt. Он должен находиться на том же уровне, что и ваш файл dbt_project.yml.
  2. Укажите пакет(ы), которые вы хотите добавить, используя один из поддерживаемых синтаксисов, например:
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.

  1. Запустите dbt deps, чтобы установить пакет(ы). Пакеты устанавливаются в директорию dbt_packages — по умолчанию эта директория игнорируется git, чтобы избежать дублирования исходного кода пакета.

Как указать пакет?​

Вы можете указать пакет, используя один из следующих методов, в зависимости от того, где хранится ваш пакет.

Hub-пакеты (рекомендуется)​

dbt Labs предоставляет Package hub, реестр для пакетов dbt, в качестве услуги для сообщества dbt, но не сертифицирует и не подтверждает целостность, работоспособность, эффективность или безопасность любых пакетов. Пожалуйста, прочитайте отказ от ответственности dbt Labs Package перед установкой hub-пакетов.

Вы можете установить доступные hub-пакеты следующим образом:

packages.yml
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.yml
packages:
  - git: "https://github.com/dbt-labs/dbt-utils.git" # git URL
    revision: 0.9.2 # имя тега или ветки

Добавьте Git URL для пакета и, при необходимости, укажите ревизию. Ревизия может быть:

  • именем ветки
  • тегированным релизом
  • конкретным коммитом (полный 40-символьный хэш)

Пример ревизии, указывающей 40-символьный хэш:

packages:
  - git: "https://github.com/dbt-labs/dbt-utils.git"
    revision: 4e28d6da126e2940d17f697de783a717f2503188

По умолчанию, dbt deps "закрепляет" каждый пакет. Подробности см. в разделе "Закрепление пакетов".

Внутренне размещенный URL-адрес tarball​

Некоторые организации имеют требования безопасности, чтобы загружать ресурсы только из внутренних сервисов. Чтобы удовлетворить необходимость установки пакетов из размещенных сред, таких как 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 Cloud поддерживает использование приватных пакетов из поддерживаемых Git-репозиториев, используя уже существующую конфигурацию в вашей среде. Ранее вам нужно было настроить токен для получения пакетов из ваших приватных репозиториев.

Предварительные условия​

Чтобы использовать нативные приватные пакеты, вы должны иметь одного из следующих Git-провайдеров, настроенных в разделе Интеграции ваших Настроек аккаунта:

Конфигурация​

Используйте ключ private в вашем packages.yml или dependencies.yml, чтобы клонировать репозитории пакетов, используя вашу существующую интеграцию dbt Cloud Git, без необходимости предоставления токена доступа или создания переменной окружения dbt Cloud:

packages.yml
packages:
  - private: dbt-labs/awesome_repo
  - package: normal packages

	[...]

Вы можете закрепить приватные пакеты аналогично обычным пакетам dbt:

packages:
  - private: dbt-labs/awesome_repo
    revision: "0.9.5" # Закрепить на теге, ветке или полном 40-символьном хэше коммита

Если вы используете несколько Git-интеграций, уточните, добавив ключ провайдера:

packages:
  - private: dbt-labs/awesome_repo
    provider: "github" # В настоящее время поддерживаются GitHub и Azure. Поддержка GitLab скоро появится.

С помощью этого метода вы можете получать приватные пакеты от интегрированного Git-провайдера без дополнительных шагов для подключения.

Метод SSH-ключа (только командная строка)​

Если вы используете командную строку, приватные пакеты могут быть клонированы через SSH и SSH-ключ.

Когда вы используете SSH-ключи для аутентификации на вашем удаленном сервере git, вам не нужно вводить ваше имя пользователя и пароль каждый раз. Подробнее о SSH-ключах, как их сгенерировать и как добавить их в ваш git-провайдер, читайте здесь: Github и GitLab.

packages.yml
packages:
  - git: "git@github.com:dbt-labs/dbt-utils.git" # git SSH URL

Если вы используете dbt Cloud, метод SSH-ключа не будет работать, но вы можете использовать метод HTTPS Git Token.

Метод Git-токена​

примечание

dbt Cloud имеет нативную поддержку для размещенных в Git приватных пакетов с GitHub и Azure DevOps (GitLab скоро появится). Если вы используете поддерживаемую интегрированную Git-среду, вам больше не нужно настраивать Git-токены для получения приватных пакетов.

Этот метод позволяет пользователю клонировать через HTTPS, передавая git-токен через переменную окружения. Будьте осторожны с датой истечения срока действия любого токена, который вы используете, так как истекший токен может привести к сбою запланированного запуска. Кроме того, пользовательские токены могут создать проблему, если пользователь когда-либо потеряет доступ к конкретному репозиторию.

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

Если вы используете dbt Cloud, вы должны соблюдать соглашения об именах для переменных окружения. Переменные окружения в dbt Cloud должны иметь префикс DBT_ или DBT_ENV_SECRET. Ключи переменных окружения пишутся заглавными буквами и чувствительны к регистру. При ссылке на {{env_var('DBT_KEY')}} в коде вашего проекта, ключ должен точно соответствовать переменной, определенной в интерфейсе dbt Cloud.

В GitHub:

packages.yml
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.yml
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.yml
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.yml
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.yml
packages:
  - git: "https://github.com/dbt-labs/dbt-labs-experimental-features" # git URL
    subdirectory: "materialized-views" # имя подкаталога, содержащего `dbt_project.yml`

Локальные пакеты​

"Локальный" пакет — это проект dbt, доступный из вашей локальной файловой системы. Вы можете установить его, указав путь к проекту. Это работает лучше всего, когда вы вкладываете проект в подкаталог относительно директории вашего текущего проекта.

packages.yml
packages:
  - local: relative/path/to/subdirectory

Другие шаблоны могут работать в некоторых случаях, но не всегда. Например, если вы установите этот проект как пакет в другом месте или попытаетесь запустить его на другой системе, относительные и абсолютные пути дадут одинаковые результаты.

packages.yml
packages:
  # не рекомендуется - поддержка этих шаблонов варьируется
  - local: /../../redshift   # относительный путь к родительскому каталогу
  - local: /opt/dbt/redshift # абсолютный путь на системе

Существуют несколько конкретных случаев использования, когда мы рекомендуем использовать "локальный" пакет:

  1. Монорепозиторий — Когда у вас есть несколько проектов, каждый вложен в подкаталог, в рамках монорепозитория. "Локальные" пакеты позволяют объединять проекты для координированной разработки и развертывания.
  2. Тестирование изменений — Чтобы протестировать изменения в одном проекте или пакете в контексте нисходящего проекта или пакета, который его использует. Временно переключив установку на "локальный" пакет, вы можете вносить изменения в первый и сразу тестировать их во втором для более быстрой итерации. Это похоже на редактируемые установки в Python.
  3. Вложенный проект — Когда у вас есть вложенный проект, который определяет фикстуры и тесты для проекта утилитарных макросов, как интеграционные тесты в пакете dbt-utils.

Какие пакеты доступны?​

Посмотрите dbt Hub, чтобы увидеть библиотеку опубликованных пакетов dbt!

Расширенная конфигурация пакетов​

Обновление пакета​

Когда вы обновляете версию или ревизию в вашем файле packages.yml, она не обновляется автоматически в вашем проекте dbt. Вам следует запустить dbt deps, чтобы обновить пакет. Возможно, вам также потребуется выполнить полное обновление моделей в этом пакете.

Удаление пакета​

Когда вы удаляете пакет из вашего файла packages.yml, он не удаляется автоматически из вашего проекта dbt, так как он все еще существует в вашей директории dbt_packages/. Если вы хотите полностью удалить пакет, вам следует либо:

  • удалить директорию пакета в dbt_packages/; или
  • запустить dbt clean, чтобы удалить все пакеты (и любые скомпилированные модели), а затем dbt deps.

Закрепление пакетов​

Начиная с версии v1.7, выполнение dbt deps "закрепляет" каждый пакет, создавая или обновляя файл package-lock.yml в корне проекта, где записан packages.yml.

  • Файл package-lock.yml содержит запись обо всех установленных пакетах.
  • Если последующие запуски dbt deps не содержат изменений в dependencies.yml или packages.yml, dbt-core устанавливает из package-lock.yml.

Например, если вы используете имя ветки, файл package-lock.yml закрепляет на коммите head. Если вы используете диапазон версий, он закрепляет на последнем релизе. В любом случае, последующие коммиты или версии не будут установлены. Чтобы получить новые коммиты или версии, выполните dbt deps --upgrade или добавьте package-lock.yml в ваш .gitignore файл.

Начиная с версии v0.14.0, dbt предупредит вас, если вы установите пакет, используя синтаксис git, без указания ревизии (см. ниже).

Конфигурирование пакетов​

Вы можете настроить модели и семена в пакете из файла dbt_project.yml, например:

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

Например, при использовании пакета, специфичного для набора данных, вам может потребоваться настроить переменные для имен таблиц, содержащих ваши необработанные данные.

Конфигурации, сделанные в вашем файле dbt_project.yml, переопределят любые конфигурации в пакете (либо в файле dbt_project.yml пакета, либо в блоках конфигурации).

Указание незакрепленных Git-пакетов​

Если ваш проект указывает "незакрепленный" Git-пакет, вы можете увидеть предупреждение, например:

Git-пакет "https://github.com/dbt-labs/dbt-utils.git" не закреплен.
Это может привести к внесению изменений, нарушающих работу вашего проекта, без предупреждения!

Это предупреждение можно отключить, установив warn-unpinned: false в спецификации пакета. Примечание: Это не рекомендуется.

packages.yml
packages:
  - git: https://github.com/dbt-labs/dbt-utils.git
    warn-unpinned: false

Установка двухчастных версий​

В dbt v0.17.0 только, если версия пакета, которую вы хотите, указана только как major.minor, в отличие от major.minor.patch, вы можете получить ошибку, что 1.0 не является строкой. В этом случае вам придется сказать dbt, что ваш номер версии является строкой. Эта проблема была решена в v0.17.1 и всех последующих версиях.

packages.yml
packages:
 - git: https://github.com/dbt-labs/dbt-codegen.git
   version: "{{ 1.0 | as_text }}"
0
Отредактировать эту страницу