Измерения

Измерения представляют собой неагрегируемые столбцы в вашем наборе данных, которые являются атрибутами, характеристиками или признаками, описывающими или категоризирующими данные. В контексте семантического слоя dbt, измерения являются частью более крупной структуры, называемой семантической моделью. Они создаются вместе с другими элементами, такими как сущности и меры, и используются для добавления деталей к вашим данным. В SQL измерения обычно включаются в предложение group by вашего SQL-запроса.

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

Параметр	Описание	Обязательный	Тип
name	Относится к названию группы, которое будет видно пользователю в инструментах нижнего уровня. Оно также может служить псевдонимом, если имя столбца или ссылка на SQL-запрос отличаются и указаны в параметре expr. Имена измерений должны быть уникальными в пределах семантической модели, но могут быть неуникальными в разных моделях, так как MetricFlow использует соединения для идентификации правильного измерения.	Обязательный	Строка
type	Указывает тип группы, созданной в семантической модели. Существует два типа: - Категориальный: Описывает атрибуты или признаки, такие как география или регион продаж. - Временной: Временные измерения, такие как временные метки или даты.	Обязательный	Строка
type_params	Специфические параметры типа, такие как, например, является ли время основным или используется в качестве раздела.	Обязательный	Словарь
description	Четкое описание измерения.	Необязательный	Строка
expr	Определяет базовый столбец или SQL-запрос для измерения. Если expr не указан, MetricFlow будет использовать столбец с тем же именем, что и группа. Вы можете использовать имя столбца для ввода SQL-выражения.	Необязательный	Строка
label	Определяет отображаемое значение в инструментах нижнего уровня. Принимает обычный текст, пробелы и кавычки (например, orders_total или "orders_total").	Необязательный	Строка

Обратитесь к следующему для полной спецификации измерений:

dimensions:
  - name: Имя группы, которое будет видно пользователю в инструментах нижнего уровня # Обязательный
    type: Категориальный или Временной # Обязательный
    label: Рекомендуется добавить строку, определяющую отображаемое значение в инструментах нижнего уровня. # Необязательный
    type_params: Специфические параметры типа, такие как, например, является ли время основным или используется в качестве раздела # Обязательный
    description: Как всегда # Необязательный
    expr: Имя столбца или выражение. Если не указано, по умолчанию используется имя измерения # Необязательный

Обратитесь к следующему примеру, чтобы увидеть, как измерения используются в семантической модели:

semantic_models:
  - name: transactions
    description: Запись для каждой транзакции, которая происходит. Корзины считаются множественными транзакциями для каждого SKU. 
    model: {{ ref('fact_transactions') }}
    defaults:
      agg_time_dimension: order_date
# --- сущности --- 
  entities: 
    - name: transaction
      type: primary
      ...
# --- меры --- 
  measures: 
      ... 
# --- измерения ---
  dimensions:
    - name: order_date
      type: time
      type_params:
        time_granularity: day
      label: "Дата транзакции" # Рекомендуется добавить метку, чтобы предоставить больше контекста пользователям, использующим данные
      expr: ts
    - name: is_bulk
      type: categorical
      expr: case when quantity > 10 then true else false end
    - name: type
      type: categorical

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

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

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

Типы измерений

В этом разделе более подробно объясняются определения измерений с примерами. Измерения имеют следующие типы:

• Типы измерений
• Категориальные
• Временные
  • SCD Тип II
    • Основная структура
    • Параметры и ключи семантической модели
    • Реализация
    • Примеры SCD

Категориальные

Категориальные измерения используются для группировки метрик по различным атрибутам, характеристикам или признакам, таким как тип продукта. Они могут ссылаться на существующие столбцы в вашей модели dbt или вычисляться с использованием SQL-выражения с параметром expr. Примером категориального измерения является is_bulk_transaction, которое создается путем применения оператора case к базовому столбцу quantity. Это позволяет пользователям группировать или фильтровать данные на основе массовых транзакций.

dimensions: 
  - name: is_bulk_transaction
    type: categorical
    expr: case when quantity > 10 then true else false end

Временные

Временные измерения имеют дополнительные параметры, указанные в разделе type_params. Когда вы запрашиваете одну или несколько метрик, временное измерение агрегации для каждой метрики по умолчанию является временным измерением агрегации, которое вы можете назвать metric_time или использовать имя измерения.

Вы можете использовать несколько временных групп в отдельных метриках. Например, метрика users_created использует created_at, а метрика users_deleted использует deleted_at:

# пользователи dbt Cloud
dbt sl query --metrics users_created,users_deleted --group-by metric_time__year --order-by metric_time__year

# пользователи dbt Core
mf query --metrics users_created,users_deleted --group-by metric_time__year --order-by metric_time__year

Вы можете установить is_partition для времени, чтобы определить конкретные временные интервалы. Кроме того, используйте раздел type_params, чтобы установить time_granularity для настройки деталей агрегации (ежедневно, еженедельно и т.д.).

