Создание пакетов dbt

Обновлен

dbt Core

Advanced

Menu

Введение

Создание пакетов — это продвинутое использование dbt. Если вы новичок в этом инструменте, мы рекомендуем сначала использовать продукт для собственных аналитических нужд, прежде чем пытаться создать пакет для других.

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

Глубокое понимание:

• пакетов
• администрирования репозитория на GitHub
• семантического версионирования

Оцените, является ли пакет правильным решением

Пакеты обычно содержат:

• макросы, которые решают конкретную задачу аналитической инженерии — например, аудит результатов запроса, генерация кода или добавление дополнительных тестов схемы в проект dbt.
• модели для общего набора данных — например, набор данных для программных продуктов, таких как MailChimp или Snowplow, или даже модели для метаданных о вашем стеке данных, таких как расходы на запросы Snowflake и артефакты, созданные dbt run. В общем, должен быть общий набор отраслевых стандартных метрик, которые вы можете моделировать (например, уровень открытия электронной почты).

Пакеты не подходят для обмена моделями, содержащими бизнес-специфичную логику, например, написание кода для атрибуции маркетинга или ежемесячного повторяющегося дохода. Вместо этого рассмотрите возможность публикации блога и ссылки на пример репозитория, а не упаковки этого кода в виде пакета (вот наш блог о атрибуции маркетинга в качестве примера).

Создайте ваш новый проект

Использование командной строки для разработки пакетов

Мы склонны использовать интерфейс командной строки для разработки пакетов. Рабочий процесс разработки часто включает установку локальной копии вашего пакета в другой проект dbt — в настоящее время dbt Cloud не предназначен для этого рабочего процесса.

1. Используйте команду dbt init для создания нового проекта dbt, который станет вашим пакетом:

$ dbt init [package_name]

2. Создайте публичный репозиторий GitHub¹, названный dbt-<package-name>, например, dbt-mailchimp. Следуйте инструкциям GitHub, чтобы связать его с только что созданным проектом dbt.
3. Обновите name: проекта в dbt_project.yml на имя вашего пакета, например, mailchimp.
4. Определите допустимые версии dbt, используя конфигурацию require-dbt-version.

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

Разработайте ваш пакет

Мы рекомендуем авторам пакетов впервые разрабатывать макросы и модели для использования в собственном проекте dbt. Как только ваш новый пакет будет создан, вы можете начать переносить их, внедряя по пути некоторые дополнительные шаблоны проектирования, специфичные для пакета.

При работе над вашим пакетом мы часто находим полезным установить локальную копию пакета в другой проект dbt — этот рабочий процесс описан здесь.

Следуйте лучшим практикам

Только для пакетов моделирования

Используйте наши конвенции кодирования dbt, нашу статью о структурировании наших проектов dbt и наши лучшие практики для всех наших советов о том, как построить ваш проект dbt.

Здесь особенно полезно иметь опыт работы над собственным проектом dbt.

Сделайте местоположение необработанных данных настраиваемым

Только для пакетов моделирования

Не каждый пользователь вашего пакета будет хранить свои данные Mailchimp в схеме с именем mailchimp. Таким образом, вам нужно сделать местоположение необработанных данных настраиваемым.

Мы рекомендуем использовать источники и переменные для достижения этой цели. Ознакомьтесь с этим пакетом для примера — в частности, README включает инструкции о том, как переопределить схему по умолчанию из файла dbt_project.yml.

Установите пакеты upstream с hub.getdbt.com

Если ваш пакет зависит от другого пакета (например, вы используете некоторые из кросс-базовых макросов из dbt-utils), мы рекомендуем установить пакет с hub.getdbt.com, указав диапазон версий следующим образом:

packages.yml

packages:
  - package: dbt-labs/dbt_utils
    version: [">0.6.5", "0.7.0"]

Когда пакеты устанавливаются с hub.getdbt.com, dbt может обрабатывать дублирующиеся зависимости.

Реализуйте кросс-базовую совместимость

Многие функции SQL специфичны для конкретной базы данных. Например, имя функции и порядок аргументов для вычисления разницы между двумя датами варьируются между Redshift, Snowflake и BigQuery, и аналогичной функции не существует в Postgres!

Если вы хотите поддерживать несколько хранилищ, у нас есть несколько приемов:

• Мы написали ряд макросов, которые компилируются в допустимые фрагменты SQL на каждом из оригинальных четырех адаптеров. По возможности используйте эти макросы.
• Если вам нужно реализовать кросс-базовую совместимость для одного из ваших макросов, используйте макрос adapter.dispatch для достижения этой цели. Ознакомьтесь с кросс-базовыми макросами в dbt-utils для примеров.
• Если вы работаете над пакетом моделирования, вы можете заметить, что вам нужно писать разные модели для каждого хранилища (например, если инструмент EL, с которым вы работаете, хранит данные по-разному в каждом хранилище). В этом случае вы можете написать разные версии каждой модели и использовать конфигурацию enabled в сочетании с target.type, чтобы включить правильные модели — ознакомьтесь с этим пакетом в качестве примера.

