跳转至

指标归因

看报表时最常遇到的问题是:这个指标为什么变了? Dosi 用两个工具回答,各调用一次:

  • attribute_metrics 按指标的公式拆变化。比如客单价降了 106:收入下降拉低了 731,订单数减少又抬回 624。
  • attribute_dimensions 按一个或多个字段的分组拆变化。同样这 106 里,西区占 262,没有登记地区的订单则往反方向拉了 195。

两个工具都给每一部分一个贡献(effect),各部分贡献加起来正好等于总变化。贡献按 Shapley 值计算:把各部分从基期逐个换成本期,所有换入顺序下这一部分对指标的平均影响。所以比率、乘积、CASE 都只有一种拆法,与先看哪一部分无关。贡献说明一部分对指标的变化起了多大作用,不说明这一部分自己为什么变。

四个入口都提供这两个工具:CLI(dosi attribute-metrics、dosi attribute-dimensions)、REST(POST /v1/query/attribute-metrics、/v1/query/attribute-dimensions)、MCP(attribute_metrics、attribute_dimensions 两个工具)和 Python(Engine.attribute_metrics、Engine.attribute_dimensions)。

快速开始

示例模型的 avg_order_value 是 SUM(orders.amount) / COUNT(orders.order_id)。2025 年 1 月到 2 月,它从 687.36 降到 581.00。先看是公式里的哪一部分造成的:

export DOSI_EXAMPLES=~/.local/share/dosi/examples
duckdb orders.duckdb < "$DOSI_EXAMPLES/orders/seed.sql"
dosi --model "$DOSI_EXAMPLES/orders/model.yaml" --format json attribute-metrics \
  --metric avg_order_value \
  --baseline 2025-01-01..2025-02-01 \
  --current  2025-02-01..2025-03-01 \
  --db orders.duckdb
import os
from dosi_engine import Engine

engine = Engine(os.path.join(os.environ["DOSI_EXAMPLES"], "orders/model.yaml"))
result = engine.attribute_metrics({
    "metric": "avg_order_value",
    "baseline": {"start": "2025-01-01", "end": "2025-02-01"},
    "current":  {"start": "2025-02-01", "end": "2025-03-01"},
}, db_path="orders.duckdb")
curl -s localhost:8080/v1/query/attribute-metrics \
  -H 'content-type: application/json' \
  -d '{"metric": "avg_order_value",
       "baseline": {"start": "2025-01-01", "end": "2025-02-01"},
       "current":  {"start": "2025-02-01", "end": "2025-03-01"}}'
{"name": "attribute_metrics",
 "arguments": {"metric": "avg_order_value",
               "baseline": {"start": "2025-01-01", "end": "2025-02-01"},
               "current":  {"start": "2025-02-01", "end": "2025-03-01"}}}
{
  "schema_version": 3,
  "status": "complete",
  "metric": "avg_order_value",
  "algorithm": "exact_subset",
  "accuracy": "exact",
  "tree": {
    "label": "avg_order_value", "metric": "avg_order_value",
    "expression": "SUM(orders.amount) / COUNT(orders.order_id)",
    "baseline": 687.36, "current": 581.0, "delta": -106.36,
    "effect": -106.36, "share": 1.0,
    "children": [
      {"label": "revenue", "metric": "revenue", "atom": "revenue",
       "expression": "SUM(amount)",
       "baseline": 4811.49, "current": 1743.0, "delta": -3068.49,
       "effect": -730.59, "share": 6.87},
      {"label": "order_count", "metric": "order_count", "atom": "order_count",
       "expression": "COUNT(order_id)",
       "baseline": 7.0, "current": 3.0, "delta": -4.0,
       "effect": 624.24, "share": -5.87}
    ]
  },
  "issues": [],
  "execution": {"queries_executed": 2, "rows_fetched": 2, ...}
}

收入降了三分之二,单看这一项会让客单价降 731。订单数也少了,单看这一项反而让客单价升 624。两者方向相反,所以占比一个大于 1、一个是负数。

再看变化落在哪里。revenue 和 order_count 都是模型里的指标,都可以交给第二个工具,avg_order_value 本身也可以:

dosi --model "$DOSI_EXAMPLES/orders/model.yaml" --format json attribute-dimensions \
  --metric avg_order_value \
  --dimensions customers.region \
  --baseline 2025-01-01..2025-02-01 \
  --current  2025-02-01..2025-03-01 \
  --db orders.duckdb
{
  "status": "complete",
  "metric": "avg_order_value",
  "dimensions": ["customers.region"],
  "tree": {
    "label": "avg_order_value",
    "baseline": 687.36, "current": 581.0, "delta": -106.36, "effect": -106.36,
    "groups_total": 3, "others": null,
    "children": [
      {"label": "west", "key": {"region": "west"},
       "baseline": 1212.0, "current": 62.0, "delta": -1150.0,
       "effect": -262.40, "share": 2.47},
      {"label": "(null)", "key": {"region": null},
       "baseline": 351.50, "current": null, "current_status": "missing_row",
       "delta": null, "effect": 194.73, "share": -1.83},
      {"label": "east", "key": {"region": "east"},
       "baseline": 848.33, "current": 840.5, "delta": -7.83,
       "effect": -38.69, "share": 0.36}
    ]
  },
  "issues": []
}

分组的 baseline、current 是只在这个分组上算出的指标值:西区自己的客单价从 1212 降到 62。它的 effect 是这对整体的影响,即 −262.40。没有地区的订单都在 1 月,2 月没有了,整体客单价因此升了 194.73。三个分组的贡献加起来是 −106.36。

怎么读结果

每个结果都有 schema_version: 3、metric、status、tree、issues 和 execution(发了几条语句、读回多少行、用了多长时间)。

节点。 每个节点都有自己的两期值 baseline、current,两者之差 delta,以及贡献 effect:这个节点对根节点变化的贡献,单位与指标相同。share 是贡献除以根节点的 delta,指标没变时为 null。占比大于 1 或小于 0,说明有其他部分往反方向变。根节点的贡献就是总变化,父节点的贡献等于子节点之和。

指标树(attribute_metrics)。根节点是指标本身。组合指标的子节点是它所依赖的指标和聚合,公式有几层就展开几层。叶子是读取某个聚合的一处位置,带 atom 名称和 binding(数据集、聚合自带的筛选条件、时间轴)。贡献按聚合计算:同一个聚合在几处读取(例如收入既是比率的分子、又是分母的一部分),每处各有一片叶子,它的总贡献是同一 atom 的叶子之和。节点的 metric 是它对应的模型指标;公式中间层为 null,在当前指标里读取方式不同的成员指标也为 null。带 metric 的节点可以交给 attribute_dimensions。

维度树(attribute_dimensions)。根节点是指标本身,下面是第一个字段的各个分组,每个分组下面是它按下一个字段的分组,依次往下。每个分组有 label(取值)和 key(到这一层为止固定的所有字段)。树里最多列出 top_groups 个分组(请求不指定时为 20),按各层贡献的绝对值一起挑,连同它们的上层分组一起返回。每个节点下,groups_total 是它一共有多少个分组,others 合计没有列出的分组(group_count、effect、share)。列出的贡献加上 others 等于这个节点的贡献。不论列不列出,所有分组都参与计算,所以 top_groups 只改变列出哪些,不改变任何数值。

多个维度是一条下钻路径:--dimensions customers.region,orders.status 把每个地区再按状态拆,各地区的贡献与只按 customers.region 拆时相同。要比较两种互不包含的拆法(按地区、按状态),分两次调用。

空值。 值为 null 时旁边会说明原因:baseline_status、current_status 为 null_value(查询结果是 NULL)、missing_row(这一期没有这个分组的行)或 not_defined(分组没有自己的值,比如排名指标的分组没有自己的名次)。它的贡献照常给出。

精确、推导还是采样。 精确的 Shapley 值,参与方(聚合,或同一层的分组)每多一个,求值次数就翻一倍。参与方不超过 20 个时精确计算。超过以后,如果指标的聚合能按分组相加,各分组的贡献由这些合计推导出来,结果仍然精确;否则按参与方的换入顺序采样,直到标准误足够小。accuracy 是 exact、derived(由可加聚合推导)、sampled 或 mixed。采样得到的节点带 uncertainty(sample_stddev、standard_error);名次在误差范围内与相邻分组分不开的分组带 rank_unstable: true。

状态和问题。 status 说的是指标能不能归因,不是调用成没成功:

status 含义
complete 在要求的精度内完成。采样结果也可以是 complete
partial 没有完成:预算用完,或某项检查没通过。哪些结果可用见 issues
not_computable 没有变化可拆:指标在某一期没有值,或在两期之间的某个混合状态下没有值(例如那里的分母为零)
unsupported 引擎不支持,或超出了引擎的上限
invalid_request 目标本身不成立:指标不存在,或参数、条件不被这个指标接受

