Зависимости проекта

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

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

В этом году dbt Labs вводит расширенное понятие dependencies (зависимостей) между несколькими проектами dbt:

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

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

• Доступно в dbt Cloud Enterprise. Если у вас есть корпоративный аккаунт, вы можете разблокировать эти функции, назначив публичную модель и добавив межпроектную ссылку. enterprise
• Определите модели в вышестоящем ("производящем") проекте, которые настроены с access: public. Вам нужно как минимум одно успешное выполнение задания после определения их access.
• Определите среду развертывания в вышестоящем ("производящем") проекте которая настроена как ваша производственная среда, и убедитесь, что в этой среде было выполнено как минимум одно успешное задание.
• Если в вышестоящем проекте есть среда Staging, выполните задание в этой среде Staging, чтобы убедиться, что межпроектная ссылка разрешается.
• Каждое имя проекта name должно быть уникальным в вашем аккаунте dbt Cloud. Например, если у вас есть проект dbt (кодовая база) для команды jaffle_marketing, вы не должны создавать отдельные проекты для Jaffle Marketing - Dev и Jaffle Marketing - Prod. Эта изоляция должна быть обработана на уровне среды.
  • Мы добавляем поддержку разрешений на уровне среды и подключений к хранилищу данных; пожалуйста, свяжитесь с вашей командой аккаунта dbt Labs для доступа к бета-версии.
• Файл dbt_project.yml чувствителен к регистру, что означает, что имя проекта должно точно соответствовать имени в вашем dependencies.yml. Например, если имя вашего проекта jaffle_marketing, вы должны использовать jaffle_marketing (а не JAFFLE_MARKETING) во всех связанных файлах.

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

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

• Добавьте любые зависимости пакетов в packages.yml
• Добавьте любые зависимости проекта в dependencies.yml

Однако, вы можете объединить оба файла в один 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 (или оба). Обратитесь к Часто задаваемым вопросам для получения дополнительной информации.

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

Зависимости проекта предназначены для dbt Mesh и рабочего процесса межпроектных ссылок:

• Используйте dependencies.yml, когда вам нужно настроить межпроектные ссылки между различными проектами dbt, особенно в настройке dbt Mesh.
• Используйте dependencies.yml, когда вы хотите включить как проекты, так и нечастные пакеты dbt в зависимости вашего проекта.
  • Частные пакеты не поддерживаются в dependencies.yml, потому что они намеренно не поддерживают рендеринг Jinja или условную конфигурацию. Это сделано для поддержания статической и предсказуемой конфигурации и обеспечения совместимости с другими сервисами, такими как dbt Cloud.
• Используйте dependencies.yml для организации и поддерживаемости, если вы используете как межпроектные ссылки, так и пакеты dbt Hub. Это уменьшает необходимость в нескольких YAML-файлах для управления зависимостями.

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

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

• Если вы используете только пакеты, такие как из dbt Hub, оставайтесь с packages.yml.
• Используйте packages.yml, когда вы хотите загрузить пакеты dbt, такие как проекты dbt, в ваш корневой или родительский проект dbt. Стоит отметить, что это не способствует рабочему процессу dbt Mesh.
• Используйте packages.yml, чтобы включить пакеты, включая частные пакеты, в зависимости вашего проекта. Если у вас есть частные пакеты, к которым вам нужно обратиться, packages.yml — это то, что вам нужно.
• packages.yml поддерживает рендеринг Jinja по историческим причинам, позволяя динамическую конфигурацию. Это может быть полезно, если вам нужно вставить значения, такие как метод Git-токена из переменной окружения, в спецификации вашего пакета.

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

Пример

Например, предположим, что вы работаете в команде маркетинга в Jaffle Shop. Имя проекта вашей команды - jaffle_marketing:

dbt_project.yml

name: jaffle_marketing

В рамках моделирования маркетинговых данных вам нужно взять зависимость от двух других проектов:

• dbt_utils как пакет: Коллекция утилитарных макросов, которые вы можете использовать при написании SQL для своих моделей. Этот пакет является открытым и поддерживается dbt Labs.
• jaffle_finance как проектный кейс: Модели данных о доходах Jaffle Shop. Этот проект является частным и поддерживается вашими коллегами из финансовой команды. Вы хотите выбрать некоторые из финальных моделей этого проекта в качестве отправной точки для своей работы.

dependencies.yml

packages:
  - package: dbt-labs/dbt_utils
    version: 1.1.1

projects:
  - name: jaffle_finance  # чувствителен к регистру и соответствует 'name' в 'dbt_project.yml'

Что здесь происходит?

