Семантические метрики
Семантическая модель один раз фиксирует, что означает число: что считать ошибкой, какие вызовы меняют доступ, как соединяются две таблицы. DuckLocal читает модель из файла Apache Ossie, model.ossie.yaml, и превращает каждый запрос (эти метрики, по этим полям, при этих условиях) в один SELECT DuckDB. Один и тот же запрос к одной и той же модели всегда компилируется в один и тот же SQL, поэтому все графики, ответы и агенты, которые используют error_rate, имеют в виду одно и то же.
Метрику можно запустить из боковой панели окна или командой ducklocal metrics. Агент с официальным навыком спрашивает по метрикам, а не пишет SQL сам.
Новее 0.4.1
Семантические метрики уже в ветке main DuckLocal и войдут в следующий выпуск. В 0.4.1 их нет.
Как написать модель
Положите 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 считает представление events, которое определяет дашборд примера:
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, который не является именем таблицы, отклоняется целиком.
Запуск метрики из боковой панели
На вкладке «Схема» боковой панели под разделом Дашборды есть раздел Метрики. В нём перечислены модели, найденные рядом с недавно открытыми дашбордами:
- Для каждого дашборда DuckLocal ищет
model.ossie.yamlв его папке и до трёх папок выше. Поиск останавливается на папке сducklocal-project.json— признаком переносимого проекта. Модель, найденная от нескольких дашбордов, выводится один раз. - Под каждой моделью — по строке на метрику. Наведите указатель на модель, чтобы увидеть её путь и дашборд, из которого взяты её наборы данных. Наведите на метрику, чтобы увидеть описание и синонимы.
- Метрика, которую нельзя запросить, помечена как недоступна для запроса. Наведите на неё, чтобы узнать причину.
Щёлкните метрику или её кнопку ▶ — DuckLocal скомпилирует её, поместит SQL в активный редактор запросов и выполнит. Кнопка 📈 запускает её с разбивкой по дням, по первому полю времени набора данных, который она считает.
SQL начинается со строки, которая говорит, откуда взялось число, например -- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …). Если наборы данных модели берутся из блоков source и view дашборда, эти блоки ставятся перед запросом как CTE. Тогда запрос выполняется на собственном подключении окна, открыт дашборд или нет, и его можно редактировать, как любой другой запрос.
Запуск метрики из командной строки
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. Он принимает параметры--database,--formatи--restrictedкоманды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
Скомпилированный SQL — это один SELECT по набору данных, который считают метрики. Он соединяется через LEFT JOIN по связям «многие к одному» с каждым набором данных, который называет запрос, поэтому строка без совпадения всё равно учитывается — под NULL. Выходные столбцы называются по полю (ip или event_time_day для шага времени) или по метрике. Если два имени совпадают, они уточняются (events.user_name). Условие по полю попадает в WHERE, условие по метрике — в HAVING. Каждый --where — одно выражение: подзапрос, второй оператор или что-либо вокруг выражения отклоняется.
Когда запрос отклонён
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 | Ошибка в самой модели, как описано в разделе Как написать модель |
Если файл модели не удаётся прочитать, код выхода — 1, kind — model_not_found. Если на вопрос нужно ответить SQL, который модель выразить не может, напишите его через ducklocal query и укажите, что это число не относится к метрикам модели.
