# Переход на последнюю версию спецификации YAML

Последняя версия спецификации Semantic Layer задаёт открытый стандарт определения метрик и измерений, который работает на разных платформах. Она упрощает создание определений: семантические аннотации размещаются непосредственно в каждой модели, меры заменяются простыми метриками, а часто используемые параметры выносятся в ключи верхнего уровня.

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

Доступность

Последняя версия спецификации YAML поддерживается в следующих средах:

* **dbt platform (v1, канал выпусков Latest)**
* **dbt v2**
* **dbt v1.12**

## Изменения в последней версии спецификации

В этом разделе описаны ключевые обновления последней версии спецификации метрик и приведено сравнение с устаревшей спецификацией.

* [Семантические модели](#semantic-models): определяют бизнес-логику метрик, задавая сущности, измерения и их связь с моделями данных. В новой спецификации `semantic_model` вложен непосредственно в каждую модель в `models:`, а не является ключом верхнего уровня.
* [Сущности и измерения](#entities-and-dimensions): сущности — это люди, места или объекты, по которым вы хотите группировать метрики или выполнять соединения (например, `user_id` или `order_id`), а измерения — атрибуты, используемые для фильтрации данных или получения срезов (например, `status` или `region`). В новой спецификации и те и другие определяются непосредственно в `columns:`.
* [Временное измерение](#time-dimension): временные измерения — это столбцы с датами или временными метками, которые позволяют анализировать метрики во времени (например, `order_date` или `created_at`). В новой спецификации задайте `agg_time_dimension` на уровне модели как временное измерение по умолчанию для всех метрик; при необходимости его можно переопределить для отдельной метрики. Задавайте `granularity` на уровне столбца вместо устаревшего `time_granularity`.
* [Простые метрики](#simple-metrics): метрики, которые напрямую ссылаются на выражение с одним столбцом в семантической модели, без участия дополнительных столбцов. В новой спецификации простые метрики заменяют меры. Для замены мер используйте метрики с `type: simple`, определённые непосредственно в модели.
* [Сложные метрики](#advanced-metrics): метрики, которые объединяют другие метрики или строятся на их основе, например отношения, конверсии или производные вычисления. В новой спецификации определяйте простые метрики внутри модели, а метрики, использующие несколько моделей, — в блоке `metrics` верхнего уровня. Ключ верхнего уровня обязателен для любой метрики, которая зависит от метрик или измерений, определённых в другой семантической модели.
* [`type_params`](#type_params): ключ-обёртка в устаревшей спецификации, содержащий настройки, специфичные для метрики (например, `expr`, `join_to_timespine`). В новой спецификации `type_params` устарел, а эти параметры вынесены в ключи верхнего уровня в определении каждой метрики.

### Семантические модели

Ключ `semantic_model` вложен в `models`.

#### Новая спецификация

```yml
models:
  - name: fct_orders
    semantic_model:
      enabled: true # обязательно
      name: fct_orders_semantic_model # необязательное переопределение; по умолчанию используется значение model.name
```

#### Устаревшая спецификация

```yml
semantic_models:
  - name: orders
     model: ref('orders')
```

Межпроектные ссылки не поддерживаются в последней версии спецификации YAML для Semantic Layer

При использовании [dbt Mesh](https://docs.getdbt.tech/best-practices/how-we-mesh/mesh-1-intro.md) с [Semantic Layer](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/dbt-sl.md) [ссылки на модели из других проектов](https://docs.getdbt.tech/reference/dbt-jinja-functions/ref.md#ref-project-specific-models) поддерживаются только в устаревшей спецификации YAML, где семантические модели определяются как ресурсы верхнего уровня и могут ссылаться на модели из других проектов.

В [последней версии спецификации YAML](https://docs.getdbt.tech/docs/build/latest-metrics-spec.md) семантические модели определяются в YAML-файлах моделей, и межпроектные ссылки пока не поддерживаются. Поддержку этой возможности в последней версии спецификации планируется добавить в одном из будущих выпусков.

### Сущности и измерения

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

#### Новая спецификация

```yml
models:
  - name: orders
    semantic_model:
      enabled: true
    agg_time_dimension: ordered_at
    columns:
      # сущности
      - name: order_id
        entity:
          type: primary
          name: order
      - name: customer_id
        entity:
          type: foreign
          name: customer

      # временное измерение
      - name: ordered_at
        granularity: day
        dimension:
          type: time

      # категориальное измерение
      - name: order_status
        dimension:
          type: categorical
```

#### Устаревшая спецификация

```yml
semantic_models:
  - name: orders
    model: ref('orders')
    entities:
      - name: order
        type: primary
        expr: order_id
      - name: customer
        type: foreign
        expr: customer_id
    dimensions:
      - name: ordered_at
        type: time
        type_params:
          time_granularity: day
      - name: status
        type: categorical
        expr: order_status
```

### Временное измерение

* `agg_time_dimension`: задаётся один раз на уровне модели как временное измерение по умолчанию для всех метрик в этой семантической модели. Его по-прежнему можно переопределить для отдельной метрики с помощью `agg_time_dimension`.
* `time granularity`: устарело в новой спецификации. Задавайте исходную детализацию в столбце временного измерения с помощью `granularity` (например, `hour`, `day`).

#### Новая спецификация

```yml
models:
  - name: subscriptions
    semantic_model:
      enabled: true

    # временное измерение агрегации по умолчанию для метрик этой модели
    agg_time_dimension: activated_at

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

      - name: created_at
        granularity: hour # другой временной столбец с иной исходной детализацией
        dimension:
          type: time

    metrics:
      - name: active_subscriptions
        type: simple
        agg: count
        expr: 1 # наследует agg_time_dimension: activated_at

      - name: signups_by_created_day
        type: simple
        agg: count
        expr: 1
        agg_time_dimension: created_at # переопределение для использования created_at в качестве временного измерения
```

#### Устаревшая спецификация

```yml
semantic_models:
  - name: subscriptions
    model: ref('subscriptions')

    defaults:
      agg_time_dimension: activated_at

    dimensions:
      - name: activated_at
        type: time
        type_params:
          time_granularity: day
      - name: created_at
        type: time
        type_params:
          time_granularity: hour

    measures:
      - name: active_subscriptions
        agg: count

metrics:
  - name: active_subscriptions
    type: simple
    type_params:
      measure: active_subscriptions
```

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

В новой спецификации меры устарели и заменены простыми метриками.

#### Новая спецификация

```yml
models:
  - name: customers
    semantic_model:
      enabled: true
    agg_time_dimension: first_ordered_at
    columns:
      - name: customer_id
        entity:
          name: customer
          type: primary
      - name: first_ordered_at
        dimension:
          type: time
        granularity: day
    metrics:
      - name: lifetime_spend_pretax
        type: simple # простые метрики
        agg: sum
        expr: amount_pretax
```

#### Устаревшая спецификация

```yml
semantic_models:
  - name: customers
    model: ref('customers')
    entities:
      - name: customer
        type: primary
        expr: customer_id
    dimensions:
      - name: first_ordered_at
        type: time
        type_params:
          time_granularity: day
    measures:
      - name: lifetime_spend_pretax
        agg: sum

metrics:
  - name: lifetime_spend_pretax
    type: simple
    type_params:
      measure: lifetime_spend_pretax
```

### Сложные метрики

Определяйте простые метрики внутри модели, а метрики, использующие несколько моделей, — в блоке `metrics` верхнего уровня. Ключ верхнего уровня обязателен для любой метрики, которая зависит от метрик или измерений, определённых в другой семантической модели.

#### Новая спецификация

```yml
# определяйте простые метрики там, где находятся данные
models:
  - name: orders
    ...
    semantic_model:
      enabled: true
    metrics:
      - name: orders
        type: simple
        agg: count
        expr: 1

  - name: website
    semantic_model:
      enabled: true
    metrics:
      - name: sessions
        type: simple
        agg: count
        expr: 1

# сложные метрики в ключе metrics верхнего уровня
metrics:
  - name: orders_per_session
    type: ratio
    numerator: orders
    denominator: sessions
```

#### Устаревшая спецификация

```yml
semantic_models:
  - name: orders
    model: ref('orders')
    measures:
      - name: orders
        agg: count
  - name: website
    model: ref('website')
    measures:
      - name: sessions
        agg: count

metrics:
  - name: orders_per_session
    type: ratio
    type_params:
      numerator: { measure: orders }
      denominator: { measure: sessions }
```

### `type_params`

Ключ `type_params` устарел. Следующие ключи теперь задаются непосредственно в определении метрики:

* `expr`
* `percentile`
* `percentile_type`
* `non_additive_dimension: { name, window_agg, group_by }`
* `join_to_timespine`
* `fill_nulls_with`

#### Новая спецификация

```yml
models:
  - name: payments
    semantic_model:
      enabled: true
    metrics:
      - name: revenue_p95
        type: simple
        agg: percentile
        expr: amount
        percentile: 95.0
        percentile_type: discrete
```

#### Устаревшая спецификация

```yml
metrics:
  - name: revenue_p95
    type: simple
    type_params:
      expr: amount
      percentile: 95.0
      percentile_type: discrete
```

Для [производных метрик](https://docs.getdbt.tech/docs/build/derived.md) `type_params.metrics` переименован в `input_metrics`.

#### Новая спецификация

```yaml
metrics:
  - name: d7_booking_change
    description: Разница между текущим числом бронирований и числом бронирований 7 дней назад
    type: derived
    label: Изменение числа бронирований за 7 дней
    expr: current_bookings - bookings_7_days_ago
    input_metrics:
      - name: bookings
        alias: current_bookings
      - name: bookings
        offset_window: 7 days
        alias: bookings_7_days_ago
```

#### Устаревшая спецификация

```yaml
- name: d7_booking_change
  description: Разница между текущим числом бронирований и числом бронирований 7 дней назад
  type: derived
  label: Изменение числа бронирований за 7 дней
  type_params:
    expr: bookings - bookings_7_days_ago
    metrics:
      - name: bookings
        alias: current_bookings
      - name: bookings
        offset_window: 7 days
        alias: bookings_7_days_ago
```

Для [метрик-отношений](https://docs.getdbt.tech/docs/build/ratio.md) `numerator` и `denominator` теперь задаются непосредственно в определении метрики.

#### Новая спецификация

```yaml
metrics:
  - name: conversion_rate
    type: ratio
    numerator: conversions
    denominator: sessions
```

#### Устаревшая спецификация

```yaml
metrics:
  - name: conversion_rate
    type: ratio
    type_params:
      numerator: conversions
      denominator: sessions
```

Для [накопительных метрик](https://docs.getdbt.tech/docs/build/cumulative.md):

* `type_params.measure` переименован в `input_metric` и должен ссылаться на метрику.
* Параметры из `type_params.cumulative_type_params` теперь задаются непосредственно в определении метрики: `window`, `grain_to_date` и `period_agg`.

#### Новая спецификация

```yaml
metrics:
  - name: revenue_mtd_cumulative
    type: cumulative
    input_metric: revenue_daily
    window: 30d
    grain_to_date: month
    period_agg: sum
```

#### Устаревшая спецификация

```yaml
metrics:
  - name: revenue_mtd_cumulative
    type: cumulative
    type_params:
      measure: revenue_daily  
      cumulative_type_params:
        window: 30d
        grain_to_date: month
        period_agg: sum
```

Для [метрик конверсии](https://docs.getdbt.tech/docs/build/conversion.md) следующие параметры из `type_params.conversion_type_params` теперь задаются непосредственно в определении метрики:

* `entity`
* `calculation`
* `base_metric` (ранее `base_measure`)
* `conversion_metric` (ранее `conversion_measure`)
* `constant_properties`

#### Новая спецификация

```yaml
metrics:
  - name: paid_signup_conversion
    type: conversion
    entity: user_id
    calculation: conversion_rate
    base_metric: signups
    conversion_metric: paid_signups
    constant_properties:
      - base_property: plan
        conversion_property: plan
```

#### Устаревшая спецификация

```yaml
metrics:
  - name: paid_signup_conversion
    type: conversion
    type_params:
      conversion_type_params:
        entity: user_id
        calculation: conversion_rate
        base_measure: signups            
        conversion_measure: paid_signups
        constant_properties:
          plan: pro
```

## Переход на последнюю версию спецификации

Проверка YAML в Studio IDE

Studio IDE проверяет YAML-файлы dbt с помощью JSON Schema из проекта [dbt-jsonschema](https://github.com/dbt-labs/dbt-jsonschema). Эти определения согласованы с dbt v2 и применяются ко всем [каналам выпуска dbt platform](https://docs.getdbt.tech/docs/dbt-versions/dbt-release-tracks.md), даже если ваша среда разработки всё ещё работает на dbt v1.

Если Studio IDE помечает ваш YAML как некорректный, но команды dbt выполняются успешно, ориентируйтесь на результаты выполнения. Отправьте примеры в [службу поддержки dbt](mailto:support@getdbt.com) или команде по работе с вашей учётной записью, чтобы схему можно было обновить.

Переведите устаревшие метрики на последнюю версию спецификации YAML с помощью инструмента dbt-autofix в CLI, [расширении dbt для VS Code](https://docs.getdbt.tech/docs/about-dbt-extension.md) или Studio IDE на платформе dbt platform.

примечание

dbt Copilot пока не поддерживает генерацию семантических моделей с использованием последней версии спецификации YAML.

### Совместимость пакетов

Если ваш проект использует пакеты dbt (перечисленные в `packages.yml`), в которых определены метрики или семантические модели, сопровождающий этих пакетов должен обновить их для использования последней версии спецификации YAML.

[Инструмент dbt-autofix](https://github.com/dbt-labs/dbt-autofix) обновляет только файлы в текущем проекте dbt (например, модели, витрины данных и т. д.) и не обновляет установленные пакеты в `dbt_packages/`. Если установленный пакет всё ещё использует устаревшую спецификацию метрик, после миграции dbt может выдавать ошибки разбора или проверки.

Чтобы обновить пакеты, сопровождающему пакета следует:

1. Выполнить `dbt-autofix deprecations --semantic-layer` в репозитории пакета.

2. Проверить изменения, выполнив следующие команды:

* Для пользователей dbt v2 и dbt в dbt platform CLI или локально с корректным файлом [`dbt_cloud.yml`](https://docs.getdbt.tech/reference/dbt_cloud.yml.md):

  ```bash
  dbt parse
  dbt sl validate
  ```

  При локальном использовании `dbt sl validate` команда проверяет локальный семантический манифест, а не манифест платформы. Это означает, что проверка учитывает ваши локальные изменения, ещё не включённые в коммит.

* Для пользователей dbt v2 CLI, не подключённых к платформе dbt и использующих локальный MetricFlow:

  ```bash
  dbt parse
  mf validate-configs
  ```

3. Выпустить новую версию пакета с обновлёнными определениями метрик.

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

* [Использование CLI или расширения VS Code](#using-the-cli-or-vs-code-extension)
* [Использование Studio IDE](#using-the-studio-ide)

### Использование CLI или расширения VS Code

[Инструмент dbt-autofix](https://github.com/dbt-labs/dbt-autofix) преобразует YAML-файлы метрик из устаревшего формата в новейший и создаёт понятный набор изменений для проверки в системе контроля версий. Прежде чем переходить на новую спецификацию с помощью CLI или расширения dbt для VS Code, убедитесь, что установлена последняя версия инструмента autofix.

1. В CLI или расширении VS Code выполните следующую команду:

   ```bash
   dbt-autofix deprecations --semantic-layer
   ```

2. Просмотрите изменения и устраните все отмеченные проблемы.

3. Выполните разбор и проверки:

   ```bash
   dbt parse
   mf validate-configs
   ```

### Использование Studio IDE

Преобразуйте метрики в Studio IDE на платформе dbt platform без необходимости устанавливать инструмент `dbt-autofix`.

1. Перейдите в Studio IDE, нажав **Studio** в левом меню.

2. Прежде чем продолжить, обязательно сохраните свою работу и создайте коммит. Команда autofix может перезаписать все несохранённые изменения.

3. В Studio IDE выполните следующую команду:

   ```bash
   dbt-autofix deprecations --semantic-layer
   ```

4. Нажмите **Commit and sync** в левом верхнем углу Studio IDE, чтобы зафиксировать эти изменения в репозитории проекта.