Если ваш пакет был написан только для работы с одним , убедитесь, что вы документируете это в README вашего пакета.

Используйте специфичные имена моделей

Только для пакетов моделирования

Многие наборы данных имеют концепцию "пользователя", "аккаунта" или "сессии". Чтобы убедиться, что в dbt все однозначно, добавьте префикс [package_name]_ ко всем вашим моделям. Например, mailchimp_campaigns.sql — это хорошее имя для модели, тогда как campaigns.sql — нет.

По умолчанию используйте представления

Только для пакетов моделирования

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

Основное исключение из этого правила — работа с источниками данных, которые выигрывают от инкрементного моделирования (например, просмотры веб-страниц). Реализация инкрементной логики от имени ваших конечных пользователей в этом случае, вероятно, будет полезной.

Тестируйте и документируйте ваш пакет

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

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

Включите полезные артефакты GitHub

Со временем мы разработали набор полезных артефактов GitHub, которые облегчают администрирование наших пакетов. В частности, мы обеспечиваем включение:

• Полезного README, который содержит:
  • инструкции по установке, которые ссылаются на последнюю версию пакета на hub.getdbt.com, и включает любые необходимые конфигурации (пример)
  • Примеры использования для любых макросов (пример)
  • Описания основных моделей, включенных в пакет (пример)
• Шаблоны GitHub, включая шаблоны PR и шаблоны проблем (пример)

Добавьте интеграционные тесты

Опционально

Мы рекомендуем реализовать интеграционные тесты, чтобы подтвердить, что пакет работает как ожидалось — это еще более продвинутый шаг, поэтому вы можете обнаружить, что вам потребуется время, чтобы дойти до этого.

Этот шаблон можно увидеть в большинстве пакетов, включая пакеты audit-helper и snowplow.

Примерный план:

1. Создайте подкаталог с именем integration_tests
2. В этом подкаталоге создайте новый проект dbt — вы можете использовать команду dbt init для этого. Однако наш предпочтительный метод — скопировать файлы из существующего проекта integration_tests, как, например, здесь (удалив содержимое папок macros, models и tests, так как они специфичны для проекта)
3. Установите пакет в подкаталоге integration_tests, используя синтаксис local, а затем запустите dbt deps

packages.yml

packages:
    - local: ../ # это означает "один каталог выше текущего каталога"

4. Добавьте ресурсы в пакет (seeds, модели, тесты), чтобы вы могли успешно запустить ваш проект и сравнить вывод с ожидаемым. Точный подход здесь будет варьироваться в зависимости от ваших пакетов. В общем, вы обнаружите, что вам нужно:

   • Добавить фиктивные данные через seed с несколькими примерами (анонимизированными) записями. Настройте проект integration_tests так, чтобы он указывал на seeds вместо таблиц необработанных данных.
   • Добавить больше seeds, которые представляют ожидаемый вывод ваших моделей, и использовать тест dbt_utils.equality, чтобы подтвердить, что вывод вашего пакета и ожидаемый вывод совпадают.

5. Подтвердите, что вы можете успешно запустить dbt run и dbt test из вашей командной строки.

6. (Опционально) Используйте инструмент CI, такой как CircleCI или GitHub Actions, чтобы автоматизировать запуск вашего проекта dbt при открытии нового Pull Request. Для вдохновения ознакомьтесь с одной из наших конфигураций CircleCI, которая запускает тесты против наших четырех основных хранилищ. Примечание: это продвинутый шаг — если вы идете по этому пути, вам может быть полезно поздороваться в dbt Slack.

Разверните документацию для вашего пакета

Опционально

Сайт документации dbt может помочь потенциальному пользователю вашего пакета понять написанный вами код. Поэтому мы рекомендуем развернуть сайт, сгенерированный dbt docs generate, и ссылаться на развернутый сайт из вашего пакета.

Самый простой способ, который мы нашли для этого, — использовать GitHub Pages.

1. На новой ветке git выполните dbt docs generate. Если у вас настроены интеграционные тесты (выше), используйте проект интеграционных тестов для этого.
2. Переместите следующие файлы в каталог с именем docs (пример): catalog.json, index.html, manifest.json, run_results.json.
3. Объедините эти изменения в основную ветку
4. Включите GitHub Pages в репозитории на вкладке настроек и укажите на подкаталог “docs”
5. GitHub должен затем развернуть документацию по адресу <org-name>.github.io/<repo-name>, например: fivetran.github.io/dbt_ad_reporting

Выпустите ваш пакет

Создайте новый релиз, когда вы будете готовы, чтобы другие могли использовать вашу работу! Обязательно используйте семантическое версионирование при именовании вашего релиза.

В частности, если новые изменения вызовут ошибки у пользователей более ранних версий пакета, обязательно используйте как минимум минорный релиз (например, переходите с 0.1.1 на 0.2.0).

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

Добавьте пакет на hub.getdbt.com

Наш реестр пакетов, hub.getdbt.com, обновляется скриптом hubcap. Чтобы добавить ваш пакет на hub.getdbt.com, создайте PR в репозиторий hubcap, чтобы включить его в файл hub.json.