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

Назад к гайдам

Semantic Layer

Migration

Intermediate

Menu

Введение

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

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

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

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

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

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

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

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

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

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

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

Примечание — команды MetricFlow в настоящее время ещё не поддерживаются в Studio IDE.

2. Запустите dbt parse. Это разберет ваш проект и создаст файл semantic_manifest.json в вашей целевой директории. MetricFlow нуждается в этом файле для выполнения запросов к метрикам. Если вы внесете изменения в ваши конфигурации, вам нужно будет снова разобрать ваш проект.
3. Запустите mf list metrics, чтобы просмотреть метрики в вашем проекте.
4. Протестируйте запрос к метрике, запустив mf query --metrics <metric_name> --group-by <dimensions_name>. Например:

   mf query --metrics revenue --group-by metric_time
5. Запустите mf validate-configs для выполнения семантических и складских проверок. Это гарантирует, что ваши конфигурации действительны и что базовые объекты существуют в вашем хранилище.
6. Отправьте эти изменения в новую ветку вашего репозитория.

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 и установите версию dbt 1.6 или выше.

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

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

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

5. Выберите Account Settings → Projects → Project details и нажмите Configure the Semantic Layer.

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

7. На странице Project details нажмите Generate service token и выдайте ему права Semantic Layer Only и Metadata Only. Надёжно сохраните этот токен. Он понадобится вам для подключения к семантическому слою.

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

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

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

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

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

Чтобы узнать больше об интеграции с Hex, ознакомьтесь с их документацией. Также см. ячейки Semantic Layer, чтобы настроить SQL‑ячейки в Hex.

1. Настройте новое подключение к Semantic Layer для вашей учетной записи. Обратите внимание, что ваше устаревшее подключение продолжит работать.

2. Пересоздайте дашборды или отчеты, которые используют устаревший Semantic Layer.

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

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

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

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

3. Пересоздайте дашборды или отчёты, которые используют устаревший Semantic Layer.

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

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

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

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

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

3. Обновите окружение в Account Settings -> Project Details -> Edit Semantic Layer Configuration, указав ваше production‑окружение

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

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

• Краткое руководство по началу работы с Semantic Layer
• Часто задаваемые вопросы (FAQ) по Semantic Layer
• Конвертер метрик dbt
• Почему мы выводим из эксплуатации пакет dbt_metrics — запись в блоге
• Синтаксис запросов к API Semantic Layer
• Курс по Semantic Layer в формате on-demand

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

Создать GitHub Issue