issues 说明原因,每条有稳定的 code、severity、message,多数还有 suggested_action。状态不是 complete 时,应该报告原因,而不是引用数字。

请求

两个工具接受的都是一个指标查询,只是把一个时期换成两个:

字段
metric 一次调用一个指标
baseline、current 半开区间 {start, end},默认在指标自己的时间轴上;两期写同一个 dimension 可以换时间轴。CLI 写作 --baseline START..END、--current START..END、--time-dimension
where_sql 对字段的条件,与指标查询相同。对指标的条件会被拒绝
context_filter 在聚合之前作用于行的条件
params D-PARAM 参数绑定,每个参数一个值(多选参数是一组值)
group_by 指标按什么粒度计算,见下文
dimensions 仅 attribute_dimensions:按哪些字段拆,写作 dataset.field 或 dataset.field:grain
top_groups 仅 attribute_dimensions:列出多少个分组,1 到 200,默认 20

group_by 不是 dimensions。 dimensions 是按什么拆变化。group_by 用于值依赖分组方式的指标:市场间的排名、占市场合计的比例、比上一期的变化、移动平均。这时要解释的是分组查询结果里的一行,where_sql 要用 字段 = 值 把每个分组字段都固定下来。以按收入给市场排名的指标为例:

{"metric": "market_revenue_rank",
 "group_by": [{"field": "stores.market"}],
 "where_sql": "stores.market = 'east'",
 "baseline": {"start": "2025-01-01", "end": "2025-02-01"},
 "current":  {"start": "2025-02-01", "end": "2025-03-01"}}

普通指标看某一个市场,不需要 group_by,只用 where_sql 选出来即可。带了 group_by 结果也一样,包括某一期这个市场没有数据、分组查询里没有这一行的情况:这一行在这一期的值按没有行来算,计数是 0,求和是 NULL,结果里有一条 no_rows_in_period 说明。有三种情况这一行没有值,返回 undefined_endpoint:指标要读取其他行(排名、占比、窗口);按月分组,而被解释的那个月没有数据;两期都没有这一行。有必填维度的指标,要像查询时一样把这些维度写进 group_by。按时间的窗口指标会读取被解释那一桶之前的几桶,所以每一期都要是窗口粒度的整桶,每期的最后一桶就是被解释的那一桶。

怎么选维度

哪些字段能解释变化是业务问题,所以引擎不替调用方挑。dosi list dimensions --metric <name>(以及 MCP 的 list_dimensions 工具)列出指标能按哪些字段分组,推荐的排在前面;这份清单来自声明还是推断,见 D-DIM。不给维度的调用会以 dimensions_required 拒绝,它的 candidates 就是这份清单去掉时间轴:两期本身已经是时间轴。

请求出错

请求本身不成立时调用直接失败,不发任何语句:

code
invalid_comparison 两期不是同一时间轴上的区间
dimensions_required 没有给维度。candidates 列出这个指标能拆的字段,按推荐程度排序
dimension_repeated 同一个字段写了两次
top_groups_out_of_range top_groups 不在 1 到 200 之间
bad_request 请求里有不认识的字段,或者值的类型不对

错误带 code 和出错的 field_path:CLI 在 stderr 输出 JSON,REST 返回 HTTP 400,MCP 返回工具错误,Python 抛出 QueryError,detail["field_path"] 指出字段。读保护拒绝或数仓出错时,调用失败的方式与指标查询相同。

能归因什么

指标目录按指标、按工具说明模型允许什么:dosi list metrics --format json、GET /v1/metrics 以及 MCP 的 list_metrics、describe_metric 都给每个指标一个 attribution 字段,例如 {"metrics": {"supported": true}, "dimensions": {"supported": false, "code": "insufficient_state", ...}}。attribute_dimensions 只能按一部分字段拆某个指标时,dimensions 按数据集把这些字段逐个列出:{"supported": true, "only_by": [{"name": "orders", "fields": ["region"]}, …]}。目录说支持,调用仍可能因为请求或数据本身被拒绝。

