# Измерения

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

Измерения представляют собой неагрегируемые столбцы в вашем наборе данных — атрибуты, признаки или характеристики, которые описывают или классифицируют данные. В контексте Semantic Layer измерения являются частью более крупной структуры, называемой семантической моделью. Они создаются вместе с другими элементами, такими как [сущности](https://docs.getdbt.tech/docs/build/entities.md) и [простые метрики](https://docs.getdbt.tech/docs/build/simple.md), и используются для добавления дополнительных сведений к данным. В SQL измерения обычно включаются в предложение `group by` SQL-запроса.

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

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

примечание

В блоке `dimension` нельзя использовать `expr`. Чтобы определить измерение на основе SQL-выражения, а не отдельного столбца, используйте [`derived_semantics`](#derived_semantics-in-dimensions).

| Параметр                                                               | Описание                                                                                                                                                                                                                                                                                                                                                                                                               | Обязательность                                           | Тип     |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------- |
| `name`                                                                 | Имя измерения, которое будет видно пользователю в инструментах, использующих эти данные. Оно также может служить псевдонимом для производных измерений.<br /><br />Имена измерений должны быть уникальными в пределах семантической модели, но могут повторяться в разных моделях, поскольку MetricFlow использует [соединения](https://docs.getdbt.tech/docs/build/join-logic.md) для определения нужного измерения. | Необязательный (по умолчанию совпадает с именем столбца) | Строка  |
| `type`                                                                 | Указывает тип группировки, создаваемой в семантической модели. Существует два типа:<br /><br />- **Категориальный**: описывает атрибуты или характеристики, например географическое положение или регион продаж.<br />- **Временной**: измерения на основе времени, например временные метки или даты.                                                                                                                 | Обязательный                                             | Строка  |
| `description`                                                          | Понятное описание измерения.                                                                                                                                                                                                                                                                                                                                                                                           | Необязательный                                           | Строка  |
| `label`                                                                | Определяет отображаемое значение в инструментах, использующих эти данные. Допускает обычный текст, пробелы и кавычки (например, `orders_total` или `"orders_total"`).                                                                                                                                                                                                                                                  | Необязательный                                           | Строка  |
| [`meta`](https://docs.getdbt.tech/reference/resource-configs/meta.md) | Задает метаданные ресурса и позволяет организовывать ресурсы. Допускает обычный текст, пробелы и кавычки.                                                                                                                                                                                                                                                                                                              | Необязательный                                           | Словарь |

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

```yaml
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 и новее)

```yaml
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` обязательно.

```yaml
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`. Имя может не соответствовать столбцу таблицы и не влияет на генерацию запросов. Используйте уникальные имена для таких виртуальных первичных сущностей. Ниже показано, как определить первичную сущность:

```yaml
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 детализация модели соответствует этой сущности.

```yaml
models:
  - name: model_without_pk
    semantic_model:
      enabled: true
    primary_entity: order  # "virtual primary entity"
    columns:
      - name: customer_id
        entity: foreign
```

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

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

* [`derived_semantics` в `dimensions`](#derived_semantics-in-dimensions)

* [Типы измерений](#dimensions-types)

* [Категориальные](#categorical)

* [Временные](#time)

  * [SCD типа II](#scd-type-ii)

    * [Базовая структура](#basic-structure)
    * [Параметры и ключи семантической модели](#semantic-model-parameters-and-keys)
    * [Реализация](#implementation)
    * [Примеры SCD](#scd-examples)

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

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

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

Определите категориальное измерение для нужного столбца. Например, столбец `transaction_type` становится измерением, по которому можно группировать или фильтровать метрики:

```yaml
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`](#derived_semantics-in-dimensions) и задайте `expr`. Например, измерение `is_bulk_transaction` вычисляется выражением `CASE` по столбцу `quantity` и позволяет группировать или фильтровать данные по признаку оптовой покупки:

```yaml
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](https://docs.getdbt.tech/docs/build/latest-metrics-spec.md).

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

```bash
# Пользователи 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

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

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

```yaml
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
```

### time\_granularity

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

Параметр `granularity` задаёт детализацию временного измерения. MetricFlow приводит исходный столбец к заданной детализации. Например, при почасовой детализации он округляет метку времени до часа с помощью `date_trunc`. При запросе можно перейти к более крупному интервалу, например от часа к месяцу. Обратный переход невозможен.

Поддерживаемые уровни детализации:

* `nanosecond` (только Snowflake)
* microsecond
* millisecond
* second
* minute
* hour
* day
* week
* month
* quarter
* year

Метрики с разной детализацией можно агрегировать вместе. По умолчанию Semantic Layer возвращает результат на самом крупном уровне. Например, при совместном запросе дневной и месячной метрик результат будет агрегирован по месяцам.

```yaml
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
```

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

Чтобы создать временное измерение на основе SQL-выражения, а не отдельного столбца, определите его в разделе [`derived_semantics`](#derived_semantics-in-dimensions) и добавьте `expr` и `granularity`. Например, `order_month` усекает `ts_created` до месяца:

```yaml
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 и новее)

```yaml
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`](https://docs.getdbt.tech/docs/build/entities.md#entity-types) значение `natural`.
* Используйте ключ `natural` в качестве [типа сущности (`type`)](https://docs.getdbt.tech/docs/build/entities.md#entity-types) — в этом случае ключ `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](https://docs.getdbt.tech/docs/build/snapshots.md). Это поддерживает макет таблицы SCD Типа II и гарантирует, что таблица обновляется с последними данными.

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

```sql
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` сущность имеет одну строку для каждой комбинации значения сущности и периода его действия.

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

```yaml
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 и новее)

```yaml
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\_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 нет уровня.

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

```bash
# Пользователи платформы 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
```
