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

> Определите метрики один раз в модели Apache Ossie и запускайте их из боковой панели DuckLocal или CLI ducklocal metrics — каждый запрос компилируется в один SELECT DuckDB.

Source: https://ducklocal.app/docs/ru/metrics

Семантическая модель один раз фиксирует, что означает число: что считать
ошибкой, какие вызовы меняют доступ, как соединяются две таблицы. DuckLocal
читает модель из файла [Apache Ossie](https://ossie.apache.org/),
`model.ossie.yaml`, и превращает каждый запрос (эти метрики, по этим полям,
при этих условиях) в один `SELECT` DuckDB. Один и тот же запрос к одной и той
же модели всегда компилируется в один и тот же SQL, поэтому все графики,
ответы и агенты, которые используют `error_rate`, имеют в виду одно и то же.

Метрику можно запустить из боковой панели окна или командой
`ducklocal metrics`. Агент с [официальным навыком](cli.md#install-the-official-skill)
спрашивает по метрикам, а не пишет SQL сам.

::: info Новее 0.4.1
Семантические метрики уже в ветке `main` DuckLocal и войдут в следующий
выпуск. В 0.4.1 их нет.
:::

## Как написать модель {#write-a-model}

Положите `model.ossie.yaml` в корень проекта, рядом с его дашбордами или выше.
DuckLocal читает плоскую форму Ossie 0.2:

- `datasets`: у каждого есть `source` (имя таблицы или представления),
  необязательный `primary_key` и `fields`. Поле с пометкой
  `dimension: {is_time: true}` — поле времени.
- `relationships`: `from`, `to`, `from_columns` и `to_columns`.
- `metrics`: в корне модели или внутри набора данных; там они называются
  `dataset.metric`.

Каждое выражение записывается для каждого диалекта SQL. DuckLocal берёт первый
из `DUCKDB`, `OSSIE_SQL_2026` и `ANSI_SQL`, который есть у выражения, и
разбирает его собственным парсером DuckDB. Эта сокращённая модель из
[примера CloudTrail](example-cloudtrail.md) считает представление `events`,
которое определяет дашборд примера:

```yaml
version: 0.2.0.dev0
name: cloudtrail
ai_context:
  instructions: >
    event_time is UTC. A NULL error_code means the call succeeded.
datasets:
- name: events
  source: events
  fields:
  - name: event_time
    expression: {dialects: [{dialect: ANSI_SQL, expression: event_time}]}
    dimension: {is_time: true}
  - name: ip
    expression: {dialects: [{dialect: ANSI_SQL, expression: ip}]}
    dimension: {is_time: false}
    ai_context: {synonyms: [source_ip, address]}
metrics:
- name: event_count
  description: API calls.
  expression: {dialects: [{dialect: ANSI_SQL, expression: COUNT(events.event_time)}]}
- name: error_count
  description: Calls that were refused or failed.
  expression: {dialects: [{dialect: ANSI_SQL, expression: COUNT(events.error_code)}]}
- name: error_rate
  description: The share of calls that were refused or failed.
  expression: {dialects: [{dialect: ANSI_SQL, expression: "error_count * 1.0 / NULLIF(event_count, 0)"}]}
```

Метрику можно построить из других метрик, как `error_rate`. Поле или метрика
без подходящего диалекта или с выражением, которое DuckDB не может разобрать,
выводится вместе с описанием проблемы, а остальная модель продолжает работать.
Модель с повторяющимся именем, связью с несуществующим набором данных или
`source`, который не является именем таблицы, отклоняется целиком.

## Запуск метрики из боковой панели {#sidebar}

На вкладке «Схема» боковой панели под разделом **Дашборды** есть раздел
**Метрики**. В нём перечислены модели, найденные рядом с недавно открытыми
дашбордами:

- Для каждого дашборда DuckLocal ищет `model.ossie.yaml` в его папке и до трёх
  папок выше. Поиск останавливается на папке с `ducklocal-project.json` —
  признаком [переносимого проекта](agent-workflows.md). Модель, найденная от
  нескольких дашбордов, выводится один раз.
- Под каждой моделью — по строке на метрику. Наведите указатель на модель,
  чтобы увидеть её путь и дашборд, из которого взяты её наборы данных.
  Наведите на метрику, чтобы увидеть описание и синонимы.
- Метрика, которую нельзя запросить, помечена как **недоступна для запроса**.
  Наведите на неё, чтобы узнать причину.

Щёлкните метрику или её кнопку ▶ — DuckLocal скомпилирует её, поместит SQL в
активный редактор запросов и выполнит. Кнопка 📈 запускает её с разбивкой по
дням, по первому полю времени набора данных, который она считает.

SQL начинается со строки, которая говорит, откуда взялось число, например
`-- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …)`.
Если наборы данных модели берутся из блоков `source` и `view` дашборда, эти
блоки ставятся перед запросом как CTE. Тогда запрос выполняется на собственном
подключении окна, открыт дашборд или нет, и его можно редактировать, как любой
другой запрос.

## Запуск метрики из командной строки {#cli}

```bash
ducklocal metrics                       # модель в текущей папке
ducklocal metrics compile --metric error_count,event_count --by events.ip \
  --where "events.user_name = 'ci-deploy'"
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data
```

Первый аргумент — файл модели или папка с `model.ossie.yaml`. Без него
используется текущая папка.

- `ducklocal metrics` выводит словарь модели в JSON:
  - `model` с его `sha256` и `ai_context`.
  - Каждую метрику с `description`, `synonyms` и `queryable`. Метрика, которую
    можно запросить, называет свою `base` — набор данных, который она
    считает; у остальных есть `problem` с объяснением причины.
  - Каждое поле в виде `dataset.field`, с `is_time`.
  - Связи, каждую с её `cardinality`: `many_to_one`, если `to_columns` —
    ключ `to`, иначе `unknown`.
- `metrics compile` выводит SQL для запроса вместе с его столбцами, базовым
  набором данных, соединениями и `sql_sha256` этого SQL. Данные не читаются.
- `metrics query` компилирует запрос и выполняет SQL так же, как
  [`ducklocal query`](cli.md#query-options). Он принимает параметры
  `--database`, `--format` и [`--restricted`](agent-workflows.md) команды
  `query` и добавляет объект `semantic` со скомпилированным SQL, запросом и
  `sha256` модели — именно его и следует цитировать. `--views FILE.dash`
  ставит блоки `source` и `view` этого дашборда перед SQL — для моделей, чьи
  наборы данных определены там.

Запрос состоит из:

| Параметр | Значение |
| --- | --- |
| `--metric NAME[,NAME]` | Метрики для вычисления. Можно повторять |
| `--by REF[,REF]` | Поля для разбивки в виде `dataset.field`. Достаточно имени поля, если оно есть только в одном наборе данных. `dataset.field:GRAIN` усекает поле времени до `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter` или `year`. Можно повторять |
| `--where SQL` | Одно условие. Условие по полям фильтрует строки (`WHERE`); условие по именам метрик, например `"error_count > 5"`, фильтрует группы (`HAVING`). Можно повторять; применяются все |
| `--order-by NAME[:desc]` | Выходной столбец или `dataset.field`, из которого он получен. По умолчанию — столбцы `--by` по возрастанию |
| `--limit N` | Не больше N строк |

## Как запрос превращается в SQL {#compiled-sql}

Скомпилированный SQL — это один `SELECT` по набору данных, который считают
метрики. Он соединяется через `LEFT JOIN` по связям «многие к одному» с каждым
набором данных, который называет запрос, поэтому строка без совпадения всё
равно учитывается — под `NULL`. Выходные столбцы называются по полю (`ip` или
`event_time_day` для шага времени) или по метрике. Если два имени совпадают,
они уточняются (`events.user_name`). Условие по полю попадает в `WHERE`,
условие по метрике — в `HAVING`. Каждый `--where` — одно выражение: подзапрос,
второй оператор или что-либо вокруг выражения отклоняется.

## Когда запрос отклонён {#refusals}

DuckLocal отклоняет запрос, на который не может ответить точно, вместо того
чтобы вернуть, возможно, неверное число. При отказе код выхода — 2, а в ошибке
указан `kind`:

| Kind | Причина |
| --- | --- |
| `metric_unknown_name` | Нет метрики или поля с таким именем. `hint` называет ближайшее |
| `metric_fanout` | Поле находится на стороне «многие» связи, и соединение посчитало бы строки несколько раз. Разбивайте по полю собственного набора данных метрики |
| `metric_multi_grain` | Метрики считают разные наборы данных. Запрашивайте каждую отдельно |
| `metric_ambiguous_path`, `metric_no_path` | Модель не задаёт ровно один способ соединить наборы данных |
| `metric_window_unsupported`, `metric_nested_aggregate`, `metric_not_aggregate` | Метрика — оконная функция, содержит вложенные агрегаты или не является агрегатом |
| `metric_no_dialect` | У метрики нет выражения на диалекте, который читает DuckLocal |
| `metric_bad_grain` | Шаг времени запрошен для поля, которое не является полем времени |
| `metric_filter_refused` | `--where` содержит больше одного выражения |
| `metric_missing` | Не указан ни один `--metric` |
| `metric_no_dataset` | Ни одна метрика запроса не читает столбец, поэтому нет набора данных для подсчёта. Уточните агрегат в модели: `COUNT(events.event_id)`, а не `COUNT(*)` |
| `model_invalid` | Ошибка в самой модели, как описано в разделе [Как написать модель](#write-a-model) |

Если файл модели не удаётся прочитать, код выхода — 1, kind —
`model_not_found`. Если на вопрос нужно ответить SQL, который модель выразить
не может, напишите его через `ducklocal query` и укажите, что это число не
относится к метрикам модели.
