语义指标
语义模型把一个数字的含义写定一次:什么算错误,哪些调用算权限变更,两张表怎么关联。DuckLocal 从 Apache Ossie 文件 model.ossie.yaml 读取模型,把每个请求(这些指标、按这些字段、在这些条件下)编译成一条 DuckDB SELECT。同一个模型上的同一个请求,总是编译出同样的 SQL,所以每张图表、每个回答、每个用到 error_rate 的 agent,说的都是同一个意思。
指标可以在窗口的侧边栏里运行,也可以在命令行用 ducklocal metrics 运行。装了官方 skill 的 agent 会按指标提问,而不是自己写 SQL。
编写模型
把 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:to_columns是to的键时为many_to_one,否则为unknown。
metrics compile打印一个请求对应的 SQL,以及它的列、基础数据集、关联和 SQL 的sql_sha256。不读取任何数据。metrics query编译请求,并像ducklocal query那样运行 SQL。它接受query的--database、--format和--restricted选项,并附上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 来写,并说明这个数字不是模型里的指标。
