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

Доступно на тарифных планах dbt Enterprise или Enterprise+.

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

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

dbt Labs поддерживает расширенное понимание dependencies между несколькими dbt‑проектами:

• Packages — знакомый и уже существующий тип зависимости. Вы подключаете такую зависимость, устанавливая полный исходный код пакета (аналогично программной библиотеке).
• Projects — способ dbt брать зависимость от другого проекта. Используя сервис метаданных, работающий «за кулисами», dbt на лету разрешает ссылки на публичные модели, определённые в других проектах. Вам не нужно самостоятельно парсить или запускать эти апстрим‑модели. Вместо этого вы рассматриваете зависимость от них как API, которое возвращает датасет. Ответственность за качество и стабильность публичной модели несёт её владелец.

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

• Доступно в dbt Enterprise или Enterprise+. Чтобы использовать эту возможность, необходимо назначить public model и добавить cross-project ref.
• Требования к настройке апстрим‑проекта («producer»):
  • Настройте модели в апстрим‑проекте с параметром access: public и выполните как минимум один успешный запуск job после задания access.
  • Определите Production deployment environment в апстрим‑проекте и убедитесь, что там успешно отработал как минимум один deployment job. Этот job должен сгенерировать файл manifest.json — он содержит метаданные, необходимые для даунстрим‑проектов.
  • Если в апстрим‑проекте есть Staging‑окружение, выполните там как минимум один успешный deployment job, чтобы обеспечить корректное разрешение cross‑project ссылок в даунстрим‑проектах.
• Имя каждого проекта (name) должно быть уникальным в рамках вашего аккаунта dbt. Например, если у вас есть dbt‑проект (кодовая база) для команды jaffle_marketing, не создавайте отдельные проекты Jaffle Marketing - Dev и Jaffle Marketing - Prod; вместо этого используйте изоляцию на уровне окружений.
  • dbt поддерживает Connections, доступные всем пользователям dbt. Connections позволяют использовать разные подключения к платформе данных для разных окружений, устраняя необходимость дублировать проекты. Проекты могут использовать несколько подключений одного и того же типа хранилища. Connections переиспользуются между проектами и окружениями.
• Файл dbt_project.yml чувствителен к регистру, поэтому имя проекта должно точно совпадать с именем, указанным в dependencies.yml. Например, jaffle_marketing, а не JAFFLE_MARKETING.

Варианты использования

Следующая настройка подойдет для любого 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.

 Когда использовать project dependencies

Project dependencies предназначены для воркфлоу dbt Mesh и cross-project reference:

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

 Когда использовать package dependencies

Package dependencies позволяют добавлять в ваш проект исходный код из dbt-проекта другого автора — как библиотеку:

• Если вы используете только пакеты, например из dbt Hub, оставайтесь на packages.yml.
• Используйте packages.yml, когда нужно скачать dbt-пакеты (например, dbt-проекты) в корневой (root) или родительский (parent) dbt-проект. Важно: это не относится к воркфлоу dbt Mesh.
• Используйте packages.yml, чтобы включать пакеты в зависимости проекта. Это включает и публичные пакеты (например из dbt Hub), и приватные пакеты. dbt теперь поддерживает native private packages.
• packages.yml поддерживает рендеринг Jinja по историческим причинам, что позволяет делать динамические конфигурации. Это может быть полезно, если нужно подставлять значения (например метод Git token method из переменной окружения) в спецификации пакетов.

Ранее для использования приватных Git-репозиториев в dbt приходилось применять обходной путь: встраивать Git token с помощью Jinja. Это неидеально, потому что требует дополнительных шагов — например, создавать пользователя и делиться Git token. Мы добавили поддержку native private packages, чтобы решить эту проблему.

Пример

Например, предположим, что вы работаете в команде маркетинга в 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 не будут загружены как исходный код и разобраны (parsed) в вашем проекте. Вместо этого dbt предоставляет сервис метаданных, который разрешает ссылки на публичные модели, определённые в проекте jaffle_finance.

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

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

• Вы используете осознанно спроектированный интерфейс, обозначенный владельцем модели с помощью access: public.
• Вы сохраняете узкий фокус своего проекта и избегаете лишних ресурсов и сложности. Это быстрее для вас и быстрее для dbt.
• Вам не нужно дублировать какую‑либо условную конфигурацию вышестоящего проекта, такую как vars, переменные окружения или target.name. Вы можете напрямую ссылаться на модели там, где команда Finance собирает их в продакшене. Даже если команда Finance внесёт изменения — например, переименует модель, изменит имя схемы или повысит её версию, — ваш 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 в качестве зависимости.

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

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

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

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

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

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

dbt начинает использовать окружение Staging для разрешения межпроектных ссылок из downstream‑проектов сразу после того, как это окружение появляется в проекте, без «fail-over» на Production. Это означает, что dbt будет последовательно использовать метаданные из окружения Staging для разрешения ссылок в downstream‑проектах, даже если в настроенном окружении Staging ещё не было ни одного успешного запуска.

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

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?

Это зависит от того, каким способом вы получаете доступ к приватным пакетам:

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

Почему косвенно используемая upstream public модель не отображается в Explorer?

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

Например, если:

• project_b добавляет project_a как зависимость
• модель downstream_c в project_b ссылается на project_a.upstream_b
• project_a.upstream_b ссылается на другую публичную модель — project_a.upstream_a

Тогда:

• В Explorer отображаются только напрямую используемые публичные модели (в данном случае — upstream_b).
• В представлении lineage в Studio IDE, однако, upstream_a (косвенная зависимость) будет отображаться, поскольку dbt динамически разрешает полный граф зависимостей.

Такое поведение гарантирует, что Catalog показывает только непосредственные зависимости, доступные для конкретного проекта.

Связанные материалы

• Подробнее о том, как использовать Mesh, см. руководство Mesh.
• Быстрый старт с Mesh

Нашли ошибку?

Создать GitHub Issue