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

dbt Copilot доступен в бета-версии

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

Чтобы использовать dbt Copilot, у вас должна быть активная учетная запись dbt Cloud Enterprise, и вы должны либо согласиться использовать ключ OpenAI от dbt Labs, либо предоставить свой собственный ключ Open AI API. Зарегистрируйтесь здесь или свяжитесь с командой по работе с клиентами, чтобы присоединиться к закрытой бета-версии.

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

Представьте семантические модели как узлы, соединенные сущностями в семантическом графе.
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`.	Необязательный	Словарь

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

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

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.

Name

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

Description

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

Model

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

Defaults

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

Entities

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

Primary entity

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.

Этот пример показывает семантическую модель с тремя сущностями и их типами: transaction (первичная), order (внешняя) и user (внешняя).

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

entity:
  - name: transaction
    type: primary
  - name: order
    type: foreign
    expr: id_order
  - name: user
    type: foreign
    expr: substring(id_order FROM 2)

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

Dimensions

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

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

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

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

Для временных групп

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

Measures

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

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

Параметр	Описание	Обязательный	Тип
`name`	Укажите имя для меры, которое должно быть уникальным и не может повторяться во всех семантических моделях вашего проекта dbt.	Обязательный	String
`description`	Описывает вычисляемую меру.	Необязательный	String
`agg`	dbt поддерживает следующие агрегации: `sum`, `max`, `min`, `average`, `median`, `count_distinct`, `percentile` и `sum_boolean`.	Обязательный	String
`expr`	Либо ссылайтесь на существующий столбец в таблице, либо используйте SQL-выражение для создания или вывода нового.	Необязательный	String
`non_additive_dimension`	Неаддитивные измерения могут быть указаны для мер, которые не могут быть агрегированы по определенным измерениям, таким как остатки на банковских счетах, чтобы избежать получения некорректных результатов.	Необязательный	String
`agg_params`	Специфические свойства агрегации, такие как процентиль.	Необязательный	Dict
`agg_time_dimension`	Поле времени. По умолчанию используется стандартное временное измерение агрегации для семантической модели.	Необязательный	String
`label`	Строка, определяющая отображаемое значение в инструментах нижнего уровня. Принимает обычный текст, пробелы и кавычки (например, `orders_total` или `"orders_total"`). Доступно в версии dbt 1.7 или выше.	Необязательный	String
`create_metric`	Создайте `simple` метрику из меры, установив `create_metric: True`. Атрибуты `label` и `description` будут автоматически перенесены в созданную метрику. Доступно в версии dbt 1.7 или выше.	Необязательный	Boolean

Зависимости

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

синтаксисе выбора dbt
Визуализации DAG в dbt-docs и интегрированной среде разработки (IDE).

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

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

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

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

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

Name​

Description​

Model​

Defaults​

Entities​

Primary entity​

Dimensions​

Measures​

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

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