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

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

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

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

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

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

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

• Доступно в dbt Enterprise или Enterprise+. Для использования обозначьте модель как публичную и добавьте межпроектную ссылку ref.
• Для настройки вышестоящего проекта («производителя»):
  • Настройте модели в вышестоящем проекте с помощью access: public и обеспечьте хотя бы один успешный запуск задания после определения access.
  • Определите в вышестоящем проекте среду развёртывания Production и убедитесь, что в ней успешно выполнено хотя бы одно задание развёртывания. Это задание должно создать файл manifest.json — он содержит метаданные, необходимые нижестоящим проектам.
  • Если в вышестоящем проекте есть среда Staging, обеспечьте в ней хотя бы один успешный запуск задания развёртывания, чтобы межпроектные ссылки из нижестоящих проектов разрешались корректно.
• Значение name каждого проекта должно быть уникальным в вашей учётной записи dbt. Например, если у вас есть проект dbt (кодовая база) для команды jaffle_marketing, не создавайте отдельные проекты Jaffle Marketing - Dev и Jaffle Marketing - Prod; вместо этого используйте изоляцию на уровне сред.
  • dbt поддерживает подключения (Connections), доступные всем пользователям dbt. Подключения позволяют использовать разные подключения к платформам данных для каждой среды, устраняя необходимость дублировать проекты. Проекты могут использовать несколько подключений к хранилищам одного типа. Подключения можно повторно использовать в разных проектах и средах.
• Файл 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.

Для приватных пакетов без токенов Jinja можно использовать встроенную поддержку приватных пакетов в packages.yml или dependencies.yml.

Если вашему проекту dbt не требуется Jinja в спецификациях пакетов, вы можете переименовать packages.yml в dependencies.yml. Если вам требуется Jinja в спецификациях пакетов (например, для переменной окружения или метода с Git-токеном):

• В dbt v1 продолжайте использовать packages.yml. dbt v1 не обрабатывает Jinja в dependencies.yml.
• В dbt v2 можно использовать Jinja в dependencies.yml. Если проект должен работать и в dbt v1, рекомендуется использовать packages.yml.

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

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

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

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

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

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

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

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

Определение зависимостей проекта

Если ваш проект dbt использует модели из другого проекта, вы можете определить эту связь с помощью зависимостей проекта. Следующие шаги помогут вам указать зависимости проекта в dbt:

1. Создайте файл dependencies.yml в корневом каталоге вашего проекта dbt.
2. В файле dependencies.yml укажите вышестоящий проект dbt, от которого зависит ваш проект, используя его имя из файла dbt_projects.yml.
3. (Необязательно) Укажите конкретные модели, которые вы ожидаете получить из этого вышестоящего проекта, чтобы явно определить зависимость.
4. Используйте ref() с именем проекта, чтобы ссылаться на модели вышестоящего проекта в SQL.
5. Создайте коммит с изменениями и убедитесь, что зависимость настроена в dbt.
6. dbt разрешает зависимость, используя метаданные публичных моделей из выбранной среды вышестоящего проекта, и отображает межпроектные связи в представлениях происхождения данных и DAG (направленного ациклического графа). Запускайте задания развертывания вышестоящего проекта отдельно или настройте цепочку заданий, если вам нужно согласованное выполнение.

Пример

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

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

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

• Вы используете специально предусмотренный интерфейс, который разработчик, отвечающий за модель, обозначил с помощью access: public.

• Вы ограничиваете область ответственности своего проекта и избегаете ненужных ресурсов и сложности. Это ускоряет и вашу работу, и работу dbt.

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

• Вы исключаете риск случайного построения этих моделей с помощью dbt run или dbt build. Хотя вы можете выбрать эти модели, построить их вы не сможете. Это предотвращает непредвиденные расходы на хранилище данных и проблемы с правами доступа. Кроме того, это обеспечивает корректное закрепление ответственности за модели каждой команды и распределение связанных с ними затрат.

• Вы используете осознанно спроектированный интерфейс, обозначенный владельцем модели с помощью 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') }}

),

...

Сообщить об ошибке в коде

(Версии dbt: v1.12 и новее)

Межпроектные ссылки не поддерживаются в последней версии спецификации YAML для Semantic Layer

При использовании dbt Mesh с Semantic Layer ссылки на модели из других проектов поддерживаются только в устаревшей спецификации YAML, где семантические модели определяются как ресурсы верхнего уровня и могут ссылаться на модели из других проектов.

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

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

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

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

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

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

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

Чтобы защитить производственные данные, настройте среду развертывания Staging в своих проектах.

Если в вышестоящем проекте есть среда Staging, межпроектные ссылки ref из сред Development и Staging нижестоящих проектов разрешаются в среду Staging вышестоящего проекта. Если в вышестоящем проекте нет среды Staging, они разрешаются в его среду Production. По умолчанию ссылки из сред Production нижестоящих проектов разрешаются в среду Production вышестоящего проекта. Это обеспечивает согласованность между средами и добавляет дополнительный уровень безопасности, предотвращая доступ к производственным данным в процессе разработки.

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

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

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

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

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

Маршрутизация окружений между проектами

По умолчанию dbt выбирает окружение вышестоящего проекта для межпроектного ref по правилам для production и staging, описанным в предыдущем разделе. Чтобы изменить используемое окружение вышестоящего проекта, отредактируйте файл dependencies.yml в нижестоящем проекте и добавьте поле mesh_environment_routing для каждого вышестоящего проекта, для которого нужна маршрутизация. В вышестоящем проекте ничего менять не нужно. Вызов ref в коде модели остается без изменений.

Доступность

