跳转至

错误码

所有表面——CLI、REST、MCP、Python——都用同一套结构化错误报告失败。 错误码是稳定 API,错误文本不是:按 code(snake_case)匹配,读 candidates / suggested_retry / hint 来自纠错,不要解析文本。

错误的结构

错误沿流水线分阶段,每个阶段一个错误码枚举:

阶段 何时运行 payload 形态
load 读取模型文件 目前只有文本(无 code)
validate 模型结构检查 {severity, code, location, message}
compile 把模型降解为 IR {code, location, message, candidates?, hint?}
plan 编译指标查询 {code, message, metrics?, candidates?, suggested_retry?, condition?, missing_dimensions?}
execute 在数仓上执行 SQL {code, message, hint?}

可选字段为空时省略,payload 保持紧凑。location 指出该改哪里 (metric 'revenue'、relationships[2].to); candidates 列出错误引用的合法替代;suggested_retry / hint 给出能成功的改写;missing_dimensions 列出查询要补进 group-by 的 dataset.field,和指标目录里 required_dimensions 发布的是同一批。

JSON-path 形式的 location 从根节点的 datasets、relationships 或 metrics 开始。 普通文件加载会先把历史单模型文件转换为新版,再进行校验;文本校验只接受新版。 无法安全覆盖时,加载返回错误并保留原文件。参见 文档格式。

各表面:

  • CLI —— --format json 把错误结构体以 JSON 打到 stderr; validate --format json 在 stdout 输出 {issues, compile_errors, warnings}。退出码:0 成功,1 引擎拒绝(结构化错误),2 用法错误。已知不对称:load 错误和 非 validate 命令下的校验问题只有文本形态。
  • REST 与 MCP —— 同一个 body,外面包一层:{"error": {…}}。MCP 工具失败时把它作为 isError: true 的文本内容返回;MCP 工具参数不合法时返回的是纯文本 schema 错误。
  • Python(dosi_engine)—— ModelError / QueryError / ExecuteError,都有 .code 与 .to_dict();planner 的 suggested_retry 到 Python 侧叫 hint。
{"error": {"code": "unknown_metric",
           "message": "unknown metric \"revenu\"",
           "metrics": ["revenu"],
           "candidates": ["revenue", "order_count", "..."]}}

各命令可能出现的错误码

表面 validate issues compile 错误 plan 错误 execute 错误
CLI validate ✓(issues) ✓(compile_errors) — —
CLI query / explain / list ✓(文本,中止) ✓ ✓ 仅 query --execute
REST POST /v1/validate、MCP validate_model ✓(在 body 中) ✓(在 body 中) — —
REST /v1/query/compile · /explain、MCP compile_sql · explain_query —(模型启动时加载) ✓(惰性编译) ✓ —
REST /v1/query/execute、MCP run_query — ✓ ✓ ✓
Python Engine(...) ModelError("invalid_model") ModelError("compile_error") — —
Python compile_sql / query — — QueryError ExecuteError

服务级错误码(bad_request、unauthorized、forbidden、busy、 internal、timeout)可伴随任意 REST/MCP 调用出现,见 服务级错误码。

模型校验问题

结构检查(dosi validate、POST /v1/validate)。error 使模型无效; warning 不会——模型仍可编译。

错误码 级别 何时触发 修复
unsupported_version error version 不等于本引擎实现的 Apache Ossie 规范版本 按消息中的版本号钉住
duplicate_name error 模型、数据集、字段、指标或关系重名 重命名其一
empty_datasets error 语义模型没有数据集 至少加一个数据集
empty_columns error 关系未声明任何列对 填写 from_columns / to_columns
column_count_mismatch error from_columns 与 to_columns 长度不等 二者按位置配对——改成等长
unknown_dataset error 关系端点引用了未声明的数据集 修正 from: / to: 名称
unknown_column error 关系列不是所在数据集声明的字段 声明该字段或改列名
missing_sql_dialect error(指标)/ warning(字段) 表达式中没有引擎可读取的 SQL 在 expression.sql 中填写可移植的 SQL
self_relationship warning 关系把数据集连到自身 通常是有意的;复查即可
relationship_target_not_unique warning to_columns 不是目标的主键/唯一键——join 可能发散 让 join 指向唯一键;若是有意的事实表配对,声明 cardinality: many_to_many
{"severity": "error", "code": "unknown_dataset",
 "location": "relationships[0].to",
 "message": "relationship \"orders_to_customers\" references unknown dataset \"customers\""}