Пакет dbt_utils — Когда вы запускаете dbt deps, dbt загружает полный контент этого пакета (более 100 макросов) как исходный код и добавляет его в вашу среду. Вы можете затем вызывать любой макрос из пакета, так же как вы можете вызывать макросы, определенные в вашем собственном проекте.

Проекты jaffle_finance — Это новый сценарий. В отличие от установки пакета, модели в проекте jaffle_finance не будут загружены как исходный код и разобраны в вашем проекте. Вместо этого dbt Cloud предоставляет метаданные-сервис, который разрешает ссылки на публичные модели, определенные в проекте jaffle_finance.

Преимущества

Когда вы строите на основе работы другой команды, разрешение ссылок таким образом имеет несколько преимуществ:

• Вы используете намеренный интерфейс, назначенный поддерживающим модель с access: public.
• Вы сохраняете узкий охват вашего проекта и избегаете ненужных ресурсов и сложности. Это быстрее для вас и быстрее для dbt.
• Вам не нужно зеркалировать любую условную конфигурацию вышестоящего проекта, такую как vars, переменные среды или target.name. Вы можете ссылаться на них напрямую, где бы команда финансов ни строила свои модели в производстве. Даже если команда финансов вносит изменения, такие как переименование модели, изменение имени ее схемы или повышение ее версии, ваша ref все равно будет успешно разрешаться.
• Вы исключаете риск случайного построения этих моделей с помощью dbt run или dbt build. Хотя вы можете выбрать эти модели, вы не можете их фактически построить. Это предотвращает неожиданные затраты на хранилище и проблемы с разрешениями. Это также обеспечивает надлежащее владение и распределение затрат для моделей каждой команды.

Как написать межпроектную ссылку

Написание ref: Модели, на которые ссылаются из зависимости типа project, должны использовать двухаргументную ref, включая имя проекта:

models/marts/roi_by_channel.sql

with monthly_revenue as (
  
    select * from {{ ref('jaffle_finance', 'monthly_revenue') }}

),

...

Обнаружение циклов

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

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

1. Проект project_a выполняется в среде развертывания и создает публичные модели.
2. Проект project_b добавляет project_a в качестве зависимости.
3. Проект project_b выполняется в среде развертывания и создает публичные модели.
4. Проект project_a добавляет project_b в качестве зависимости.

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

Защита производственных данных с помощью промежуточных сред

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

С интегрированной в проект средой Staging, dbt Mesh автоматически получает информацию о публичной модели из промежуточной среды производителя, если потребитель также находится в промежуточной среде. Аналогично, dbt Mesh получает данные из производственной среды производителя, если потребитель находится в производственной среде. Это обеспечивает согласованность между средами и добавляет уровень безопасности, предотвращая доступ к производственным данным во время рабочих процессов разработки.

Прочтите Почему использовать промежуточную среду для получения дополнительной информации о преимуществах.

Промежуточная среда с нисходящими зависимостями

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

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

1. Создайте новую среду, но НЕ помечайте ее как Staging.
2. Определите задание в этой среде.
3. Запустите задание и убедитесь, что оно завершилось успешно.
4. Обновите среду, чтобы пометить ее как Staging.

Сравнение

Если бы вы вместо этого установили проект jaffle_finance как зависимость package, вы бы загружали его полный исходный код и добавляли его в свою среду выполнения. Это означает:

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

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

• Объединенные развертывания — В производственной среде, если центральная команда платформы данных Jaffle Shop хотела бы запланировать развертывание моделей как в jaffle_finance, так и в jaffle_marketing, они могли бы использовать синтаксис выбора dbt для создания нового "проходного" проекта, который устанавливает оба проекта как пакеты.
• Скоординированные изменения — В разработке, если вы хотите протестировать эффекты изменения публичной модели в вышестоящем проекте (jaffle_finance.monthly_revenue) на нисходящей модели (jaffle_marketing.roi_by_channel) до внесения изменений в промежуточную или производственную среду, вы можете установить пакет jaffle_finance как пакет в jaffle_marketing. Установка может указывать на конкретную ветку git, однако, если вы часто нуждаетесь в проведении сквозного тестирования между обоими проектами, мы рекомендуем пересмотреть, представляет ли это стабильную границу интерфейса.

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

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

Могу ли я определить частные пакеты в файле dependencies.yml?

Если вы используете частные пакеты с методом токена git, вы должны определить их в файле packages.yml вместо файла dependencies.yml. Это связано с тем, что условный рендеринг (например, Jinja-in-yaml) не поддерживается.

Связанные документы

• Обратитесь к руководству по dbt Mesh для получения дополнительной информации о том, как использовать dbt Mesh.
• Быстрый старт с dbt Mesh