Маршрутизация окружений доступна в dbt platform для dbt v1 в каналах выпуска Latest и Compatible, а для dbt v2 — в Stable и Nightly. В каналах Extended она появится в ноябре 2026 года.

Как работает маршрутизация

Маршруты задаются для каждого вышестоящего проекта в файле dependencies.yml нижестоящего проекта, поэтому один запуск нижестоящего проекта может обращаться к разным окружениям разных проектов. В следующей таблице сравниваются окружения вышестоящего проекта, которые dbt использует для каждого окружения нижестоящего проекта:

Окружение нижестоящего проекта	По умолчанию без маршрутизации	С маршрутизацией
Production	Production вышестоящего проекта	Выбранное вами окружение вышестоящего проекта
Staging	Staging вышестоящего проекта, если настроено; иначе production	Выбранное вами окружение вышестоящего проекта, например production
General	Staging вышестоящего проекта, если настроено; иначе production	Выбранное вами окружение вышестоящего проекта, например конкретное окружение general по ID
Development	Staging вышестоящего проекта, если настроено; иначе production	Выбранное вами окружение вышестоящего проекта

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

Настройка маршрутов

В следующем примере:

• Для orders_project запуски из staging направляются в его окружение production, запуски из development — в окружение, указанное переменной окружения DBT_ROUTE_TO_ID, а запуски из окружения general нижестоящего проекта — в конкретное окружение general вышестоящего проекта. Для всех остальных окружений используется production, поскольку оно задано по умолчанию.
• Для finance_project окружение по умолчанию не задано, поэтому для окружений нижестоящего проекта, отличных от 12001, сохраняется автоматическое поведение.

dependencies.yml

projects:
  - name: orders_project
    default_upstream_environment: production
    mesh_environment_routing:
      - in_this_project_environment: staging
        use_upstream_environment: production
      - in_this_project_environment: development
        use_upstream_environment: DBT_ROUTE_TO_ID
      - in_this_project_environment: 12001  # Downstream general environment ID
        use_upstream_environment: 34002      # orders_project general environment ID
  - name: finance_project
    mesh_environment_routing:
      - in_this_project_environment: 12001
        use_upstream_environment: production

Сообщить об ошибке в коде

В следующей таблице описан каждый ключ:

Ключ	Описание	Допустимые значения
name	Вышестоящий проект. Должно совпадать со значением name в его файле dbt_project.yml.	Имя существующего проекта (с учетом регистра).
mesh_environment_routing	Упорядоченные явно заданные маршруты для этого вышестоящего проекта. Необязательный ключ.	YAML-список пар, задающих маршруты.
in_this_project_environment	Окружение нижестоящего проекта, в котором выполняется dbt.	Числовой ID окружения; production, staging или development; либо имя переменной окружения.
use_upstream_environment	Окружение вышестоящего проекта, относительно которого разрешается ref.	Числовой ID окружения развертывания; production или staging; либо имя переменной окружения.
default_upstream_environment	Окружение вышестоящего проекта, используемое, если ни один маршрут не подходит. Указывается на одном уровне с mesh_environment_routing. Необязательный ключ.	Те же значения, что и для use_upstream_environment.

При настройке маршрутов учитывайте следующие правила:

• Приоритет имеет первый подходящий маршрут в записи проекта. Избегайте повторяющихся селекторов.
• Подходящий маршрут имеет приоритет над default_upstream_environment проекта.
• Чтобы указать окружение general или другое пользовательское окружение развертывания, используйте его ID. general не является ключевым словом.
• Указывайте только имя переменной (DBT_ROUTE_TO_ID), без конструкций Jinja, таких как {{ env_var('DBT_ROUTE_TO_ID') }}.
• Определите DBT_ROUTE_TO_ID в окружении запуска или разработки нижестоящего проекта.
• Задайте для нее значение production, staging или ID окружения развертывания в orders_project.

Проверка маршрутов

Маршрутизация меняет окружение вышестоящего проекта, используемое для разрешения ref. Она не копирует данные и не предоставляет доступ. Прежде чем полагаться на маршрут, проверьте следующее:

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

Выполните dbt compile --select YOUR_DOWNSTREAM_MODEL и проверьте базу данных и схему в скомпилированном SQL или в target/manifest.json. Затем выполните dbt build --select YOUR_DOWNSTREAM_MODEL, чтобы проверить доступ к хранилищу.

Маршрутизация — не deferral

Маршрутизация Mesh выбирает окружение в другом проекте для межпроектного ref. Меню Defer в Studio IDE и параметр --defer используют состояние для разрешения ссылок на несобранные или невыбранные узлы в текущем проекте. Оба механизма можно использовать в одном рабочем процессе разработки.

Сравнение

Если бы вы вместо этого установили проект 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-токеном, в dbt v1 используйте packages.yml, поскольку Jinja не поддерживается в dependencies.yml. В dbt v2 можно использовать dependencies.yml, но мы рекомендуем использовать packages.yml, если ваш проект должен также работать в dbt v1. См. Поддержка Jinja по типам файлов.

Почему косвенно используемая 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).
• Однако в представлении графа зависимостей в Studio IDE upstream_a (косвенная зависимость) будет отображаться, поскольку dbt динамически определяет полный граф зависимостей.

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

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

• Обратитесь к руководству по Mesh, чтобы узнать больше об использовании Mesh.
• Быстрый старт с Mesh
• Гибридная разработка с dbt platform и dbt v2 — управление учетными данными, переменными окружения, отложенным разрешением ссылок (deferral) и версиями dbt v2 при локальной разработке с проектом Mesh

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

Создать GitHub Issue