跳转到内容

语义指标 ​

语义模型把一个数字的含义写定一次:什么算错误,哪些调用算权限变更,两张表怎么关联。DuckLocal 从 Apache Ossie 文件 model.ossie.yaml 读取模型,把每个请求(这些指标、按这些字段、在这些条件下)编译成一条 DuckDB SELECT。同一个模型上的同一个请求,总是编译出同样的 SQL,所以每张图表、每个回答、每个用到 error_rate 的 agent,说的都是同一个意思。

指标可以在窗口的侧边栏里运行,也可以在命令行用 ducklocal metrics 运行。装了官方 skill 的 agent 会按指标提问,而不是自己写 SQL。

0.5.0 新增

语义指标随 v0.5.0 发布。如果 ducklocal metrics --help 报错,说明你手上的版本较旧,请先更新。

编写模型 ​

把 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: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 来写,并说明这个数字不是模型里的指标。

基于 Apache-2.0 许可开源发布。