Итак, вы хотите создать пакет dbt

Пакеты — это самый простой способ для пользователя dbt внести код в сообщество dbt. Это убеждение, которое я поддерживаю как человек, который вносит вклад в пакеты и помог многим партнерам создать свои собственные во время моей работы в dbt Labs.

Причина проста: пакеты, как неотъемлемая часть dbt, следуют нашему принципу создания аналитическими инженерами и для них. Их легко установить, они доступны, и в конце концов, это просто SQL (с добавлением git и jinja). Вы можете либо поделиться своим пакетом с сообществом, либо использовать его среди своих команд в вашей организации.

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

Что такое пакет?

Если вы рассматриваете возможность создания пакета, вы, вероятно, уже знаете, что это такое, но давайте быстро повторим, чтобы структурировать наше мышление. Пакет dbt — это, по сути, мини-проект dbt. Единственный обязательный файл, который он требует, это dbt_project.yml, чтобы подтвердить, что это пакет dbt (так же, как и любой проект dbt). Он может содержать макросы, которые помогают вам писать что-то на SQL в значительно меньшем количестве строк. Он может содержать модели, которые помогают вам моделировать ваш SaaS набор данных за считанные минуты (я смотрю на вас, пакет Fivetran Salesforce). Но в мире dbt вы можете буквально взять один проект (скажем, Jaffle shop) и установить его как пакет в ваш проект, независимо от того, из Hub он или нет.

Пакеты — это способ делиться кодом в dbt, не прибегая к копированию и вставке (или отправке по электронной почте :смайл в ужасе:).

Давайте разберем макрос dateadd из макроса dbt_utils, чтобы показать вам процесс, который создал этот замечательный макрос.

Проблема: Аналитикам часто нужно добавить интервал к временной метке/дате. Чтобы сделать это кросс-базовым и стандартизированным по всему проекту, нужен макрос.

{% macro dateadd(datepart, interval, from_date_or_timestamp) %}

  {{ return(adapter.dispatch('dateadd', 'dbt_utils')(datepart, interval, from_date_or_timestamp)) }}

{% endmacro %}

В этом разделе мы используем dispatch Jinja, чтобы включить правильный макрос из остальной части файла (так как они специфичны для адаптера), когда пользователь вызывает макрос. Это означает, что пользователю не нужно думать о том, что вызывать в зависимости от адаптера, ему нужно просто вызвать один макрос, dbt все обработает за кулисами.

{% macro default__dateadd(datepart, interval, from_date_or_timestamp) %}

    dateadd(

        {{ datepart }},

        {{ interval }},

        {{ from_date_or_timestamp }}

        )

{% endmacro %}

В этом макросе мы предоставляем стандартный способ создания dateadd. Это первый макрос, который будет использоваться, если не требуется специфичный для адаптера.

{% macro bigquery__dateadd(datepart, interval, from_date_or_timestamp) %}

        datetime_add(

            cast( {{ from_date_or_timestamp }} as datetime),

        interval {{ interval }} {{ datepart }}

        )

{% endmacro %}

{% macro postgres__dateadd(datepart, interval, from_date_or_timestamp) %}

    {{ from_date_or_timestamp }} + ((interval '1 {{ datepart }}') * ({{ interval }}))

{% endmacro %}

