# Создание метрик

После создания [семантических моделей](https://docs.getdbt.tech/docs/build/semantic-models.md) можно приступать к добавлению метрик. На этой странице описаны поддерживаемые типы метрик, которые можно добавить в ваш проект dbt.

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

Метрики можно определять в двух местах в YAML-файлах `models`:

* **Внутри семантических моделей** (в `models` -> `semantic_model` -> `metrics`) — для метрик, использующих измерения из одной семантической модели. Рекомендуется для простых метрик.
* **На верхнем уровне** (в отдельном ключе `metrics`) — для расширенных метрик (накопительных, метрик отношения, производных метрик и метрик конверсии), которые ссылаются на метрики из разных семантических моделей. Простые метрики нельзя определять на верхнем уровне.

Определяйте метрики в YAML-файлах вашего проекта dbt, а не в блоке `config` модели.

## Параметры

Ключи параметров метрик:

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

| Параметр      | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Обязательность | Тип    |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------ |
| `name`        | Укажите имя для ссылки на метрику. Это имя должно быть уникальным среди метрик и может состоять из строчных латинских букв, цифр и символов подчёркивания.                                                                                                                                                                                                                                                                                                            | Обязательный   | String |
| `description` | Добавьте описание метрики.                                                                                                                                                                                                                                                                                                                                                                                                                                            | Необязательный | String |
| `type`        | Задайте тип метрики: `conversion`, `cumulative`, `derived`, `ratio` или `simple`.                                                                                                                                                                                                                                                                                                                                                                                     | Обязательный   | String |
| `label`       | Определяет отображаемое значение в инструментах, использующих метрику. Допускает обычный текст, пробелы и кавычки (например, `orders_total` или `"orders_total"`).                                                                                                                                                                                                                                                                                                    | Необязательный | String |
| `config`      | Используйте свойство [`config`](https://docs.getdbt.tech/reference/resource-properties/config.md), чтобы задать настройки метрики. Поддерживаются настройки [`meta`](https://docs.getdbt.tech/reference/resource-configs/meta.md), [`group`](https://docs.getdbt.tech/reference/resource-configs/group.md), [`tags`](https://docs.getdbt.tech/reference/resource-configs/tags.md) и [`enabled`](https://docs.getdbt.tech/reference/resource-configs/enabled.md). | Необязательный | Dict   |
| `filter`      | К метрике любого типа можно добавить строку [фильтра](#filters), чтобы применять фильтры к измерениям, сущностям, временным измерениям или другим метрикам при вычислении метрики. Рассматривайте её как условие WHERE.                                                                                                                                                                                                                                               | Необязательный | String |

### Параметры, зависящие от типа метрики

Для каждого типа метрики предусмотрены дополнительные параметры:

* **Простые метрики**: `agg` (обязательный), `expr`, `percentile`, `percentile_type`, `non_additive_dimension`, `agg_time_dimension`, `join_to_timespine`, `fill_nulls_with`
* **Накопительные метрики**: `input_metric` (обязательный), `window`, `grain_to_date`, `period_agg`
* **Производные метрики**: `expr` (обязательный), `input_metrics` (обязательный)
* **Метрики-отношения**: `numerator` (обязательный), `denominator` (обязательный)
* **Метрики конверсии**: `entity` (обязательный), `calculation` (обязательный), `base_metric` (обязательный), `conversion_metric` (обязательный), `window`, `constant_properties`

Подробную информацию о параметрах, зависящих от типа метрики, см. в следующих разделах, посвящённых каждому типу метрик.

### Пример

Ниже приведён полный пример конфигурации спецификации метрик:

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

models/file\_name.yml

```yaml
models:
  - name: my_model
    semantic_model:
      enabled: true
      name: my_semantic_model
    
    # Define columns, dimensions, entities...
    columns:
      - name: my_column
        # column config...
    
    # Metrics defined within the semantic model
    metrics:
      - name: my_simple_metric
        description: A metric description
        type: simple
        label: My Simple Metric
        agg: sum
        expr: revenue_column  # Optional, defaults to metric name
        config:
          meta:
            owner: "@analytics_team"

# Advanced metrics that reference metrics from different semantic models
metrics:
  - name: my_advanced_cumulative_metric
    type: cumulative
    window: 1 week 
    input_metric: 
      name: my_metric_name_from_another_semantic_model
      filter: my_filter
      alias: my_metric_name_a_week_ago_in_another_semantic_model
```

📹 Узнайте о семантическом слое dbt с помощью видеокурсов по запросу!

Изучите наш [курс по семантическому слою dbt](https://learn.getdbt.com/courses/semantic-layer), чтобы узнать, как определять и запрашивать метрики в вашем проекте dbt.

Кроме того, погрузитесь в мини-курсы по запросам к семантическому слою dbt в ваших любимых инструментах: [Tableau](https://courses.getdbt.com/courses/tableau-querying-the-semantic-layer), [Excel](https://learn.getdbt.com/courses/querying-the-semantic-layer-with-excel), [Hex](https://courses.getdbt.com/courses/hex-querying-the-semantic-layer) и [Mode](https://courses.getdbt.com/courses/mode-querying-the-semantic-layer).

## Гранулярность по умолчанию для метрик

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

Задайте исходную детализацию столбца временного измерения и выбирайте детализацию агрегирования при выполнении запроса.

* Определите детализацию данных в столбце временного измерения с помощью granularity (например, час, день, месяц).
* Метрики наследуют временное измерение для агрегирования по умолчанию, заданное на уровне модели. При необходимости его можно переопределить для отдельной метрики с помощью `agg_time_dimension`.
* При выполнении запроса выбирайте детализацию агрегирования (день/неделя/месяц/год) в BI-инструменте или через [API семантического слоя](https://docs.getdbt.tech/docs/dbt-apis/sl-api-overview.md). Агрегировать данные можно только до уровня детализации, равного исходному уровню столбца или более крупного.

### Пример

* `order_time` хранится с почасовой детализацией.
* Метрика `orders` использует это временное измерение; вы агрегируете её по месяцам при выполнении запроса (а не в спецификации метрики).
* Вторая метрика показывает, как указать другое временное измерение с помощью `agg_time_dimension`.

models/file\_name.yml

```yaml
models:
  - name: orders
    semantic_model:
      enabled: true

    # Временное измерение для агрегирования по умолчанию на уровне модели (необязательно)
    agg_time_dimension: order_time

    columns:
      - name: order_time
        granularity: hour  # Исходная детализация столбца
        dimension:
          type: time

      - name: created_at
        granularity: day
        dimension:
          type: time

    metrics:
      - name: orders
        type: simple
        agg: count
        expr: 1
        # Здесь нет time_granularity. Агрегируйте по месяцам при выполнении запроса.

      - name: orders_by_created_day
        type: simple
        agg: count
        expr: 1
        agg_time_dimension: created_at  # Используйте другое временное измерение для этой метрики
```

## Метрики конверсии

[Метрики конверсии](https://docs.getdbt.tech/docs/build/conversion.md) помогают отслеживать, когда для сущности происходит базовое событие и последующее событие конверсии в рамках заданного временного окна.

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

models/file\_name.yml

```yaml
models:
  - name: my_model
    semantic_model:
      enabled: true
    
    # Define columns, dimensions, entities...
    
    metrics:
      - name: my_conversion_metric
        description: Conversion metric description
        type: conversion
        label: My conversion metric
        entity: my_primary_entity  # Required
        calculation: conversion_rate  # conversion_rate | conversions
        base_metric: simple_metric # Required, must refer to metric name or metric dict
        conversion_metric: my_simple_metric_that_uses_the_other_time_dimension # Required, must refer to metric name or metric dict
        window: 1 week  # Optional time window
        constant_properties:  # Optional
          - base_property: dimension_or_entity_name  # Dimension or entity from base metric's semantic model
            conversion_property: dimension_or_entity_name  # Dimension or entity from conversion metric's semantic model

# For conversion metrics referencing metrics from different semantic models
metrics:
  - name: my_advanced_conversion_metric
    config:
      group: example_group
      tags:
        - example_tag
        - another_tag
      meta:
        owner: "@docs-team"
    type: conversion
    entity: my_primary_entity # required for conversion metrics
    calculation: conversion_rate # conversion_rate | conversions # required for conversion metrics
    base_metric: my_simple_metric # str | metric dict (if filters are needed)
    conversion_metric: my_other_metric_from_another_semantic_model # str | metric dict (if filters are needed)
    window: 1 week # optional, as above
    constant_properties: # optional - DIMENSION OR ENTITY
      - base_property: my_primary_entity # Required. A reference to a dimension/entity of the semantic model linked to the base_metric
        conversion_property: another_semantic_model_categorical_dimension
```

## Накопительные метрики

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

[Кумулятивные метрики](https://docs.getdbt.tech/docs/build/cumulative.md) агрегируют простую метрику за заданный период. Если период не указан, окно будет накапливать простую метрику за весь период, за который имеются данные. Обратите внимание: перед добавлением кумулятивных метрик необходимо создать [модель временной шкалы](https://docs.getdbt.tech/docs/build/metricflow-time-spine.md).

models/file\_name.yml

```yaml
models:
  - name: my_model
    semantic_model:
      enabled: true
    
    # Define columns, dimensions, entities...
    
    metrics:
      - name: active_users
        type: simple
        agg: count_distinct
        expr: user_id
      
      - name: wau_rolling_7
        type: cumulative
        label: Weekly active users
        description: Rolling 7 day window of active users
        input_metric: active_users  # Required - must refer to metric name or dict
        window: 7 days  # Optional - omit for infinite window (all time)
        join_to_timespine: true  # Optional
        fill_nulls_with: 0  # Optional

# For cumulative metrics using metrics from different semantic models
metrics:
  - name: my_advanced_cumulative_metric
    type: cumulative
    label: Advanced cumulative metric
    input_metric:
      name: metric_from_another_model
      filter: "{{ Dimension('entity__dimension') }} > 0"
      alias: filtered_metric
    window: 1 week  # Optional: can specify window OR grain_to_date, not both
    # grain_to_date: month  # Alternative to window
    # period_agg: first  # Optional: first | last | average
```

## Производные метрики

[Производные метрики](https://docs.getdbt.tech/docs/build/derived.md) позволяют выполнять вычисления с использованием других метрик. Например, можно вычислить `gross_profit`, вычтя метрику `cost` из метрики `revenue`, или рассчитать рост, сравнив метрику с её значением за предыдущий период.

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

models/file\_name.yml

```yaml
models:
  - name: my_model
    semantic_model:
      enabled: true
    
    # Define columns, dimensions, entities...
    
    metrics:
      - name: order_total
        type: simple
        agg: sum
        expr: order_amount
      
      - name: order_cost
        type: simple
        agg: sum
        expr: cost_amount
      
      - name: order_gross_profit
        description: Gross profit from each order
        type: derived
        label: Order gross profit
        expr: revenue - cost  # Required for derived metrics
        input_metrics:  # Required for derived metrics
          - name: order_total
            alias: revenue
          - name: order_cost
            alias: cost

# For derived metrics using metrics from different semantic models
metrics:
  - name: my_advanced_derived_metric
    type: derived
    label: Advanced derived metric
    expr: metric_a - metric_b_offset + metric_c  # Required
    input_metrics:  # Required - list of metric names or dicts
      - name: metric_a
        filter: "{{ Dimension('entity__dimension') }} > 10"
      - name: metric_b
        alias: metric_b_offset
        offset_window: 1 week  # Only allowed for derived metrics
      - name: metric_c
        offset_to_grain: month  # Only allowed for derived metrics
```

## Метрики отношения

[Метрики отношения](https://docs.getdbt.tech/docs/build/ratio.md) включают метрику числителя и метрику знаменателя. Строку `filter` можно применить как к числителю и знаменателю одновременно, так и отдельно к числителю или знаменателю.

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

models/file\_name.yml

```yaml
models:
  - name: my_model
    semantic_model:
      enabled: true
    
    # Определите столбцы, измерения, сущности...
    
    metrics:
      - name: cancellations
        type: simple
        agg: sum
      
      - name: transaction_amount
        description: Сумма транзакций
        label: Сумма транзакций
        type: simple
        agg: sum
      
      - name: cancellation_rate
        type: ratio
        label: Доля отмен
        numerator: cancellations  # Может быть строкой или словарём
        denominator: transaction_amount  # Может быть строкой или словарём
        filter: |  # Необязательно — применяется к числителю и знаменателю
          "{{ Dimension('customer__country') }} = 'MX'"
      
      - name: enterprise_cancellation_rate
        type: ratio
        label: Доля отмен для корпоративных клиентов
        numerator:
          name: cancellations
          filter: "{{ Dimension('company__tier') }} = 'enterprise'"  # Необязательно
          alias: enterprise_cancellations  # Необязательно
        denominator: transaction_amount
        filter: |  # Необязательно — применяется к числителю и знаменателю
          {{ Dimension('customer__country') }} = 'MX'

# Для метрик отношения, использующих метрики из разных семантических моделей
metrics:
  - name: my_advanced_ratio_metric
    type: ratio
    label: Расширенная метрика отношения
    numerator:
      name: metric_from_model_a
      filter: "{{ Dimension('entity__dimension') }} > 10"
      alias: filtered_numerator
    denominator:
      name: metric_from_model_b
      filter: "{{ Dimension('entity__dimension') }} < 100"
```

## Простые метрики

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

[Простые метрики](https://docs.getdbt.tech/docs/build/simple.md) напрямую ссылаются на выражение для одного столбца в семантической модели. Простую метрику можно рассматривать как базовый строительный блок для других метрик. Она выполняет агрегацию (например, `sum`, `count`, `average` и т. д.) по одному полю вашей модели.

models/file\_name.yml

```yaml
models:
  - name: my_model
    semantic_model:
      enabled: true
    
    # Define columns, dimensions, entities...
    
    metrics:
      - name: cancellations
        description: The number of cancellations
        type: simple
        label: Cancellations
        agg: sum  # Required: sum | max | min | average | median | count_distinct | percentile | count | sum_boolean
        expr: cancellations_usd  # Optional, defaults to metric name
        join_to_timespine: true  # Optional
        fill_nulls_with: 0  # Optional
        filter: |  # Optional
          {{ Dimension('order__value') }} > 100 and "{{ Dimension('user__acquisition') }} is not null
      
      # Example with percentile aggregation
      - name: order_percentile
        type: simple
        label: Order 95th Percentile
        agg: percentile
        expr: order_value
        percentile: 95.0  # Required if agg is percentile
        percentile_type: discrete  # Required: discrete | continuous
      
      # Example with non-additive dimension
      - name: account_balance
        type: simple
        label: Account balance
        agg: sum
        expr: balance_amount
        non_additive_dimension:
          name: snapshot_date  # Must be a dimension
          window_agg: max  # min | max
          group_by:  # Optional - list of entity names
            - account_id
      
      # Example with config
      - name: revenue
        type: simple
        label: Total revenue
        agg: sum
        expr: revenue_amount
        config:
          meta:
            owner: "@finance_team"
            team: "Revenue analytics"
```

## Фильтры

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

Подробнее см. [Метрики как измерения](https://docs.getdbt.tech/docs/build/ref-metrics-in-filters.md):

models/metrics/file\_name.yml

```yaml
filter: |
  {{ Entity('entity_name') }}

filter: |
  {{ Dimension('primary_entity__dimension_name') }}

filter: |
  {{ TimeDimension('time_dimension', 'granularity') }}

filter: |
 {{ Metric('metric_name', group_by=['entity_name']) }}
```

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

```yaml
filter: |
  {{ TimeDimension('order_date', 'month') }}
```

## Связанная документация

* [Семантические модели](https://docs.getdbt.tech/docs/build/semantic-models.md)
* [Заполнение пустых значений метрик](https://docs.getdbt.tech/docs/build/fill-nulls-advanced.md)
* [Метрики как измерения в фильтрах](https://docs.getdbt.tech/docs/build/ref-metrics-in-filters.md)