编译错误

把有效模型降解为 IR(validate 信封中的 compile_errors;查询表面上在模型 首次编译时出现)。全部携带 location;candidates / hint 见备注。

错误码 何时触发 payload 附加
invalid_metric_reference AGG 的参数没有指向数据集级指标,或参数形式不合法 在模型级指标表达式中写 AGG(数据集.指标)
unparseable_expression 表达式不是可解析的 SQL
no_sql_dialect 当前模式找不到可用于该字段或指标的 SQL 在 expression.sql 中填写可移植的 SQL
unknown_dataset SUM(no_such.amount)——限定名不是数据集 candidates:数据集名
unknown_field dataset.field 中数据集没有该字段 candidates:该数据集的字段
unknown_column 裸列在任何数据集都找不到 hint:限定为 dataset.field
ambiguous_column 裸列存在于多个数据集 candidates:限定拼法
not_an_aggregate 指标表达式没有聚合 hint:包一层 SUM(...)
nested_aggregate SUM(MAX(...))
bare_column_in_metric 指标里出现未聚合的列(或纯字面量聚合) hint:对数据集字段聚合
cross_dataset_aggregate 一个聚合混用两个数据集的列 拆开聚合
count_star_needs_dataset 多数据集模型里的裸 COUNT(*) hint:改数键列
unsupported_aggregate SUM/COUNT/COUNT DISTINCT/AVG/MIN/MAX 之外的聚合
multi_column_count_distinct 已声明但目前不会产生
window_in_metric 指标表达式里的窗口函数 hint:在数据集里预计算
subquery_in_metric 指标表达式里的子查询
measure_name_collision 显式(D-MEASURE)度量名冲突:一个聚合有两个显式名字,或一个名字落在两个聚合上(自动生成的名字撞上时会加签名 tag 区分,不再报错) 部分触发点带 hint
metric_reference_cycle D-DERIVE compose 指标互相引用 消息展示环路路径
field_reference_cycle 读取 D-LOD 值的字段互相引用 消息展示环路路径
derive_expression_mismatch 手写 fallback 表达式与 derive 展开不一致 hint
invalid_datus_extension DATUS payload 不合法(v 错、字段引用错等) hint 带文档锚点
unsupported_datus_ext_version payload 的 v 是更新的 major / 低于 1.0 hint 指出支持的 major
datus_ext_key_required requires: [...] 点名了本引擎未实现的键
not_implemented 声明合法但超出当前 derive/window/LOD 范围 hint 带文档锚点

直接或间接查询无效指标时,返回造成问题的原始编译错误码。ossie_code 在三种情况下给出对应的 Ossie 错误:聚合外引用字段为 E_UNAGGREGATED_FINER_GRAIN_REFERENCE,指标表达式使用窗口为 E_DEFERRED_WINDOWED_METRIC,聚合所属的数据集无法确定为 E_AMBIGUOUS_MEASURE_GRAIN。dosi validate 会检查所有指标。

编译警告

非致命:模型编译通过,但并非所有声明都生效。形态 {code, location, message};CLI 在 stderr 打 ! … 且退出码为 0。

错误码 何时触发
ignored_vendor_extension basic 模式忽略了 DATUS 扩展,或数据集级指标在任一模式下忽略扩展并按 Ossie 表达式计算
datus_ext_version_ahead payload 声明了更新的 minor;未知键被丢弃(消息中点名)
datus_ext_key_newer_than_declared 用了比声明的 v 更新的键,但仍被采纳
datus_ext_requires_missing 使用了非空的 time、measure 等 silent 扩展,却未列入 requires;补齐后可防止旧引擎忽略它
compose_no_conformed_dimensions compose 指标的成员没有共同维度——任何查询都无法分组
datus_time_format_misplaced 时间维度的顶层 format 写的是存储布局(%Y%m%d 等);它是展示元数据,已被忽略——布局应写进 time 块(D-FORMAT)
datus_param_unbounded D-PARAM 的 int/float 参数没声明 allowed/min/max
datus_param_unused 声明了却没有任何槽位引用的参数
underdeclared_field (datus 模式,仅 dosi validate)字段没写 is_dimension,但看起来是度量、业务键或没标记的时间列,因而会被当作分组维度推荐
dimension_role_conflict (datus 模式,仅 dosi validate)字段声明了 is_dimension: true,却被某个指标当度量聚合;声明照常生效,消息会点出是哪个指标
datus_param_opaque_token allowed 里的取值经 ASCII 词根消毒后无法区分,其输出列改用 h<hex> 后缀(消息里给出对应关系)
aggregate_field_dropped 字段表达式里有聚合,却没有声明 D-LOD 粒度——字段被丢弃,引用它的地方以 unknown_field 失败
field_dropped_needs_params 字段表达式里的 :name 洞没有该字段自己的 params 声明来填(没有声明,或基础模式)——字段被丢弃,引用它的地方以 unknown_field 失败