{# redshift должен использовать default вместо postgres #}

{% macro redshift__dateadd(datepart, interval, from_date_or_timestamp) %}

    {{ return(dbt_utils.default__dateadd(datepart, interval, from_date_or_timestamp)) }}

{% endmacro %}

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

Теперь это было не так уж плохо, верно?

Намерения

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

Технически, у вас есть что-то переиспользуемое, чем вы хотите поделиться. Замечательные вещи, которые подходят под эту категорию, могут выглядеть так:

• Макросы, которые вы очень часто используете для своих проектов: dbt_utils

• Тесты, которые вы находите ценными: dbt_expectations

• Методы для расширения основной функциональности dbt: dbt_artifacts

• Способы выведения трансформаций dbt за рамки: dbt_ml

• Стандартные методы моделирования источника данных SaaS: Salesforce

Я даже написал макрос, который изменяет макрос union_relations для конкретного случая использования (объединение двух массивных таблиц инкрементным образом). Аналитика часто означает, что существует много переиспользуемого кода, как в организациях, так и в вертикалях.

Социально, вы хотите внести вклад в dbt. Используя dbt, вы по сути являетесь частью нашего сообщества с открытым исходным кодом. Это означает, что вы получаете выгоду от вклада сообщества, сделанного теми, кто был до вас, и теми, кто будет после. Так что какой лучший способ выразить свою признательность, чем внести свой вклад в знания, чтобы помочь dbt постоянно улучшаться. Вклады помогают вам подтвердить свою экспертизу в dbt, как для себя, так и для более широкого сообщества. Создание пакета dbt — отличный способ предоставить мнение о том, как использовать dbt. Вы можете помочь определить отраслевые стандарты в проектах, как для себя, так и для сообщества. И все это без необходимости знания Python.

Требования:

Но Эми, ты только что сказала, что любой, кто знает SQL и dbt, может создать пакет.

Я не соврала, но хочу быть конкретной в том, с какими навыками вы хотите быть комфортными или ожидать их развития, создавая свой пакет:

• Высокий уровень знаний SQL

• Понимание git, особенно семантического версионирования и обслуживания git

• Знание dbt (уровень 300, где вы полностью построили проект dbt)

• Владение Jinja

• Использование пакетов dbt в прошлом

• Если вы создаете публичный пакет, высокоуровневое понимание того, как работает open source

Варианты пакетов

Пакеты dbt могут быть разных видов; давайте разберем ваши варианты:

• Публичные vs Приватные

Вообще говоря, мы поощряем вклад в наше сообщество с открытым исходным кодом, поэтому всегда рекомендуем делиться своим пакетом публично. Вы можете разместить свой пакет на нашем Packages Hub, чтобы продемонстрировать его вместе с вашими коллегами-экспертами. Но мы понимаем, что иногда есть знания, которыми вы хотите поделиться более контролируемым образом. Вы можете сделать свой пакет приватным в git, чтобы только те, кому вы предоставили доступ, могли установить пакет в свой проект dbt. Это часто означает включение дополнительных учетных данных во время установки с использованием env_vars.

• Содержание

  • Мы обнаружили, что наши самые популярные пакеты настраиваемы, поэтому имейте в виду, насколько настраиваемым вы хотите быть. Пакеты, содержащие макросы, являются лидерами среди установленных пакетов, но моделирование наборов данных SaaS имеет очень специфическое и все еще полезное пространство. Так что решает ваш пакет? Он будет использоваться на разных платформах или только для Snowflake?

• Документация

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

Как создать пакет

Теперь давайте перейдем к интересной части. Начнем с высокого уровня, как выглядит рабочий процесс?

Рабочий процесс

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

Теперь давайте углубимся в то, что происходит в этом потоке.

Разработка

Здесь вы создаете основу.

1. Начните с создания проекта dbt в Github (вы можете использовать других провайдеров git, если планируете сделать пакет приватным). Все, что нужно включить, это dbt_project.yml, чтобы его можно было установить как пакет.

2. Добавьте содержимое вашего пакета. Это означает ваши модели и макросы. Не забудьте объявить переменные в вашем файле dbt_project.yml, если у вас есть какие-либо специфические конфигурации.

Проходя эти шаги, имейте в виду, насколько настраиваемым вы хотите сделать ваш код. Следует ли ваш код лучшим практикам dbt? Если он кросс-платформенный, учли ли вы различные диалекты SQL? Также, если ваш пакет зависит от существующих пакетов dbt, привязываете ли вы его к определенной версии? Для получения дополнительной информации о разработке вашего пакета, ознакомьтесь с нашим сайтом документации. Если вам нужна помощь от сообщества, канал #packages-ecosystem — отличное место для начала.

Тестирование

После того как вы разработали свой основной код, пришло время добавить интеграционные тесты. Это отличная вещь, потому что она подтверждает ваши предположения и дает вам и любым участникам вашего пакета базовый уровень того, как пакет должен работать. Наш пакет audit-helper имеет отличные кросс-платформенные интеграционные тесты. Обязательно также установите ваш пакет в существующий проект dbt, чтобы подтвердить, что он работает.

Документирование

Мы в dbt Labs твердо убеждены, что хороший код документирован, поэтому обязательно документируйте любые модели или макросы. Обновите Readme с описанием случаев использования пакета, как его использовать и спецификой того, что он содержит. Посмотрите на пакет dbt-expectations как на пример отличной документации. Вы хотите убедиться, что охватили все, что может понадобиться пользователю для использования этого пакета и устранения любых ошибок.

Вклад сообщества

Если вы планируете создать публичный пакет, я настоятельно рекомендую внедрить процесс внесения вклада. Это поможет пользователям вносить вклад в ваш код и продолжать расширять его использование (ура, open source!). Чтобы создать надежный процесс, обязательно включите следующие элементы:

• Шаблоны Pull Request и Шаблоны Issues, чтобы помочь пользователям вносить вклад с руководством. Это предотвращает ненужные переписки и помогает наладить продуктивные разговоры. Это поможет вам помочь пользователям устранять проблемы и поощрять людей вносить вклад в ваш пакет.

• Объявите разумное SLA. Будьте прозрачны в том, как быстро вы можете отвечать на pull requests и issues.

• Определите своих владельцев кода, если у вас несколько сопровождающих, чтобы автоматизировать рецензентов.

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

Публикация

Теперь, когда вся работа сделана, пришло время выйти на сцену. Это часть рабочего процесса, где вы сделаете репозиторий публичным, если это необходимо, и добавите его на наш сайт Hub. Обязательно расскажите людям, что вы сделали, в dbt Slack в канале #i-made-this или в социальных сетях.

Поддержка

Теперь, это на самом деле раздел, который сопровождающие пакетов говорят мне, что является самым сложным. Вы хотите убедиться, что поддерживаете актуальность версий dbt core, а также отвечаете на открытые pull requests и issues с прозрачностью. У вас также могут быть пользователи, которые задают вопросы о ваших пакетах в части сообщества slack, которую вы не видите. Вот почему так важно иметь хороший процесс для внесения вклада в разделе вклада сообщества рабочего процесса. Один сопровождающий пакета сказал мне, что он просто регулярно ищет ключевые слова в dbt Slack, чтобы поймать случайные вопросы о своем пакете. Так что будьте ясны в общении, и это значительно упростит жизнь с точки зрения элемента сообщества. С точки зрения поддержания актуальности версий dbt core, к счастью для вас, выходит версия v1, и это означает конец ломающих изменений. Тем не менее, было бы хорошо иметь в виду график обслуживания, скажем, каждые 2 месяца, чтобы поддерживать ваш пакет в актуальном состоянии с последними и лучшими обновлениями.

Мой вызов вам

Поделитесь своими знаниями. В сообществе с открытым исходным кодом никогда не бывает слишком много голосов. Присоединяйтесь к каналу #packages-ecoystem, чтобы пообщаться с сопровождающими пакетов.

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

Я с нетерпением жду, что вы создадите.

Благодарности!

Большое спасибо нашим создателям и сопровождающим пакетов, которые позволили мне интервьюировать их и изучить их мнение о лучших практиках работы с пакетами: Андерс, Джо Маркевич, Клаус Хертер, Матеуш Климек, Джереми Коэн.