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

Семантические модели

Совет
Используйте dbt Copilot, доступный для аккаунтов dbt Enterprise и Enterprise+, чтобы генерировать semantic models только в Studio IDE.

Семантические модели являются основой для описания данных в MetricFlow, который лежит в основе Semantic Layer:

  • Представьте семантические модели как узлы, соединенные сущностями в семантическом графе.
  • MetricFlow использует YAML-файлы конфигурации для создания этого графа для запросов метрик.
  • Каждая семантическая модель соответствует модели dbt в вашем DAG, требуя уникальной YAML-конфигурации для каждой семантической модели.
  • Вы можете создать несколько семантических моделей из одной модели dbt (SQL или Python), при условии, что каждой семантической модели будет присвоено уникальное имя.
  • Настройте семантические модели в YAML-файле в каталоге вашего проекта dbt. Обратитесь к руководству по лучшим практикам для получения дополнительной информации о структуре проекта.
  • Организуйте их в папке metrics: или в источниках проекта по мере необходимости.
Семантическая модель состоит из различных компонентов: Сущности, Меры и Измерения.Семантическая модель состоит из различных компонентов: Сущности, Меры и Измерения.
📹 Узнайте о семантическом слое dbt с помощью видеокурсов по запросу!

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

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

Здесь мы описываем компоненты семантической модели с примерами:

КомпонентОписаниеОбязательныйТип
NameВыберите уникальное имя для семантической модели. Избегайте использования двойных подчеркиваний (__) в имени, так как они не поддерживаются.ОбязательныйСтрока
DescriptionВключает важные детали в описание.НеобязательныйСтрока
ModelУказывает модель dbt для семантической модели, используя функцию ref.ОбязательныйСтрока
DefaultsЗначения по умолчанию для модели, в настоящее время поддерживается только agg_time_dimension.ОбязательныйСловарь
EntitiesИспользует столбцы из сущностей в качестве ключей соединения и указывает их тип как первичные, внешние или уникальные ключи с помощью параметра type.ОбязательныйСписок
Primary EntityЕсли существует первичная сущность, этот компонент необязателен. Если у семантической модели нет первичной сущности, то это свойство обязательно.НеобязательныйСтрока
DimensionsРазличные способы группировки или разбиения данных для метрики, они могут быть временными или категориальными.ОбязательныйСписок
MeasuresАгрегации, применяемые к столбцам в вашей модели данных. Они могут быть конечной метрикой или использоваться как строительные блоки для более сложных метрик.НеобязательныйСписок
LabelОтображаемое имя для вашего узла семантической модели, измерения, сущности и/или мер.НеобязательныйСтрока
configИспользуйте свойство config для указания конфигураций для вашей метрики. Поддерживает конфигурации meta, group и enabled.НеобязательныйСловарь
Loading table...

Компоненты семантических моделей​

Полная спецификация для семантических моделей приведена ниже:

semantic_models:
  - name: the_name_of_the_semantic_model ## Обязательный
    description: same as always ## Необязательный
    model: ref('some_model') ## Обязательный
    defaults: ## Обязательный
      agg_time_dimension: dimension_name ## Обязательный, если модель содержит меры
    entities: ## Обязательный
      - see more information in entities
    measures: ## Необязательный
      - see more information in the measures section
    dimensions: ## Обязательный
      - see more information in the dimensions section
    primary_entity: >-
      if the semantic model has no primary entity, then this property is required. #Необязательный, если существует первичная сущность, в противном случае Обязательный

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

Следующий пример демонстрирует полную конфигурацию и подробные описания каждого поля:

semantic_models:
  - name: transaction # Семантическая модель с именем Transactions
    model: ref('fact_transactions') # Ссылается на модель dbt с именем `fact_transactions`
    description: "Таблица фактов транзакций на уровне транзакции. Эта таблица содержит одну строку на транзакцию и включает временную метку транзакции."
    defaults:
      agg_time_dimension: transaction_date

    entities: # Сущности, включенные в таблицу, определены здесь. MetricFlow будет использовать эти столбцы в качестве ключей соединения.
      - name: transaction
        type: primary
        expr: transaction_id
      - name: customer
        type: foreign
        expr: customer_id

    dimensions: # Измерения — это качественные значения, такие как имена, даты или географические данные. Они предоставляют контекст для метрик и позволяют "разбивать метрику по группам".
      - name: transaction_date
        type: time
        type_params:
          time_granularity: day

      - name: transaction_location
        type: categorical
        expr: order_country

    measures: # Меры — это столбцы, по которым мы выполняем агрегацию. Меры являются входными данными для метрик.
      - name: transaction_total
        description: "Общая стоимость транзакции."
        agg: sum

      - name: sales
        description: "Общая продажа по транзакции."
        agg: sum
        expr: transaction_total

      - name: median_sales
        description: "Медианная продажа по транзакции."
        agg: median
        expr: transaction_total

  - name: customers # Другая семантическая модель с именем customers.
    model: ref('dim_customers')
    description: "Таблица измерений клиентов."

    entities:
      - name: customer
        type: primary
        expr: customer_id

    dimensions:
      - name: first_name
        type: categorical