查询规划错误

两个查询平面的拒绝:指标平面(dosi query、/v1/query/*、compile_sql / run_query)与明细平面(dosi select、/v1/select/*、compile_select / select)。HTTP 一律 400,例外:not_implemented → 501、 internal → 500。

错误码 何时触发 payload 附加
empty_query 未请求任何指标 candidates:全部指标
dimensions_required 已过期的 attribute 请求没给 dimensions;引擎不猜哪些列能解释这次变化。两个归因工具对同样的请求返回各自的请求错误 metrics、candidates:该指标值得拆解的维度(好的在前)、suggested_retry:可直接粘贴的 dimensions 片段
unknown_metric 指标名不在模型里 metrics、candidates
unknown_dimension group-by 项不是维度 —— 包括写了一个指标名,此时 retry 会告诉你该怎么请求它 candidates 或 suggested_retry
ambiguous_dimension 裸字段存在于多个数据集 candidates:限定拼法
grain_on_non_time_dimension 对非时间字段加 :grain suggested_retry
grain_too_fine 请求的粒度细于存储的 time_granularity;时间范围的边界落在 time.format 列无法细分的周期内部;或窗口查询放宽的边界落在其粒度的分桶内部(窗口) suggested_retry:保留这段不完整周期的边界和舍弃它的边界
duplicate_output_name 两个 group-by 项——或两个指标列——产出同名输出列 suggested_retry
unknown_order_key 排序键既不是指标也不是 group-by 项;列表绑定下的指标名(摊成多列)同码 candidates:可用的键,或各组绑定 + suggested_retry
unsupported_filter where 中包含子查询/窗口、where_sql 引用了 D-FORMAT 编码字段、time_ranges 下直接写了指标名(应写 {metric}__{tag}),或时间范围格式不对 相关时 candidates 列出带 tag 的名字。编码时间字段改用 time_range。
aggregate_in_where where 里出现内联聚合 suggested_retry:声明成指标、加入 metrics,再在 where_sql 里按名引用(过滤条件)
result_filter_metric_not_selected where_sql 引用了查询没有选择的指标;指标条件筛选的是本次查询自己的结果行 metrics、candidates:已选的指标、suggested_retry
result_filter_unprojected where_sql 的同一个子条件既引用指标又引用未分组的字段,没有哪个位置能同时求值两者 suggested_retry:把字段加入分组,或拆成两个子条件
no_join_path 没有数据集能沿多对一同时到达 measure 与全部 group-by,与聚合方式无关;包括两张没有任何关系相连的事实表,以及维度用了两张配对事实表中只有一张能读到的列(这样的 where_sql 条件如果查询里另有部分读得到,报 where_needs_context) metrics、suggested_retry:原因是 D-CONFORM 配对时给出配对提示,否则给出可达的维度或该声明的关系
ambiguous_join_path 存在多条关系路径——语义会不同 candidates:各路径、suggested_retry
fan_out_risk 对重复敏感的聚合跨越会发散的 join:有数据集能同时到达 measure 与全部 group-by,换成对重复不敏感的聚合就能算 metrics、suggested_retry
time_range_needs_dimension 作用域里有多个时间维度,范围目标不明 candidates
no_primary_time_dimension 按 metric_time 分组的指标没有主时间维度;查询里没有任何部分有时间字段可以放时间范围;或窗口跨越日期没有配对的几张事实表 candidates、suggested_retry(窗口的情况:用 D-CONFORM 配对日期)
time_axis_ambiguous 查询的某个部分读的数据集有多个时间字段、又没有声明 time_dimension,统计期没有可落的列 candidates:这些时间字段,suggested_retry
context_unreadable context_filter 的某个条件引用的列,查询里没有任何部分读得到——它什么也筛不了 candidates:查询读的数据集,suggested_retry
where_needs_context where_sql 的一条行条件,查询里有的部分读不到、有的部分读得到:比如只有 fixed 字段读的那张表上的列,或者几个事实表里某一个的列。where_sql 作用于每个指标的行,所以不能成立;context_filter 会作用于每个读得到它的部分 metrics:读不到它的指标,condition,suggested_retry:读得到它的部分
metric_time_conflict 已不再产生:同一底表上时间轴不同的指标现在每条轴一个分支(见语义);保留这个错误码是为了兼容已有客户端
unconformed_dimension 维度在派生指标的 conformed 集合之外 metrics、candidates、suggested_retry
unknown_metric_param params 里的名字既没有被查询的指标声明,也没有被查询读到的固定粒度字段声明 candidates:已声明的名字、suggested_retry
param_out_of_domain 绑定越出参数的类型/取值域、列表为空或有重复、在只允许单值处(归因)传了列表、一组值为空或超过上限,或同一个名字在一个指标上是一组值、在另一个指标上是单个值 metrics、suggested_retry:一段合法的 params
param_expansion_too_large 列表绑定展开超过 64 个输出列 metrics、suggested_retry
unknown_query_key 查询带了它的类型没有定义的键,通常是拼写错误;直接拒绝,不会悄悄丢掉 candidates:查询定义的键、suggested_retry
window_reset_too_fine 窗口 reset 细于查询粒度 suggested_retry
window_offset_misaligned 窗口 offset 移位后落不到所查询粒度的分桶上(在季度或周分桶上移 1 month),每一行都会是 NULL metrics, suggested_retry:能落准的粒度
window_exclude_not_grouped 依赖链上某个窗口 partition.exclude 的维度不在查询的 group_by 里 metrics:依赖链缺维度的那些被请求指标(具体是哪一层在 message 里);candidates:本次查询的维度;missing_dimensions 和 suggested_retry:一次性列出需要补上的全部维度
lod_dimension_not_grouped 细节层次指标写到的维度不在查询的 group_by 里:带键 exclude 排除的维度(不分组就什么也排除不掉),或者带键 fixed 指标的键(必须不带时间粒度分组)。套在这类指标外面的 compose 同样适用 metrics:被请求的指标(具体是哪个声明在 message 里);missing_dimensions 和 suggested_retry:一次性列出需要补上的全部维度
time_axis_not_grouped 依赖链上某个窗口按时间排序、重置或分区,而 group-by 里没有带粒度的时间轴 candidates:时间轴字段和 metric_time;missing_dimensions:时间轴;suggested_retry:要带粒度加上的那一项
dialect_unsupported_window_function 目标方言缺少所需窗口函数 metrics、suggested_retry
unknown_dataset 明细查询的 from 不是任何数据集 candidates:数据集名
unknown_subtype 过滤里的 <Concept> is <Name> 没有指向该概念的任何派生子类型,或指向了当前模式下未映射的那个 candidates:该概念的派生子类型;suggested_retry
detail_fanout 明细查询只能逆着连接方向抵达某数据集,一行根会变成好几行 candidates:反向路径;suggested_retry:应改用的根
metric_in_detail_query 指标出现在明细查询的投影里 metrics、suggested_retry:对应的 dosi query 调用
unknown_relationship 关系前缀引用里有不存在的关系名 candidates:从当前数据集出发的边;suggested_retry
invalid_relationship_path 命名路径接不上、重复访问某数据集,或不从查询的基础数据集出发 candidates:该数据集的出边;suggested_retry
not_implemented 模型层面合法,超出当前引擎范围——包括一次查询用两条路径抵达同一数据集,以及不支持的 LOD 组合(与窗口指标共查、混合不兼容的再聚合粒度) metrics 或 candidates、suggested_retry
internal 引擎不变量被破坏——重试无用;请报 bug

查询告警

能编译通过的查询,也可能和字面意思不一样。结果里带有 warnings (S-FILTER-5);每一条有 code、level、message, 适用时还有它涉及的部分 part、针对的条件 condition,以及怎么改查询的 hint。 warning 表示结果可能答的不是所问的问题;info 只记录条件落在了哪里。

代码 级别 何时出现
context_skipped info;被跳过的是 fixed 字段的汇总、而它读的数据集上有同名列时为 warning,hint 给出写在同名列上的条件 某个部分读不到 context_filter 的某个条件(或钉在它读不到的列上的时间范围),这个条件不约束它
time_axis_missing warning 某个部分的数据集没有时间字段,统计期不约束它
empty_time_window warning 固定粒度汇总的统计期和同一列上的 context_filter 条件没有交集,一天都不剩
where_not_in_lod warning where_sql 的行条件筛了指标汇总的行,但没进查询读到的某个 fixed 字段;这个字段的汇总其实读得到这个条件,而且条件不只落在它的键上。条件只落在这个字段的 base 用自己参数圈定的那一列上时不报
param_window_cut warning 查询给 fixed 字段 base 声明的参数窗口传了值,而统计期或同一列上的 context_filter 日期条件把窗口截掉了一部分。截断来自 context_filter 时,condition 写出那条条件,提示针对它而不是 time_range
lookback_cut warning;不带重置的累计或滑动窗口为 info 上期值或累计窗口沿时间轴往回看,而 where_sql 或 context_filter 在这条时间轴上的条件去掉了它要回看的行。统计期写在 time_range 里时,偏移和带重置的累计窗口会自动扩大扫描范围;不带重置的窗口不论日期写在哪里都只读查询保留的那些期,所以对它只说明从哪一天开始
display_only info 窗口查询里,where_sql 的条件落在窗口要比较的维度上,只决定显示哪些行;排名和占比仍按全部取值计算

条件放在两个位置都合法,只是回答的问题不同,所以这些告警都不会拒绝查询: 排名里,where 问的是在全部取值里排第几,context_filter 问的是在留下的取值里排第几; 对 fixed 字段,where 让它仍按全部行计算,context_filter 让它只按留下的行计算。

典型的自纠错循环:unknown_metric → 从 candidates 里选 → 重试; fan_out_risk → 按 suggested_retry(按可达维度分组,或改成 COUNT DISTINCT/MIN/MAX):

{"code": "fan_out_risk",
 "message": "metric \"store_productivity\" aggregates Sum over dataset \"store\", which has no many→one path to [\"item\"]; evaluating a duplicate-sensitive aggregate (SUM/AVG/COUNT) across that join would double-count rows",
 "metrics": ["store_productivity"],
 "suggested_retry": "group by dimensions reachable from the metric's dataset, or restate the metric with a duplicate-insensitive aggregate (COUNT DISTINCT/MIN/MAX)"}

明细平面的两个循环同理:detail_fanout 直接给出能在正确粒度上回答该问题的 根数据集,ambiguous_join_path 直接给出点名各条候选路径的关系前缀, 两者都可以粘贴进下一次调用。参见查询明细行。

执行错误

在数仓上执行编译出的 SQL(query --execute、/v1/query/execute、 run_query)。形态 {code, message, hint?}。

错误码 HTTP 何时触发
config 400 连接配置有问题(URI 错、DuckDB 文件打不开、驱动选项缺失)
connection 502 数仓不可达
auth 502 凭据被拒
sql_rejected 502 数仓拒绝了 SQL(表缺失、类型错误)——消息内嵌数仓自身的报错
driver 502 连接建立后驱动层失败
timeout 504 语句或服务端执行超时

服务级错误码

dosi-server 在同一信封里追加传输层错误码, {"error": {"code", "message"}}:

错误码 HTTP 何时触发
bad_request 400 JSON body 不合法、方言未知
unauthorized 401 bearer token 缺失/错误
forbidden 403 --disable-execute 下调用执行
busy 429 执行槽位占满(Retry-After: 1)
timeout 504 服务端自身的执行超时
internal 500 意料之外的服务失败

Python 异常

dosi_engine wheel 抛一套异常层级(基类 OsiError,均有 .code 与 .to_dict()):

异常 错误码 说明
ModelError io、parse、ontology、invalid_model、compile_error invalid_model 带 issues;compile_error 带 compile_errors 及首个错误的 candidates/hint;ontology(ontology 无法解析或降低)在消息里列出每条拒绝及其自身的错误码
QueryError 上文全部 plan 错误码,以及归因工具的请求错误 suggested_retry 到达时名为 hint;condition、missing_dimensions 是属性;归因的请求错误带 detail["field_path"]
ExecuteError 上文全部 execute 错误码

编译警告在 Engine(...) 构造时以 Python RuntimeWarning 抛出—— python -W error 可把它们升级为失败。

SQL 生成错误(parse_error、unsupported_aggregate 等)是 planner 与 渲染器之间的内部边界,只会出现在上述 compile 或 plan 错误内部, 不构成独立的用户级契约。

本页每个错误码都有测试钉住:一组负向用例随每次提交运行,逐个核对 每个错误码实际返回的 payload。