除特别说明外,两个工具都支持:

  • SUM、COUNT、AVG、MIN、MAX、方差、标准差,以及它们之间的四则运算、CASE 和常用数值函数。
  • 派生指标:筛选、任意层的组合、补值,以及跨事实组合(按两个事实共有的维度拆)。
  • 窗口指标:同环比的值、差和比,滑动窗口与累计窗口,占分区合计的比例,以及排名。
  • 细节层次:fixed、include、exclude 指标,以及用作维度或筛选的 fixed 字段。
  • COUNT(DISTINCT x) 用 attribute_dimensions 只能按 x 决定的字段拆:每个 x 只对应这些字段的一个值,没有哪个值会在两个组里重复计数,各组加起来正好是总数。这些字段包括:x 是数据集主键时该数据集的字段,x 经多对一关系通往的数据集的字段,关联关系上与 x 决定的列配对的那一列,以 x 为键、值不会随时期变化的 fixed 字段(时期落不到它的基础指标的行上,或它的键决定了时期落在的时间字段,即默认的那个或请求指定的那个,且计数也按这个字段取期)或读它的字段,以及 determines 声明列出的字段。排名、整分区汇总或偏移读这个计数时也一样:每一行的各组加起来正好是这一行。细节层次读它时不行。目录里的 only_by 会把它们列出来。用 attribute_metrics 则总能拆。其他 DISTINCT 聚合不按维度拆。

结果为 unsupported 或 not_computable 的常见原因:

code 含义 怎么办
insufficient_state 聚合的各组加起来不等于总数:按去重对象决定不了的字段拆去重计数 按问题里建议的字段拆;没有可拆字段时用 attribute_metrics 拆,或者拆它所依赖的指标
no_primary_time_dimension 指标没有可以切出两期的时间字段 需要在模型里给它一个时间字段
target_row_not_fixed 用了 group_by,但 where_sql 没有固定每个分组字段 为每个分组字段加上 字段 = 值
dimension_is_time_axis 按两期所在的时间轴拆 换一个字段拆;各时间桶的比较用查询来做
undefined_counterfactual 两期之间的某个混合状态没有值(例如那里的分母为零) 换比较期,或者把分子、分母分别拆
state_too_large、budget_exceeded 需要的行数或求值次数超过上限 少拆几个维度、收窄 where_sql,或缩短时期
nondeterministic_order row_number、ntile 在目标行处有并列 改用允许并列的排名函数
dimension_not_aligned 同一个分组返回了两次(跨事实指标的多个分支上都有 NULL 键),或者去重计数的某个值落在了两个组里:数据违反了声明,或者某个关联关系有些行没匹配上 用 context_filter 排除这个分组;去重计数则改正声明,或者换一个字段拆

试运行

dry_run(--dry-run、?dry_run=true、dry_run=True)不发任何语句,也不建立连接。它绑定请求,按方言编译一次调用会发的全部语句(方言取 dialect,否则取连接的类型,再否则是 DuckDB;DWS 还需要 dws_mode),并说明在看到数据之前有没有什么会拒绝它:

{
  "dry_run": true,
  "status": "attributable",             // or unsupported / invalid_request
  "algorithm_candidates": ["exact_subset"],
  "evaluations_upper_bound": 6,
  "runtime_checks": ["endpoint_mismatch", "undefined_counterfactual", ...],
  "statements": [{"purpose": "totals", "period": "baseline",
                  "sql": "SELECT CAST(SUM(orders.amount) AS DOUBLE PRECISION) / ..."}, ...],
  "tree": {...}                         // the metric tree, without values
}

runtime_checks 是只有看到数据才能确定的问题代码。试运行不应用 SQL 策略,也不接受策略参数;在 REST 上,即使服务端关闭了执行也能回答试运行。MCP 的两个工具没有试运行:list_metrics 已经说明了指标能否归因。

上限

  • 一次拆分里,每个聚合每期最多取 1 万行。超过时结果是 unsupported,原因为 state_too_large,不给出任何数字。
  • 参与方不超过 20 个时精确计算 Shapley 值;超过后按上文所述推导或采样。
  • 维度树最多列出 200 个分组。
  • 整次调用共用一个超时:Python 是 timeout_secs,REST 和 MCP 是服务端的执行超时。

从 attribute 迁移

原来的单一归因工具已过期,之后会移除:dosi attribute 和 Engine.attribute 会打印过期警告,POST /v1/query/attribute 已标为过期。MCP 的 attribute_metric 已由两个新工具取代。旧结果在新结果里的对应位置:

attribute 现在
total_change 两棵树的根节点
dimension_ranking、top_dimension_values 每个维度调用一次 attribute_dimensions,它的树就是各个分组
比率的 mix_effect、rate_effect attribute_metrics 里分子和分母的贡献
factors、per_member attribute_metrics 的指标树
drill_down.where_sql 分组的 key,写成 字段 = 值 条件
segment_kind: entered / exited baseline_status / current_status: missing_row
strategy: unsupported status: unsupported 及其 issues
NotComputableError、HTTP 422 结果里的 status: not_computable