Интеграция с семантическим слоем dbt с использованием лучших практик

Обновлен

Semantic Layer

Best practices

Advanced

Menu

Введение

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

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

📹 Узнайте о семантическом слое dbt с помощью видеокурсов по запросу!

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

Кроме того, погрузитесь в мини-курсы по запросам к семантическому слою dbt в ваших любимых инструментах: Tableau, Excel, Hex и Mode.

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

Чтобы построить интеграцию с семантическим слоем dbt:

• Мы предлагаем JDBC API и GraphQL API. Обратитесь к специальному API семантического слоя dbt для получения более подробной информации о технической интеграции.

• Ознакомьтесь с ключевыми концепциями семантического слоя dbt и MetricFlow. Существует два основных объекта:

  • Семантические модели — Узлы в вашем семантическом графе, соединенные через сущности как ребра. MetricFlow принимает семантические модели, определенные в YAML-файлах конфигурации, в качестве входных данных и создает семантический граф, который вы можете использовать для запроса метрик.
  • Метрики — Могут быть определены в тех же YAML-файлах, что и ваши семантические модели, или разделены на отдельные YAML-файлы в любых других подкаталогах (при условии, что эти подкаталоги также находятся в том же репозитории проекта dbt).

Параметры подключения

API семантического слоя dbt аутентифицируются с помощью environmentId, SERVICE_TOKEN и host.

Мы рекомендуем предоставлять пользователям отдельные поля ввода с этими компонентами для аутентификации (dbt Cloud предоставит эти параметры пользователю).

Раскрытие метаданных для dbt Labs

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

Пожалуйста, отправляйте нам следующий заголовок с каждым запросом:

'X-dbt-partner-source': 'Your-Application-Name'

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

Используйте лучшие практики при раскрытии метрик

Лучшие практики для раскрытия метрик сведены в пять тем:

• Управление — Рекомендации по установлению ограничений для управляемой работы с данными.
• Обнаруживаемость — Рекомендации по созданию удобных для пользователя взаимодействий с данными.
• Организация — Организуйте метрики и измерения для всех аудиторий, используйте сохраненные запросы.
• Гибкость запросов — Позвольте пользователям запрашивать либо одну метрику без измерений, либо несколько метрик с измерениями.
• Контекст и интерпретация — Контекстуализируйте метрики для лучшего анализа; раскрывайте определения, метаданные, происхождение и свежесть.

Управление и отслеживаемость

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

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

• Выравнивание временных рядов и использование metric_time — Убедитесь, что пользователи видят метрики по правильным временным рядам. При отображении графиков метрик использование не по умолчанию измерения временной агрегации может привести к неверным интерпретациям. Хотя пользователи все еще могут группировать по другим временным измерениям, они должны быть осторожны, чтобы не создавать трендовые линии с неправильными временными осями.
  
  При просмотре одной или нескольких метрик пользователи должны использовать metric_time как основное временное измерение, чтобы гарантировать, что они смотрят на правильные временные ряды для метрики(ок).
  
  Таким образом, при создании приложения мы рекомендуем раскрывать metric_time как отдельное, "особое" временное измерение. Это измерение всегда будет согласовываться со всеми метриками и будет общим для них. Другие временные измерения все еще могут быть просмотрены и сгруппированы, но наличие четкого разграничения между измерением metric_time и другими временными измерениями проясняет, чтобы люди не путали, как метрики должны быть построены.
  
  Также, когда пользователь запрашивает изменение временной гранулярности для основного временного ряда, запрос, который выполняет ваше приложение, должен использовать metric_time, так как это всегда даст вам правильный срез. В связи с этим мы также настоятельно рекомендуем иметь способ раскрыть, на какое измерение metric_time фактически отображается для пользователей, которые могут быть не знакомы. Наши API позволяют вам получить фактические подлежащие временные измерения, которые составляют metric_time (например, transaction_date), чтобы вы могли раскрыть их для своих пользователей.

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

• Отслеживаемость изменений метрик и измерений — Когда пользователи изменяют названия метрик и измерений для отчетов, важно иметь механизм отслеживания, чтобы связать их с исходным названием метрики.

Обнаруживаемость

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

• Легкие взаимодействия с метриками — Предоставьте пользователям интуитивный подход к:

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

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

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

Организация

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

• Организация измерений — Чтобы помочь нетехническим пользователям лучше понять модель данных, мы рекомендуем организовывать измерения на основе сущности, из которой они произошли. Например, рассмотрите такие измерения, как user__country и product__category.
  
  Вы можете создать группы, извлекая user и product, а затем вложить соответствующие измерения под каждую группу. Таким образом, измерения будут соответствовать сущности или семантической модели, к которой они принадлежат, и сделают их более удобными и доступными для пользователя. Кроме того, мы рекомендуем добавлять параметр label к измерениям, чтобы определить значение, отображаемое в инструментах нижнего уровня.

• Организация метрик — Цель состоит в том, чтобы организовать метрики в иерархию в наших конфигурациях, а не представлять их в длинном списке.
  
  Эта иерархия помогает организовать метрики на основе конкретных критериев, таких как бизнес-единица или команда. Предоставляя эту структурированную организацию, пользователи могут находить и навигировать по метрикам более эффективно, улучшая их общий опыт анализа данных.

