# Часть 19. Семантический слой, метрики и exposures

Семантический слой появляется, когда одни и те же метрики начинают использоваться в
нескольких отчётах, приложениях или командах. До этого момента достаточно
чётких витрин и проверочных фактов. Но если `total_balance_rub`, активное согласие
или `risk_event_count` повторяются ниже по цепочке потребления, их определения нужно
централизовать.

## Что такое метрика

Метрика — это не просто колонка. Это имя, формула, grain, фильтры, свежесть,
владелец и список потребителей. Если два отчёта считают «активных клиентов» по
разным правилам, проблема не в BI-инструменте, а в семантическом контракте.

## dbt semantic models

dbt поддерживает semantic models и metrics, но в учебном треке мы не обязаны
включать полный слой. Сначала нужно записать семантическое намерение:

```markdown
Метрика: active_consent_count
Исходная витрина: mart_open_api_consents
Определение: количество согласий, где `revoked_at is null`
Гранулярность: `scope`
Потребитель: мониторинг Open API
```

После этого можно решать, нужен ли семантический слой dbt или достаточно
документированной витрины.

## Exposures

Exposure показывает, кто читает дата-продукт: `dashboard`, `notebook`, `analysis`,
`ml` или `application` (для API-потребителя используется `application`).
Это важно для дрейфа контракта. Если mart имеет exposure, ломающие изменения должны
уведомлять владельца ниже по цепочке потребления.

## Qwen-запрос

```text
Прочитай витрины и specs.
Найди поля, которые выглядят как общие метрики.
Для каждого предложи определение, grain, владельца, потребителя и проверочный факт.
Не создавай semantic models без подтверждения.
```

## Минимальный выход

Создайте семантический реестр:

```markdown
# Семантический реестр

## total_balance_rub
Определение:
Гранулярность:
Владелец:
Потребители:
Проверка:
```

## Разбор для читателя

Семантический слой стоит вводить не потому, что он есть в современном стеке, а
потому, что без него повторяемые метрики начинают расходиться. Пока витрина
используется одним отчётом, определения можно держать рядом с витриной. Когда то же
поле появляется в нескольких командах, возникает новый контракт: что именно
значит `active_consent_count`, кто владеет определением, какой grain у метрики,
какие фильтры применяются.

Важно не перепутать семантический слой с каталогом красивых имён. Метрика — это не
переименование колонки. Это формула, контекст, ограничения и потребители. Если
одна команда считает активное согласие по `null` в `revoked_at`, а другая
исключает старые согласия по дате, у организации уже две метрики с одним именем.
Проблема возникла не в BI, а в отсутствии явного семантического контракта.

В учебном проекте полный семантический слой можно не включать. Это осознанное
ограничение. Сначала нужно научиться записывать намерение: поле, определение,
grain, владелец, потребители, проверка. Только после этого имеет смысл решать,
достаточно ли Markdown-реестра или нужен dbt semantic model. Иначе команда
получит ещё один слой YAML без согласованного смысла.

Exposures добавляют контур потребителей. Они показывают, кто читает витрину:
`dashboard`, `notebook`, `analysis`, `ml` или `application`. Это влияет на
ломающие изменения. Если у mart нет потребителя, изменение кажется локальным. Если exposure
записан, автор видит, кого затронет переименование поля или смена grain. Так
семантический слой становится частью SDD, а не отдельной витриной терминов.

## Практика

Выберите одну метрику из витрин и заполните семантический реестр. Если не можете
назвать владельца или потребителя, не добавляйте semantic model — сначала уточните
продуктовое обещание.

## Типичная ошибка

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

## Контрольные вопросы

1. Чем метрика отличается от колонки?
2. Когда exposure делает изменение ломающим?
3. Почему семантический слой не стоит включать до появления общих метрик?