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

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

Координация версий моделей по всей вашей 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 — это дата в будущем, которая указывает, когда старая версия будет удалена.

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

    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

  2. Вмержите новую версию в основную ветку.

  3. Запустите джобу для сборки новой версии.

  4. Убедитесь, что новая версия успешно собирается.

  5. Проверьте, что дата депрекейта корректно отображается в логах 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: Удалить старую версию​

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

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: Очистить депрекейтнутые версии​

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

«Жёсткое удаление» — самый чистый подход, при котором все артефакты старых версий полностью удаляются из проекта:

  1. Удалите файл fishtown_analytics_orders_v1.sql и переименуйте файл новой версии обратно в fishtown_analytics_orders.sql.
  2. Удалите все спецификации версий из .yml‑файла.
  3. Удалите объект fishtown_analytics_orders_v1 из хранилища вручную с помощью скрипта или cleanup‑макроса.

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

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

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

  1. Начните с использования cross‑project ref для публичной модели из другого проекта. В данном случае: {{ 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. До наступления даты депрекейта вы можете мигрировать на новую версию модели, убрав указание версии в cross‑project ref: {{ ref('upstream_project', 'fishtown_analytics_orders'). Внесите все необходимые изменения в downstream‑логику, чтобы она корректно работала с новой версией.

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

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

0
Loading