Семантические модели поддерживают свойство config meta, group и enabled как в файле схемы, так и на уровне проекта:

  • Конфигурация семантической модели в models/semantic.yml:

    semantic_models:
      - name: orders
        config:
          enabled: true | false
          group: some_group
          meta:
            some_key: some_value

  • Конфигурация семантической модели в dbt_project.yml:

    semantic-models:
      my_project_name:
        +enabled: true | false
        +group: some_group
        +meta:
          some_key: some_value

Для получения дополнительной информации о dbt_project.yml и соглашениях об именах конфигураций, см. страницу справки по dbt_project.yml.

Название​

Определите имя семантической модели. Вы должны задать уникальное имя для семантической модели. Семантический граф будет использовать это имя для идентификации модели, и вы можете обновить его в любое время. Избегайте использования двойных подчеркиваний (__) в имени, так как они не поддерживаются.

Описание​

Включает важные детали в описание семантической модели. Это описание будет в первую очередь использоваться другими участниками конфигурации. Вы можете использовать оператор pipe (|), чтобы включить несколько строк в описание.

Модель​

Укажите модель dbt для семантической модели, используя функцию ref.

Значения по умолчанию​

Значения по умолчанию для семантической модели. В настоящее время только agg_time_dimension. agg_time_dimension представляет собой временные измерения по умолчанию для мер. Это можно переопределить, добавив ключ agg_time_dimension непосредственно к мере - см. Измерения для примеров.

Сущности​

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

Основная сущность​

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

Вы можете определить первичную сущность, используя следующие конфигурации:

semantic_model:
  name: bookings_monthly_source
  description: bookings_monthly_source
  defaults:
    agg_time_dimension: ds
  model: ref('bookings_monthly_source')
  measures:
    - name: bookings_monthly
      agg: sum
      create_metric: true
  primary_entity: booking_id

Вот типы ключей:

  • Primary — Только одна запись на строку в таблице, и она включает каждую запись в платформе данных.
  • Unique — Только одна запись на строку в таблице, но она может содержать подмножество записей в платформе данных. Также могут присутствовать нулевые значения.
  • Foreign — Может иметь ноль, одну или несколько экземпляров одной и той же записи. Также могут присутствовать нулевые значения.
  • Natural — Столбец или комбинация столбцов в таблице, которые уникально идентифицируют запись на основе реальных данных. Например, sales_person_id может служить естественным ключом в таблице измерений sales_person_department.

Измерения​

Измерения — это различные способы организации или просмотра данных. Они фактически являются параметрами группировки для метрик. Например, вы можете группировать данные по таким вещам, как регион, страна или должность.

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

Измерения имеют следующие характеристики:

  • Существует два типа измерений: категориальные и временные. Категориальные измерения предназначены для вещей, которые нельзя измерить в числах, в то время как временные измерения представляют даты и временные метки.
  • Измерения привязаны к первичной сущности семантической модели, в которой они определены. Например, если измерение с именем full_name определено в модели с user в качестве первичной сущности, то full_name относится к сущности user. Чтобы сослаться на это измерение, вы бы использовали полное имя измерения user__full_name.
  • Имена измерений должны быть уникальными в каждой семантической модели с одной и той же первичной сущностью. Имена измерений могут повторяться, если они определены в семантических моделях с другой первичной сущностью.
Для временных групп

Для семантических моделей с мерой вы должны иметь первичную временную группу.

Показатели​

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

Меры имеют различные параметры, которые перечислены в таблице вместе с их описаниями и типами.

ParameterDescriptionRequiredType
nameУкажите имя меры. Оно должно быть уникальным и не может повторяться среди всех семантических моделей в вашем dbt‑проекте.RequiredString
descriptionОписание вычисляемой меры.OptionalString
aggdbt поддерживает следующие агрегатные функции: sum, max, min, average, median, count_distinct, percentile и sum_boolean.RequiredString
exprСсылка на существующий столбец в таблице либо SQL‑выражение для создания или вычисления нового значения.OptionalString
non_additive_dimensionНеаддитивные измерения могут быть заданы для мер, которые нельзя агрегировать по определённым измерениям (например, остатки на банковских счетах), чтобы избежать получения некорректных результатов.OptionalString
agg_paramsПараметры конкретной агрегации, например значение перцентиля.OptionalDict
agg_time_dimensionПоле времени. По умолчанию используется временное измерение агрегации, заданное по умолчанию для семантической модели.OptionalString
labelСтрока, определяющая отображаемое имя в downstream‑инструментах. Поддерживает обычный текст, пробелы и кавычки (например, orders_total или "orders_total"). Доступно в dbt версии 1.7 и выше.OptionalString
create_metricСоздаёт метрику типа simple на основе меры при установке create_metric: True. Атрибуты label и description автоматически наследуются созданной метрикой. Доступно в dbt версии 1.7 и выше.OptionalBoolean
configИспользуйте свойство config для задания конфигураций метрики. Поддерживается свойство meta, вложенное в config.Optional
Loading table...

Зависимости​

Узлы метрик будут отражать зависимости от семантических моделей на основе их мер. Однако зависимости, основанные на фильтрах, не должны отражаться в:

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

  • Метрики типа RATIO и DERIVED должны ссылаться на Metric.type_params.input_metrics.
  • Метрики типа SIMPLE должны ссылаться на Metric.type_params.measure.

Например, когда вы выполняете команду dbt list --select my_semantic_model+, она покажет вам метрики, которые принадлежат указанной семантической модели.

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

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

0
Loading