is_partition

Используйте is_partition: True, чтобы показать, что измерение существует в определенном временном окне. Например, таблица измерений с разделением по дате. Когда вы запрашиваете метрики из разных таблиц, семантический слой dbt использует этот параметр, чтобы гарантировать, что правильные значения измерений соединяются с мерами.

dimensions: 
  - name: created_at
    type: time
    label: "Дата создания"
    expr: ts_created # ts_created - это базовое имя столбца из таблицы 
    is_partition: True
    type_params:
      time_granularity: day
  - name: deleted_at
    type: time
    label: "Дата удаления"
    expr: ts_deleted # ts_deleted - это базовое имя столбца из таблицы
    is_partition: True 
    type_params:
      time_granularity: day

measures:
  - name: users_deleted
    expr: 1
    agg: sum
    agg_time_dimension: deleted_at
  - name: users_created
    expr: 1
    agg: sum

time_granularity

SCD Тип II

предупреждение

В настоящее время семантические модели с измерениями SCD Типа II не могут содержать меры.

MetricFlow поддерживает соединения с значениями измерений в семантической модели, построенной на основе таблицы медленно изменяющихся измерений (SCD) Типа II. Это полезно, когда вам нужна определенная метрика, разбитая по группе, которая меняется со временем, например, исторические тенденции продаж по стране клиента.

Основная структура

SCD Тип II - это группы, которые изменяют значения на более грубой временной зернистости. Таблицы SCD Типа II обычно имеют два временных столбца, которые указывают период действия измерения: valid_from (или tier_start) и valid_to (или tier_end). Это создает диапазон действительных строк с различными значениями измерений для метрики или меры.

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

MetricFlow поддерживает следующую основную структуру таблицы данных платформы SCD Типа II:

entity_key	dimensions_1	dimensions_2	...	dimensions_x	valid_from	valid_to

• entity_key (обязательно): Уникальный идентификатор для каждой строки в таблице, такой как первичный ключ или другой уникальный идентификатор, специфичный для сущности.
• valid_from (обязательно): Дата начала действия измерения. Используйте validity_params: is_start: True в семантической модели, чтобы указать это.
• valid_to (обязательно): Дата окончания действия измерения. Используйте validity_params: is_end: True в семантической модели, чтобы указать это.

Параметры и ключи семантической модели

При настройке таблицы SCD Типа II в семантической модели используйте validity_params, чтобы указать начало (valid_from) и конец (valid_to) периода действия для каждого измерения.

• validity_params: Параметры, определяющие период действия.
  • is_start: True: Указывает начало периода действия. Отображается как valid_from в таблице SCD.
  • is_end: True: Указывает конец периода действия. Отображается как valid_to в таблице SCD.

Вот пример конфигурации:

- name: tier_start # Имя измерения.
  type: time # Тип измерения (например, временной)
  label: "Дата начала уровня" # Читаемая метка для измерения
  expr: start_date # Выражение или имя столбца, которое представляет измерение
  type_params: # Дополнительные параметры для типа измерения
    time_granularity: day # Указывает зернистость временного измерения (например, день)
    validity_params: # Определяет период действия
      is_start: True # Указывает начало периода действия. 
- name: tier_end 
  type: time
  label: "Дата окончания уровня"
  expr: end_date
  type_params:
    time_granularity: day
    validity_params:
      is_end: True # Указывает конец периода действия.

Таблицы SCD Типа II имеют специфическое измерение с датой начала и окончания. Чтобы соединить таблицы:

• Установите дополнительный параметр entity type в natural ключ.
• Используйте natural ключ как entity type, что означает, что вам не нужен primary ключ.
• В большинстве случаев таблицы SCD не имеют логически используемого primary ключа, потому что natural ключи сопоставляются с несколькими строками.

Реализация

Вот некоторые рекомендации, которые следует учитывать при реализации таблиц SCD Типа II:

• Таблица SCD должна иметь временные измерения valid_to и valid_from, которые являются логическими конструкциями.
• Свойства valid_from и valid_to должны быть указаны ровно один раз для каждой конфигурации таблицы SCD.
• Свойства valid_from и valid_to не должны использоваться или указываться на одном и том же временном измерении.
• Временные измерения valid_from и valid_to должны охватывать неперекрывающийся период, где одна строка соответствует каждому значению естественного ключа (то есть они не должны перекрываться и должны быть различными).
• Мы рекомендуем определять базовую модель dbt с помощью снимков dbt. Это поддерживает макет таблицы SCD Типа II и гарантирует, что таблица обновляется с последними данными.

Это пример SQL-кода, который показывает, как пример метрики, называемой num_events, соединяется с данными версионных измерений (хранящимися в таблице, называемой scd_dimensions) с использованием первичного ключа, состоящего из столбцов entity_key и timestamp.

select metric_time, dimensions_1, sum(1) as num_events
from events a
left outer join scd_dimensions b
on 
  a.entity_key = b.entity_key 
  and a.metric_time >= b.valid_from 
  and (a.metric_time < b. valid_to or b.valid_to is null)
group by 1, 2

Примеры SCD

Ниже приведены примеры использования таблиц SCD Типа II в семантической модели:

 Измерения SCD для уровней продаж и продолжительности этого уровня.

Этот пример показывает, как создать медленно изменяющиеся измерения (SCD) с использованием семантической модели. Таблица SCD содержит информацию об уровне продавцов и продолжительности этого уровня. Предположим, у вас есть базовая таблица SCD:

sales_person_id	tier	start_date	end_date
111	1	2019-02-03	2020-01-05
111	2	2020-01-05	2048-01-01
222	2	2020-03-05	2048-01-01
333	2	2020-08-19	2021-10-22
333	3	2021-10-22	2048-01-01

Как упоминалось ранее, validity_params включают два важных аргумента, которые указывают столбцы в таблице SCD, отмечающие даты начала и окончания (или временные метки) для каждого уровня или измерения:

• is_start
• is_end

Кроме того, сущность помечена как natural, чтобы отличить ее от primary сущности. В primary сущности каждое значение сущности имеет одну строку. В отличие от этого, natural сущность имеет одну строку для каждой комбинации значения сущности и периода его действия.

semantic_models:
  - name: sales_person_tiers
    description: SCD Тип II таблица уровней для продавцов 
    model: {{ ref('sales_person_tiers') }}
    defaults:
      agg_time_dimension: tier_start

    dimensions:
      - name: tier_start
        type: time
        label: "Дата начала уровня"
        expr: start_date
        type_params:
          time_granularity: day
          validity_params:
            is_start: True
      - name: tier_end 
        type: time
        label: "Дата окончания уровня"
        expr: end_date
        type_params:
          time_granularity: day
          validity_params:
            is_end: True
      - name: tier
        type: categorical

    primary_entity: sales_person

    entities:
      - name: sales_person
        type: natural 
        expr: sales_person_id

Следующий код представляет отдельную семантическую модель, содержащую таблицу фактов для transactions:

semantic_models: 
  - name: transactions 
    description: |
      Каждая строка представляет одну транзакцию.
      Существует идентификатор транзакции, продукта, продавца и клиента для 
      каждой транзакции. Существует только один идентификатор транзакции на 
      транзакцию. `metric_time` или дата отражены в UTC.
    model: {{ ref('fact_transactions') }}
    defaults:
      agg_time_dimension: metric_time

    entities:
      - name: transaction_id
        type: primary
      - name: customer
        type: foreign
        expr: customer_id
      - name: product
        type: foreign
        expr: product_id
      - name: sales_person
        type: foreign
        expr: sales_person_id

    measures:
      - name: transactions
        expr: 1
        agg: sum
      - name: gross_sales
        expr: sales_price
        agg: sum
      - name: sales_persons_with_a_sale
        expr: sales_person_id
        agg: count_distinct

    dimensions:
      - name: metric_time
        type: time
        label: "Дата транзакции"
        is_partition: true
        type_params:
          time_granularity: day
      - name: sales_geo
        type: categorical

Теперь вы можете получить доступ к метрикам в семантической модели transactions, организованным по медленно изменяющемуся измерению tier.

В примере с уровнем продаж, если продавец был на уровне 1 с 2022-03-01 по 2022-03-12, и был повышен до уровня 2 с 2022-03-12, все транзакции за март будут отнесены к уровню 1, так как значение измерения уровня 1 приходит раньше (и является точкой начала по умолчанию), даже если продавец был повышен до уровня 2 2022-03-12.

 Измерения SCD с уровнями продаж и группировкой транзакций по месяцам, когда уровни отсутствуют

Этот пример показывает, как создать медленно изменяющиеся измерения (SCD) с использованием семантической модели. Таблица SCD содержит информацию об уровне продавцов и продолжительности этого уровня. Предположим, у вас есть базовая таблица SCD:

sales_person_id	tier	start_date	end_date
111	1	2019-02-03	2020-01-05
111	2	2020-01-05	2048-01-01
222	2	2020-03-05	2048-01-01
333	2	2020-08-19	2021-10-22
333	3	2021-10-22	2048-01-01

В примере с уровнем продаж, если sales_person_id 456 находится на уровне 2 с 2022-03-08, но для этого человека нет связанного уровня с 2022-03-01 по 2022-03-08, то все транзакции, связанные с sales_person_id 456 за март, будут сгруппированы под 'NA', так как до уровня 2 нет уровня.

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

# пользователи dbt Cloud
dbt sl query --metrics transactions --group-by metric_time__month,sales_person__tier --order-by metric_time__month,sales_person__tier

# пользователи dbt Core
mf query --metrics transactions --group-by metric_time__month,sales_person__tier --order-by metric_time__month,sales_person__tier