Измерения
Измерения представляют собой неагрегируемые столбцы в вашем наборе данных — атрибуты, признаки или характеристики, которые описывают или классифицируют данные. В контексте Semantic Layer измерения являются частью более крупной структуры, называемой семантической моделью. Они создаются вместе с другими элементами, такими как сущности и простые метрики, и используются для добавления дополнительных сведений к данным. В SQL измерения обычно включаются в предложение group by SQL-запроса.
Измерения определяются для столбцов, которым они соответствуют, поэтому для них требуется только type. По умолчанию name совпадает с именем столбца и должно быть уникальным в пределах одной семантической модели.
В блоке dimension нельзя использовать expr. Чтобы определить измерение на основе SQL-выражения, а не отдельного столбца, используйте derived_semantics.
| Параметр | Описание | Обязательность | Тип |
|---|---|---|---|
name | Имя измерения, которое будет видно пользователю в инструментах, использующих эти данные. Оно также может служить псевдонимом для производных измерений. Имена измерений должны быть уникальными в пределах семантической модели, но могут повторяться в разных моделях, поскольку MetricFlow использует соединения для определения нужного измерения. | Необязательный (по умолчанию совпадает с именем столбца) | Строка |
type | Указывает тип группировки, создаваемой в семантической модели. Существует два типа: - Категориальный: описывает атрибуты или характеристики, например географическое положение или регион продаж. - Временной: измерения на основе времени, например временные метки или даты. | Обязательный | Строка |
description | Понятное описание измерения. | Необязательный | Строка |
label | Определяет отображаемое значение в инструментах, использующих эти данные. Допускает обычный текст, пробелы и кавычки (например, orders_total или "orders_total"). | Необязательный | Строка |
meta | Задает метаданные ресурса и позволяет организовывать ресурсы. Допускает обычный текст, пробелы и кавычки. | Необязательный | Словарь |
Полная спецификация измерений приведена ниже:
models:
- name: Model name # Required
semantic_model:
enabled: true # bool. Required
columns: # Any column can have either an entity or a dimension, but not both
- name: my_dimension_column # Required
description: Column description # Optional
dimension:
name: my_dimension # Optional, defaults to column name
type: categorical # Required. Accepted values: categorical | time
label: Recommended adding a string that defines the display value in downstream tools # Optional
description: Same as always # Optional, defaults to the column description if not otherwise specified
Следующий пример показывает, как измерения используются в семантической модели:
(Версии dbt: v1.12 и новее)models:
- name: fct_transactions
semantic_model:
enabled: true
name: transactions
agg_time_dimension: order_date
columns:
# --- entities ---
- name: transaction_column
entity:
type: primary
name: transaction
# --- dimensions tied 1:1 to columns ---
- name: another_transaction_column
granularity: day
dimension:
type: time
name: order_date
label: "Date of transaction"
description: "A record for every transaction that takes place. Carts are considered multiple transactions for each SKU."
- name: type
dimension:
type: categorical
name: type
derived_semantics в dimensions
Используйте ключ derived_semantics в YAML-описании модели, когда нужно определить измерение, которое не соответствует напрямую одному физическому столбцу в соотношении 1:1. При использовании derived_semantics поле expr обязательно.
models:
- name: my_model
semantic_model:
enabled: true
...
derived_semantics:
dimensions:
- name: is_bulk
type: categorical
expr: "case when quantity > 10 then true else false end" # Required
Измерения привязаны к первичной сущности семантической модели, в которой они определены.
MetricFlow требует первичную сущность в каждой семантической модели, чтобы имена измерений были уникальными. Если у источника данных нет первичной сущности, задайте ей имя с помощью ключа entity. Имя может не соответствовать столбцу таблицы и не влияет на генерацию запросов. Используйте уникальные имена для таких виртуальных первичных сущностей. Ниже показано, как определить первичную сущность:
models:
- name: bookings_monthly_source
semantic_model:
enabled: true
agg_time_dimension: ds
columns:
# Primary entity
- name: booking_id
entity:
type: primary
name: booking_id
- name: order_date
granularity: day
dimension:
type: time
label: "Date"
metrics:
- name: bookings_monthly
type: simple
agg: sum
Первичную сущность можно объявить, даже если в таблице нет столбца с физическим первичным ключом. Чтобы задать детализацию модели, укажите primary_entity. В новой спецификации YAML детализация модели соответствует этой сущности.
models:
- name: model_without_pk
semantic_model:
enabled: true
primary_entity: order # "virtual primary entity"
columns:
- name: customer_id
entity: foreign
Типы измерений
В этом разделе более подробно объясняются определения измерений с примерами. Измерения имеют следующие типы:
Категориальные
Категориальные измерения используются для группировки метрик по различным атрибутам, признакам или характеристикам, например по типу продукта.
(Версии dbt: v1.12 и новее)Определите категориальное измерение для нужного столбца. Например, столбец transaction_type становится измерением, по которому можно группировать или фильтровать метрики:
models:
- name: fct_transactions
semantic_model:
enabled: true
columns:
- name: transaction_type
dimension:
type: categorical
config:
meta:
usage: "Group transactions by their type, like refund or purchase."
Чтобы вычислить категориальное измерение по SQL-выражению, определите его в derived_semantics и задайте expr. Например, измерение is_bulk_transaction вычисляется выражением CASE по столбцу quantity и позволяет группировать или фильтровать данные по признаку оптовой покупки:
models:
- name: fct_transactions
semantic_model:
enabled: true
derived_semantics:
dimensions:
- name: is_bulk_transaction
type: categorical
expr: "case when quantity > 10 then true else false end"
Временные
(Версии dbt: v1.12 и новее)Временные измерения больше не используют type_params.
- Для измерений, определённых в записи столбца, добавьте
granularityна уровне столбца. - Для производных измерений добавьте
granularityв конфигурацию измерения.
Временное измерение агрегации по умолчанию для семантической модели задаётся свойством agg_time_dimension на верхнем уровне модели. Метрика может переопределить его с помощью собственного свойства agg_time_dimension. Подробнее см. в разделе Миграция на последнюю версию спецификации YAML.
В разных метриках можно использовать несколько временных групп. Например, метрика users_created использует created_at, а метрика users_deleted — deleted_at:
# Пользователи dbt
dbt sl query --metrics users_created,users_deleted --group-by metric_time__year --order-by metric_time__year
# dbt v1 users
mf query --metrics users_created,users_deleted --group-by metric_time__year --order-by metric_time__year
Вы можете задать is_partition для временного измерения, чтобы определить конкретные временные интервалы.
- is_partition
- time_granularity
Используйте is_partition: True, чтобы указать, что измерение существует в рамках определённого временного окна. Например, для размерной таблицы, разбитой по датам. Когда вы запрашиваете метрики из разных таблиц, Semantic Layer использует этот параметр, чтобы гарантировать, что к показателям будут корректно присоединены соответствующие размерные значения.
models:
- name: orders
semantic_model:
enabled: true
agg_time_dimension: created_at
columns:
- name: ts_created
granularity: day
dimension:
type: time
name: created_at
label: "Date of creation"
config:
meta:
notes: "Only valid for orders from 2022 onward"
is_partition: true
- name: ts_deleted
granularity: day
dimension:
type: time
name: deleted_at
label: "Date of deletion"
is_partition: true
metrics:
- name: users_deleted
type: simple
agg: sum
expr: 1
agg_time_dimension: deleted_at
- name: users_created
type: simple
agg: sum
expr: 1
Параметр granularity задаёт детализацию временного измерения. MetricFlow приводит исходный столбец к заданной детализации. Например, при почасовой детализации он округляет метку времени до часа с помощью date_trunc. При запросе можно перейти к более крупному интервалу, например от часа к месяцу. Обратный переход невозможен.
Поддерживаемые уровни детализации:
nanosecond(только Snowflake)- microsecond
- millisecond
- second
- minute
- hour
- day
- week
- month
- quarter
- year
Метрики с разной детализацией можно агрегировать вместе. По умолчанию Semantic Layer возвращает результат на самом крупном уровне. Например, при совместном запросе дневной и месячной метрик результат будет агрегирован по месяцам.
models:
- name: your_model_name
semantic_model:
enabled: true
agg_time_dimension: created_at
columns:
- name: ts_created
granularity: hour
dimension:
type: time
name: created_at
label: "Date of creation"
is_partition: true
- name: ts_deleted
granularity: day
dimension:
type: time
name: deleted_at
label: "Date of deletion"
is_partition: true
metrics:
- name: users_deleted
type: simple
agg: sum
expr: 1
agg_time_dimension: deleted_at
- name: users_created
type: simple
agg: sum
expr: 1
Чтобы создать временное измерение на основе SQL-выражения, а не отдельного столбца, определите его в разделе derived_semantics и добавьте expr и granularity. Например, order_month усекает ts_created до месяца:
models:
- name: orders
semantic_model:
enabled: true
derived_semantics:
dimensions:
- name: order_month
type: time
granularity: month
expr: "date_trunc('month', ts_created)"
SCD типа II
(Версии dbt: v1.12 и новее)Сейчас семантические модели с измерениями 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 |
|---|---|---|---|---|---|---|
| 123 | value_a | value_x | ... | value_n | 2024-01-01 | 2024-06-30 |
| 123 | value_b | value_y | ... | value_m | 2024-07-01 | 2024-12-31 |
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.
Вот пример конфигурации:
(Версии dbt: v1.12 и новее)models:
- name: tiers
semantic_model:
enabled: true
agg_time_dimension: tier_start
columns:
- name: start_date
granularity: day
dimension:
type: time # Тип измерения
name: tier_start # Имя измерения.
label: "Start date of tier" # Понятная подпись для измерения
validity_params: # Определяет период действия
is_start: true # Указывает начало периода действия
- name: end_date
granularity: day
dimension:
type: time
name: tier_end
label: "End date of tier"
validity_params:
is_end: true # Указывает конец периода действия
В таблицах SCD типа II есть специальное измерение с датами начала и окончания действия. Чтобы соединять таблицы:
- Задайте для дополнительного параметра сущности
typeзначениеnatural. - Используйте ключ
naturalв качестве типа сущности (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 в семантической модели: