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

Измерения

(Версии dbt: v1.12 и новее)

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

(Версии dbt: v1.12 и новее)

Измерения определяются для столбцов, которым они соответствуют, поэтому для них требуется только 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
(Версии dbt: v1.12 и новее)

Измерения привязаны к первичной сущности семантической модели, в которой они определены.

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: True, чтобы указать, что измерение существует в рамках определённого временного окна. Например, для размерной таблицы, разбитой по датам. Когда вы запрашиваете метрики из разных таблиц, Semantic Layer использует этот параметр, чтобы гарантировать, что к показателям будут корректно присоединены соответствующие размерные значения.

(Версии dbt: v1.12 и новее)
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
(Версии dbt: v1.12 и новее)

Чтобы создать временное измерение на основе 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_keydimensions_1dimensions_2...dimensions_xvalid_fromvalid_to
123value_avalue_x...value_n2024-01-012024-06-30
123value_bvalue_y...value_m2024-07-012024-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 в семантической модели:

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

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

sales_person_idtierstart_dateend_date
11112019-02-032020-01-05
11122020-01-052048-01-01
22222020-03-052048-01-01
33322020-08-192021-10-22
33332021-10-222048-01-01

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

  • is_start
  • is_end

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

(Версии dbt: v1.12 и новее)
models:
- name: sales_person_tiers
semantic_model:
enabled: true

agg_time_dimension: tier_start

# You can use a virtual primary entity name
primary_entity: sales_person

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

- name: tier
dimension:
type: categorical
name: tier

- name: sales_person_id
entity:
type: natural
name: sales_person

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

(Версии dbt: v1.12 и новее)
models:
- name: fct_transactions
semantic_model:
enabled: true

agg_time_dimension: metric_time

columns:
- name: transaction_id
entity:
type: primary
name: transaction_id

- name: customer_id
entity:
type: foreign
name: customer

- name: product_id
entity:
type: foreign
name: product

- name: sales_person_id
entity:
type: foreign
name: sales_person

- name: metric_time
granularity: day
dimension:
type: time
name: metric_time
label: "Date of transaction"
is_partition: true

- name: sales_geo
dimension:
type: categorical
name: sales_geo

metrics:
- name: transactions
type: simple
agg: sum
expr: 1

- name: gross_sales
type: simple
agg: sum
expr: sales_price

- name: sales_persons_with_a_sale
type: simple
agg: count_distinct
expr: sales_person_id

Теперь вы можете обращаться к метрикам в семантической модели 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_idtierstart_dateend_date
11112019-02-032020-01-05
11122020-01-052048-01-01
22222020-03-052048-01-01
33322020-08-192021-10-22
33332021-10-222048-01-01

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

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

# Пользователи платформы dbt
dbt sl query --metrics transactions --group-by metric_time__month,sales_person__tier --order-by metric_time__month,sales_person__tier

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

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

0
Loading