Перейти к основному содержимому

Координация версий моделей

Координация версий моделей по всей вашей mesh — это критически важная часть процесса версионирования моделей. Это руководство проведёт вас через безопасные best practices по координации производителей и потребителей при внедрении версий моделей.

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

Безопасный выпуск новой версии модели требует координации между производителями моделей (теми, кто их создаёт) и потребителями моделей (теми, кто от них зависит).

В этом руководстве рассматриваются следующие темы:

Подробнее о том, как версионирование работает на техническом уровне (структура YAML, контракты, алиасы), см. версии моделей.

Лучшие практики для производителей​

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

Шаг 1: Определить, когда изменение требует новой версии​

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

Примеры разрушающих изменений, которые могут потребовать новую версию:

  • Удаление столбца
  • Переименование столбца
  • Изменение типа столбца

Примеры неразрушающих изменений:

  • Добавление нового столбца
  • Исправление ошибки в существующем столбце

Примеры изменений, которые могут быть разрушающими в зависимости от бизнес-логики:

  • Изменение логики метрики
  • Изменение гранулярности
  • Модификация фильтров
  • Переписывание CASE-выражений

Шаг 2: Безопасно создать новую версию​

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

  1. Создайте новый файл модели для новой версии. Например, fishtown_analytics_orders_v2.sql. У каждой версии модели должен быть свой SQL-файл.

  2. Оставьте версию по умолчанию стабильной. В файле properties.yml модели:

    • Укажите versions, включив старую и новую версии: - v: 1 и - v: 2 соответственно.
    • Установите latest_version: в latest_version: 1.

    Это гарантирует, что downstream‑потребители, использующие ref(...), не начнут случайно использовать v2. Если этого не сделать, по умолчанию будет выбрана версия с наибольшим номером, что может привести к разрушающим изменениям для потребителей.

  3. Настройте alias или создайте представление (view) поверх последней версии модели. Это гарантирует, что fishtown_analytics_orders (без суффикса версии) всегда существует как объект в хранилище и указывает на последнюю версию. Это также защищает внешние инструменты и BI‑дашборды.

Шаг 3: Добавить дату депрекейта​

  1. В файле properties.yml модели задайте deprecation_date для старой версии модели. deprecation_date — это дата в будущем, которая указывает, когда старая версия будет удалена.

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

к сведению

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

Если вы попытаетесь удалить версионируемую модель до наступления её deprecation_date, dbt выдаст ошибку при запусках в среде разработки, а задания завершатся с ошибкой.

models/properties.yml
models:
  - name: fishtown_analytics_orders
    latest_version: 1
    columns:
      - name: column_to_remove
      - name: column_to_keep

    versions:
      - v: 1                 # старая версия (использует все столбцы верхнего уровня)
        deprecation_date: "2025-12-31"
      - v: 2                 # новая версия
        columns:
          - include: all
            exclude: [column_to_remove]   # столбцы, удалённые в v2
  1. Вмержите новую версию в основную ветку.
  2. Запустите джобу для сборки новой версии.
  3. Убедитесь, что новая версия успешно собирается.
  4. Проверьте, что дата депрекейта корректно отображается в логах dbt run.

Если вы попытаетесь ссылаться на модели (например, {{ ref('upstream_project', 'model_name', v=1) }}) с аргументом v=1 после наступления даты депрекейта, вызов ref завершится ошибкой после того, как проект‑производитель удалит версию v1.

Шаг 4: Сообщить о новой версии​

После создания новой версии и установки даты депрекейта для старой версии сообщите об этом downstream‑потребителям. Дайте им знать, что:

  • Доступна новая версия и определён таймлайн депрекейта.
  • Потребители могут протестировать новую версию и мигрировать на неё.
  • Для тестирования новой версии можно использовать v=2 при обращении к модели. Например: {{ ref('upstream_project', 'model_name', v=2) }}.

Шаг 5: Назначьте новую версию последней​

После того как потребители перейдут на новую версию, назначьте её последней версией. v1 остаётся в проекте до завершения шага 6.

models/properties.yml
models:
  - name: fishtown_analytics_orders
    latest_version: 2 # обновляем с 1 на 2, чтобы сделать новую версию версией по умолчанию
    versions:
          - v: 1 # старая версия
      - v: 2 # новая версия

Это обновит ref по умолчанию на новую версию. Например, {{ ref('upstream_project', 'fishtown_analytics_orders') }} теперь будет указывать на модель fishtown_analytics_orders_v2 в проекте upstream_project. Если потребителям всё ещё нужна старая версия, они могут использовать v=1: {{ ref('upstream_project', 'fishtown_analytics_orders', v=1) }}.

Шаг 6: Очистить депрекейтнутые версии​

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

к сведению

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

Задайте deprecation_date для выводимой из эксплуатации версии. Если вы удаляете её немедленно, укажите дату в прошлом. Выполните слияние этого изменения и запустите задание в производственной среде, чтобы CI с учётом состояния зафиксировал объявление версии устаревшей. В следующем изменении удалите или переименуйте модель, например переименуйте fishtown_analytics_orders_v2.sql в fishtown_analytics_orders.sql.

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

«Физическое удаление» старых версий — самый аккуратный подход. Оно удаляет артефакты версий из проекта и хранилища данных.

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

  1. Удалите SQL-файл устаревшей версии (например, fishtown_analytics_orders_v1.sql).
  2. Если вы полностью отказываетесь от версионирования, переименуйте файл последней версии, присвоив ему базовое имя (например, fishtown_analytics_orders_v2.sql в fishtown_analytics_orders.sql).
  3. Удалите все спецификации версий из файла .yml.
  4. Удалите объекты устаревших версий из хранилища данных с помощью скрипта, запускаемого вручную, или макроса очистки.

... и это всё! Вы добавили новую версию модели и завершили очистку на стороне производителя. Следующий раздел предназначен для потребителей: в нём описано, как оценить новые версии и перейти на них.

Лучшие практики для потребителей​

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

  1. Начните с создания межпроектной ссылки, чтобы использовать публичную модель из другого проекта. В данном случае — {{ ref('upstream_project', 'fishtown_analytics_orders') }}.
  2. Когда появятся предупреждения об устаревании, протестируйте последнюю версию модели, явно указав её в вызове ref. Например, {{ ref('upstream_project', 'fishtown_analytics_orders', v=2) }}. Проверьте, нарушает ли новая версия совместимость с вашим проектом и не приводит ли она к непредвиденным последствиям.
    • Если это так, рассмотрите возможность явно «закрепить» текущую рабочую версию модели, прежде чем новая версия станет версией по умолчанию: {{ ref('upstream_project', 'fishtown_analytics_orders', v=1) }}. Помните, что вам потребуется перейти на новую версию до даты прекращения поддержки устаревшей версии.
  3. До даты прекращения поддержки устаревшей версии вы можете перейти на новую версию модели, удалив указание версии из межпроектной ссылки: {{ ref('upstream_project', 'fishtown_analytics_orders') }}. Внесите необходимые изменения в логику зависимых моделей, чтобы обеспечить совместимость с новой версией.

Потребителям следует планировать миграции с учётом собственных циклов релизов команды.

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

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

0
Loading