Перейти к содержимому

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

Семантическая модель один раз фиксирует, что означает число: что считать ошибкой, какие вызовы меняют доступ, как соединяются две таблицы. 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, которое определяет дашборд примера:

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, который не является именем таблицы, отклоняется целиком.

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

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

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

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

Запуск метрики из командной строки ​

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. Он принимает параметры --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 и укажите, что это число не относится к метрикам модели.

Опубликовано под лицензией Apache-2.0.