Руководство по миграции устаревшего семантического слоя dbt

Обновлен

Semantic Layer

Migration

Intermediate

Menu

Введение

Устаревший семантический слой будет снят с поддержки во второй половине 2023 года. Кроме того, пакет dbt_metrics не будет поддерживаться в dbt версии 1.6 и выше. Если вы используете dbt_metrics, вам нужно обновить ваши конфигурации перед обновлением до версии 1.6. Это руководство предназначено для тех, кто использует устаревший семантический слой dbt и хочет перейти на новый семантический слой dbt. Оценочное время миграции составляет две недели.

Миграция конфигураций метрик на новую спецификацию

Спецификация метрик в dbt Core изменилась в версии 1.6 для поддержки интеграции с MetricFlow. Настоятельно рекомендуется ознакомиться с Создание метрик перед началом, чтобы понять основные концепции семантического слоя.

dbt Labs рекомендует выполнять эти шаги в локальной среде разработки (например, dbt Cloud CLI) вместо dbt Cloud IDE:

1. Создайте новые конфигурации семантической модели в виде YAML-файлов в вашем проекте dbt.*

2. Обновите конфигурации метрик в вашем проекте до новой спецификации.*

3. Удалите ваш старый файл метрик или уберите расширение .yml, чтобы они игнорировались при разборе. Удалите пакет dbt-metrics из вашего проекта. Удалите любые макросы, которые ссылаются на dbt-metrics, такие как metrics.calculate(). Убедитесь, что используемые вами пакеты не содержат ссылок на старую спецификацию метрик.

4. Установите dbt Cloud CLI для выполнения команд MetricFlow и определения конфигураций вашей семантической модели.

   • Если вы используете dbt Core, установите MetricFlow CLI с помощью python -m pip install "dbt-metricflow[your_adapter_name]". Например:

   python -m pip install "dbt-metricflow[snowflake]"

   Примечание - Команды MetricFlow пока не поддерживаются в dbt Cloud IDE.

5. Запустите dbt parse. Это разберет ваш проект и создаст файл semantic_manifest.json в вашей целевой директории. MetricFlow нуждается в этом файле для выполнения запросов к метрикам. Если вы внесете изменения в ваши конфигурации, вам нужно будет снова разобрать ваш проект.

6. Запустите mf list metrics, чтобы просмотреть метрики в вашем проекте.

7. Протестируйте запрос к метрике, запустив mf query --metrics <metric_name> --group-by <dimensions_name>. Например:

   mf query --metrics revenue --group-by metric_time

8. Запустите mf validate-configs для выполнения семантических и складских проверок. Это гарантирует, что ваши конфигурации действительны и что базовые объекты существуют в вашем хранилище.

9. Отправьте эти изменения в новую ветку вашего репозитория.

ref не поддерживается

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

*Чтобы упростить этот процесс, dbt Labs предоставляет пользовательский инструмент миграции, который автоматизирует эти шаги для вас. Вы можете найти инструкции по установке в README. Производные метрики не поддерживаются в инструменте миграции и должны быть перенесены вручную.

Аудит значений метрик после миграции

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

1. В CLI выполните запрос к метрике(ам) и измерениям, которые вы хотите протестировать, и включите опцию --explain. Например:

   mf query --metrics orders,revenue --group-by metric_time__month,customer_type --explain

2. Используйте SQL MetricFlow для создания временной модели в вашем проекте, например, tmp_orders_revenue audit.sql. Вы будете использовать эту временную модель для сравнения с вашими устаревшими метриками.

3. Если вы еще этого не сделали, создайте модель, используя metrics.calculate() для метрик, которые вы хотите сравнить. Например:

   select * 
   from {{ metrics.calculate(  
   [metric('orders)',
   metric('revenue)'],
       grain='week',
       dimensions=['metric_time', 'customer_type'],
   ) }}

4. Запустите помощник dbt-audit на обеих моделях, чтобы сравнить значения метрик.

Настройка семантического слоя в новой среде

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

1. Создайте новую среду развертывания в dbt Cloud и установите версию dbt 1.6 или выше.

2. Выберите Только запуск на пользовательской ветке и укажите ветку, в которой определены обновленные метрики.

3. Установите схему развертывания на временную миграционную схему, такую как tmp_sl_migration. По желанию, вы можете создать новую базу данных для миграции.

4. Создайте задание для разбора вашего проекта, например, dbt parse, и запустите его. Убедитесь, что это задание выполнено успешно. В вашей среде должно быть успешное задание для настройки семантического слоя.

5. Выберите Настройки аккаунта -> Проекты -> Детали проекта и выберите Настроить семантический слой.

6. В разделе Среда выберите среду развертывания, созданную на предыдущем шаге. Сохраните вашу конфигурацию.

7. На странице Детали проекта нажмите Создать токен сервиса и предоставьте ему разрешения Только семантический слой и Только метаданные. Сохраните этот токен в безопасном месте. Он понадобится вам для подключения к семантическому слою.

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

Обновление подключения в интеграциях нижнего уровня

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

Руководство по миграции для Hex

Чтобы узнать больше о интеграции с Hex, ознакомьтесь с их документацией для получения дополнительной информации. Кроме того, обратитесь к ячейкам семантического слоя dbt для настройки SQL ячеек в Hex.

1. Настройте новое подключение для семантического слоя dbt для вашего аккаунта. Обратите внимание, что ваше устаревшее подключение все еще будет работать.

2. Воссоздайте панели или отчеты, которые используют устаревший семантический слой dbt.

3. Для получения подробной информации о синтаксисе SQL обратитесь к Запрос API для метаданных метрик для выполнения запросов к метрикам с использованием API.

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

Руководство по миграции для Mode

1. Настройте новое подключение для семантического слоя для вашего аккаунта. Следуйте документации Mode для настройки вашего подключения.

2. Воссоздайте панели или отчеты, которые используют устаревший семантический слой dbt.

3. Для получения подробной информации о синтаксисе SQL обратитесь к Запрос API для метаданных метрик для выполнения запросов к метрикам с использованием API.

Слияние вашей ветки миграции метрик в основную и обновление вашей производственной среды до версии 1.6

1. Обновите вашу производственную среду до версии 1.6 или выше.

   • Примечание — Старые определения метрик больше не действительны, поэтому ваши задания dbt не будут проходить.

2. Слейте ваши обновленные определения метрик в основную ветку. На этом этапе устаревший семантический слой больше не будет работать.

Если вы создали новую среду на Шаге 3:

3. Обновите вашу среду в Настройки аккаунта -> Детали проекта -> Редактировать конфигурацию семантического слоя, чтобы указать на вашу производственную среду.

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

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

• Руководство по быстрому старту с семантическим слоем dbt
• Часто задаваемые вопросы о семантическом слое dbt
• Конвертер метрик dbt
• Почему мы снимаем с поддержки пакет dbt_metrics блог
• Синтаксис запроса API семантического слоя dbt
• Курс по семантическому слою dbt по требованию