• Использование сохраненных запросов — Семантический слой dbt имеет концепцию сохраненных запросов, которая позволяет пользователям предварительно создавать срезы метрик, измерений, фильтров для легкого доступа. Вы должны представить их как объекты первого класса в вашей интеграции. Обратитесь к JDBC и GraphQL API для синтаксиса.

Гибкость запросов

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

• Позвольте переключаться между метриками/измерениями без проблем.

• Будьте ясны в том, какие измерения можно запрашивать с какими метриками, и скрывайте то, что не применимо. (Наши API предоставляют вызовы, чтобы вы могли получить соответствующие измерения для метрик и наоборот).

• Раскрывайте только временные гранулярности (ежемесячно, ежедневно, ежегодно), которые соответствуют доступным метрикам.

  • Например, если модель dbt и ее результирующая семантическая модель имеют ежемесячную гранулярность, убедитесь, что запрос данных с "ежедневной" гранулярностью недоступен для пользователя. Наши API имеют функциональность, которая поможет вам представить правильные гранулярности.

• Мы рекомендуем, чтобы временная гранулярность рассматривалась как общая концепция, специфичная для временного измерения, и что она может быть применена не только к основной агрегации (или metric_time).

  Рассмотрите ситуацию, когда пользователь хочет посмотреть на sales во времени по customer signup month; в этой ситуации возможность применять гранулярности к обоим временным измерениям имеет решающее значение. Наши API включают информацию для получения гранулярностей для основных (metric_time) измерений, а также всех временных измерений.

  Вы можете обрабатывать каждое временное измерение и выбор гранулярности независимо в вашем приложении. Примечание: Изначально, как отправная точка, имеет смысл поддерживать только metric_time или основное временное измерение, но мы рекомендуем расширять это по мере развития вашего решения.

• Вы должны позволить пользователям фильтровать по диапазонам дат и предоставлять календарь и удобные пресеты для фильтрации.

  • Например, последние 30 дней, последняя неделя и так далее.

Контекст и интерпретация

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

• Раскрывайте бизнес-определения метрик, а также логические определения.

• Раскрывайте дополнительную метадату из семантического слоя (меры, параметры типа).

• Используйте Discovery API для улучшения метрики и повышения уверенности в ее точности:

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

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

Прозрачность и использование компиляции

Для прозрачности и дополнительного контекста мы рекомендуем иметь легкий способ для пользователя получить SQL, который генерирует MetricFlow. В зависимости от того, какой API вы используете, вы можете сделать это, используя наш параметр compile. Это невероятно мощно и подчеркивает прозрачность и открытость, особенно для технически подкованных пользователей.

Где фильтры и оптимизация

В случаях, когда наши API поддерживают либо строку, либо список фильтров для where-условия, мы всегда рекомендуем, чтобы ваше приложение использовало список фильтров для получения максимальных преимуществ от pushdown. Строка where может быть более интуитивной для пользователей, пишущих запросы во время тестирования, но она не будет иметь производственных преимуществ списка фильтров в производственной среде.

Понимание этапов интеграции

Это рекомендации о том, как развивать интеграцию с семантическим слоем, а не строгий план действий.

Этап 1 - Основы

• Поддержка и использование JDBC или GraphQL является первым шагом. Обратитесь к API семантического слоя dbt для получения более подробной информации.

Этап 2 - Больше обнаруживаемости и базовые запросы

• Поддержка списка метрик, определенных в проекте
• Список доступных измерений на основе одной или нескольких метрик
• Запрос определенных значений метрик самостоятельно или группировка по доступным измерениям
• Отображение метаданных из Discovery API и другого контекста
• Раскрытие сохраненных запросов, которые являются предварительно созданными метриками, измерениями и фильтрами, которые разработчики семантического слоя создают для облегчения анализа. Вы можете раскрыть их в вашем приложении. Обратитесь к JDBC и GraphQL API для синтаксиса.

Этап 3 - Больше гибкости запросов и улучшенный пользовательский опыт (UX)

• Более продвинутая фильтрация
  • Временные фильтры с хорошими пресетами/календарным UX
  • Фильтрация метрик на предварительно заполненном наборе значений измерений
• Сделайте значения измерений более удобными для пользователя, эффективно организуя их
• Интеллектуальная фильтрация метрик на основе доступных измерений и наоборот

Этап 4 - Более кастомизированный пользовательский интерфейс (UI) / Сотрудничество

• Место, где пользователи могут видеть всю соответствующую информацию о данной метрике
• Организация метрик по иерархии и более продвинутые функции поиска (например, фильтрация по типу метрики или другой метадате)
• Использование и раскрытие большего количества метаданных
• Запрос измерений без метрик и другие более продвинутые функции запроса
• Предложение метрик пользователям на основе команд/идентичности и так далее.

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

• Часто задаваемые вопросы о семантическом слое dbt
• Используйте семантический слой dbt, чтобы узнать о продукте.
• Создайте свои метрики для получения дополнительной информации о MetricFlow и его компонентах.
• Страница интеграций семантического слоя dbt для получения информации о доступных интеграциях партнеров.