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

[Назад к гайдам](https://docs.getdbt.tech/guides.md)

[Menu ]()



## Введение

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

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

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

Изучите наш [курс по семантическому слою dbt](https://learn.getdbt.com/courses/semantic-layer), чтобы узнать, как определять и запрашивать метрики в вашем проекте dbt.

Кроме того, погрузитесь в мини-курсы по запросам к семантическому слою dbt в ваших любимых инструментах: [Tableau](https://courses.getdbt.com/courses/tableau-querying-the-semantic-layer), [Excel](https://learn.getdbt.com/courses/querying-the-semantic-layer-with-excel), [Hex](https://courses.getdbt.com/courses/hex-querying-the-semantic-layer) и [Mode](https://courses.getdbt.com/courses/mode-querying-the-semantic-layer).

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

Чтобы создать интеграцию с Semantic Layer:

* Мы предоставляем [JDBC API](https://docs.getdbt.tech/docs/dbt-apis/sl-jdbc.md) и [GraphQL API](https://docs.getdbt.tech/docs/dbt-apis/sl-graphql.md). Дополнительные технические сведения об интеграции см. в специальном разделе [API Semantic Layer](https://docs.getdbt.tech/docs/dbt-apis/sl-api-overview.md).

* Ознакомьтесь с ключевыми концепциями [Semantic Layer](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/dbt-sl.md) и [MetricFlow](https://docs.getdbt.tech/docs/build/about-metricflow.md). Существует два основных объекта:

  * [Семантические модели](https://docs.getdbt.tech/docs/build/semantic-models.md) — Узлы в вашем семантическом графе, соединенные через сущности как ребра. MetricFlow принимает семантические модели, определенные в YAML-файлах конфигурации, в качестве входных данных и создает семантический граф, который вы можете использовать для запроса метрик.
  * [Метрики](https://docs.getdbt.tech/docs/build/metrics-overview.md) — Могут быть определены в тех же YAML-файлах, что и ваши семантические модели, или разделены на отдельные YAML-файлы в любых других подкаталогах (при условии, что эти подкаталоги также находятся в том же репозитории проекта dbt).

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

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

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

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

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

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

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

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

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

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

* [Управление](#governance-and-traceability) — Рекомендации по установлению ограничений для управляемой работы с данными.
* [Обнаруживаемость](#discoverability) — Рекомендации по созданию удобных для пользователя взаимодействий с данными.
* [Организация](#organization) — Организуйте метрики и измерения для всех аудиторий, используйте [сохраненные запросы](https://docs.getdbt.tech/docs/build/saved-queries.md).
* [Гибкость запросов](#query-flexibility) — Позвольте пользователям запрашивать либо одну метрику без измерений, либо несколько метрик с измерениями.
* [Контекст и интерпретация](#context-and-interpretation) — Контекстуализируйте метрики для лучшего анализа; раскрывайте определения, метаданные, происхождение и свежесть.

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

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

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

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

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

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

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

* Рассмотрите возможность обращения к [метрикам](https://docs.getdbt.tech/docs/build/metrics-overview.md) как к объектам первого класса, а не к мерам. Метрики предлагают более высокий уровень и более контекстуальный способ взаимодействия с данными, снижая нагрузку на конечных пользователей по ручной агрегации данных.

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

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

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

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

### Организация

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

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

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

* **Использование сохраненных запросов** — Семантический слой dbt имеет концепцию [сохраненных запросов](https://docs.getdbt.tech/docs/build/saved-queries.md), которая позволяет пользователям предварительно создавать срезы метрик, измерений, фильтров для легкого доступа. Вы должны представить их как объекты первого класса в вашей интеграции. Обратитесь к [JDBC](https://docs.getdbt.tech/docs/dbt-apis/sl-jdbc.md) и [GraphQL](https://docs.getdbt.tech/docs/dbt-apis/sl-graphql.md) API для синтаксиса.

* **Использование сохранённых запросов** — В Semantic Layer есть концепция [сохранённых запросов](https://docs.getdbt.tech/docs/build/saved-queries.md), которая позволяет пользователям заранее создавать срезы метрик, измерений и фильтров для удобного доступа к ним. В вашей интеграции они должны быть представлены как полноценные объекты. Синтаксис см. в документации API [JDBC](https://docs.getdbt.tech/docs/dbt-apis/sl-jdbc.md) и [GraphQL](https://docs.getdbt.tech/docs/dbt-apis/sl-graphql.md).

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

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

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

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

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

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

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

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

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

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

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

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

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

* Используйте [Discovery API](https://docs.getdbt.tech/docs/dbt-apis/discovery-api.md), чтобы дополнить метрику и повысить доверие к её точности:

  * Проверьте, актуальна ли метрика и когда она обновлялась в последний раз.
  * Добавьте информацию о происхождении данных (lineage), чтобы понять, откуда берётся метрика.

* Используйте [Discovery API](https://docs.getdbt.tech/docs/dbt-apis/discovery-api.md) для улучшения метрики и повышения уверенности в ее точности:

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

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

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

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

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

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

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

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

**Этап 1 — Основы**

* Поддержка и использование [JDBC](https://docs.getdbt.tech/docs/dbt-apis/sl-jdbc.md) или [GraphQL](https://docs.getdbt.tech/docs/dbt-apis/sl-graphql.md) — первый шаг. Дополнительные технические сведения см. в разделе [API Semantic Layer](https://docs.getdbt.tech/docs/dbt-apis/sl-api-overview.md).

**Этап 2 — Расширенные возможности поиска и базовые запросы**

* Поддержка вывода списка метрик, определённых в проекте
* Вывод списка доступных измерений на основе одной или нескольких метрик
* Запрос значений определённых метрик отдельно или с группировкой по доступным измерениям
* Отображение метаданных из [Discovery API](https://docs.getdbt.tech/docs/dbt-apis/discovery-api.md) и другой контекстной информации
* Предоставление доступа к [сохранённым запросам](https://docs.getdbt.tech/docs/build/saved-queries.md) — заранее подготовленным наборам метрик, измерений и фильтров, которые разработчики Semantic Layer создают для упрощения анализа. Вы можете сделать их доступными в своём приложении. Синтаксис см. в документации по API [JDBC](https://docs.getdbt.tech/docs/dbt-apis/sl-jdbc.md) и [GraphQL](https://docs.getdbt.tech/docs/dbt-apis/sl-graphql.md).

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

* Более продвинутая фильтрация

  * Временные фильтры с хорошими пресетами/календарным UX
  * Фильтрация метрик на предварительно заполненном наборе значений измерений

* Сделайте значения измерений более удобными для пользователя, эффективно организуя их

* Интеллектуальная фильтрация метрик на основе доступных измерений и наоборот

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

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

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

* [Часто задаваемые вопросы по Semantic Layer](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/sl-faqs.md)
* [Использование Semantic Layer](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/dbt-sl.md) — чтобы подробнее узнать о продукте.
* [Создание метрик](https://docs.getdbt.tech/docs/build/build-metrics-intro.md) — дополнительная информация о MetricFlow и его компонентах.
* [Страница интеграций Semantic Layer](https://www.getdbt.com/product/semantic-layer-integrations) — информация о доступных партнёрских интеграциях.
