# 语义指标

> 在 Apache Ossie 模型里把指标定义一次，然后从 DuckLocal 侧边栏或 ducklocal metrics CLI 运行，编译成一条 DuckDB SELECT。

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

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

指标可以在窗口的侧边栏里运行，也可以在命令行用 `ducklocal metrics` 运行。装了[官方 skill](cli.md#install-the-official-skill) 的 agent 会按指标提问，而不是自己写 SQL。

::: info 0.5.0 新增
语义指标随 [v0.5.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.5.0) 发布。如果 `ducklocal metrics --help` 报错，说明你手上的版本较旧，请先[更新](getting-started.md)。
:::

## 编写模型 {#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`：`to_columns` 是 `to` 的键时为 `many_to_one`，否则为 `unknown`。
- `metrics compile` 打印一个请求对应的 SQL，以及它的列、基础数据集、关联和 SQL 的 `sql_sha256`。不读取任何数据。
- `metrics query` 编译请求，并像 [`ducklocal query`](cli.md#query-options) 那样运行 SQL。它接受 `query` 的 `--database`、`--format` 和 [`--restricted`](agent-workflows.md) 选项，并附上 `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` 来写，并说明这个数字不是模型里的指标。
