docs: `/analytics/query` 的两处示例用 `measures: ['revenue.sum']` —— 首段不是 cube 名,这条查询今天就答 400

[hotlong]

在实现 #5918(dotted measure 响亮拒收)时顺带查到,先于该 PR 存在,不由它引入。

位置

• content/docs/api/client-sdk.mdx:267 —— client.analytics.query({ cube: 'account', measures: ['revenue.sum', 'count'], … }),以及 :279 的 explain 示例同一拼写;
• content/docs/api/data-api.mdx:338 —— POST /analytics/query 的 Body 示例 {"cube": "account", "measures": ["revenue.sum", "count"], …}。

事实面(实测)

示例里的首段 revenue 不是 cube 名(cube 是 account),所以它不是分析层的 cube 名限定符,而是「点号 + 尾段」。铸造循环取的是尾段:revenue.sum 铸出的是对列 sum 的聚合,不是对 revenue 的 sum。

在含字段探针(getObjectFieldNames)的部署上,这条示例今天就得到:

400 INVALID_FIELD
Measure 'revenue.sum' … aggregates field 'sum', which object 'account' does not have.

即:照文档抄的查询跑不通,而且报错点名的是文档里根本没出现过的 sum。没有探针的部署上则是驱动的 no such column: sum。

想表达的意思显然是「对 revenue 求和」,规范写法是 revenue_sum(后缀约定:_sum / _avg / _min / _max / _count_distinct),或者由 Cube 显式声明一个 measure。

与 #5918 的关系

#5918 的裁决(2026-08-07)把这一类点号 measure 改成点名原拼写的 400。改动之后这条示例仍然是 400,只是消息会明确读成「dotted measure 不支持」——所以文档里这条示例会从「跑不通且报错莫名」变成「明确被拒的写法仍写在文档里」。#5918 的 PR 按 Prime Directive #10 没有顺带改文档(它是独立的、先于该 PR 的文档缺陷,且改的是另一个评审面)。

建议的修法

两处示例把 revenue.sum 改成 revenue_sum(以及 client-sdk.mdx:279 的 explain 示例),并在 data-api.mdx 的 /analytics/query 段落顺带写明:measures 的合法拼写是「对象自己的字段 + 聚合后缀」或 Cube 声明的 measure 名,唯一允许的点号是 cube 名限定符。

查重

搜过本仓 open issue / PR:revenue.sum / client-sdk.mdx + analytics / docs + measures dotted —— 无同题单;#5141 是 report chart 轴标题读 name 而非 label,不同面。objectui / cloud 无影子单。

[claude]

Triage: pm:queue + domain:devx + target:v17.

Verified on origin/main, and the scope is wider than the two sites named. git grep origin/main -- content/docs for the exact string:

file	line	context
content/docs/api/client-sdk.mdx	:267	measures: ['revenue.sum', 'count'] — the query example
content/docs/api/client-sdk.mdx	:279	the explain example, same spelling
content/docs/api/data-api.mdx	:338	POST /analytics/query request body
content/docs/api/data-api.mdx	:355, :356	response rows keyed "revenue.sum"
content/docs/api/data-api.mdx	:360	columns entry { "name": "revenue.sum", … }

The body names three sites; there are six. :355 / :356 / :360 are the response half of the same example — if only the request is corrected to revenue_sum, the page ships a request whose documented response keys no longer match it, which is a worse state than today. The dispatch must cover all six.

Domain: content/docs/** ⇒ domain:devx, by landing site. Docs-only diff; no code, no spec.

Release board (target:v17): criterion ④, in its most literal form — 「照文档抄即失败」. A reader copying the documented /analytics/query example today gets 400 INVALID_FIELD naming a field (sum) that appears nowhere on the page they copied from, or, on a deployment without the field probe, a raw driver no such column: sum. First-hour experience, published surface.

Interaction with #5918, worth stating precisely: #5918's 2026-08-07 ruling makes dotted measures a loud, named 400. That improves the error but does not fix this page — after it lands, the documentation will contain an example that the platform explicitly and deliberately rejects. The docs defect is independent of and prior to that PR, and #5918 correctly did not carry it (Prime Directive #10, different review surface). Sequencing is free either way; no Blocked-by:.

Fix direction endorsed as filed: revenue.sum → revenue_sum at all six sites, plus a sentence in data-api.mdx's /analytics/query section stating the legal spellings — the object's own field plus an aggregation suffix (_sum / _avg / _min / _max / _count_distinct), or a Cube-declared measure name, with a dot legal only as a cube-name qualifier. That sentence is what stops the next author re-deriving the wrong shape.

Dedup: all 463 open issues and PRs paginated across the three repos. No duplicate; the filer's own search is confirmed. #5141 (report chart axis title reading name instead of label) is a different surface, as they noted. No objectui / cloud shadow.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[hotlong]

认领(pm-dispatch devx 座位) — 本单进入派发,优先级来自 target:v17(分诊判为发版板判据④「照文档抄即失败」,已发布面 + 第一小时体验)。

• Session: session_01BDmDsu2575gDxeMCxXhDE3
• 分支: claude/issue-6291-analytics-measure-spelling
• 文件面: content/docs/api/client-sdk.mdx + content/docs/api/data-api.mdx。⛔ 不动 packages/**(analytics 自动推断路径:measures 上的关系穿越点号 member 仍被剥成基表列 —— owner.region_count_distinct 静默聚合基表 region(#5739 裁决未覆盖的第四个铸造点) #5918 的运行时半边已另行落地,本单纯文档)。
• 范围以分诊实测的六处为准,不是正文的三处:client-sdk.mdx:267(query 示例)、:279(explain 示例)、data-api.mdx:338(请求体)、:355/:356(响应行的 key)、:360(columns 条目的 name)。⚠️ 后三处是同一示例的响应半边 —— 只改请求不改响应会让页面变成「文档化的请求与文档化的响应 key 对不上」,比今天更糟。六处必须同批。行号按你 worktree 实测复核,不照抄。
• 一并要写的那句话(分诊点名,是本单防复发的部分): 在 data-api.mdx 的 /analytics/query 段写明合法拼写 —— 对象自己的字段 + 聚合后缀(_sum / _avg / _min / _max / _count_distinct),或 Cube 声明的 measure 名;点号仅在作 cube 名限定符时合法。没有这句,下一个作者会重新推导出同样的错形状。
• ⚠️ Check Documentation Links 现已在每个 PR 上真跑(PR ci(check-links): 恢复 pull_request 断链门,仅检仓内链接、advisory-first (#6028) #6304 今日恢复):改 docs 若造出死链会当场红。
• 互斥核对: 与在飞 check-single-authz-resolver 检查 (1) 的判据词表已被 ADR-0090 D3 改名废掉:sys_user_role 全仓 0 命中,门禁结构上抓不到任何重复解析器 #6286(scripts/check-single-authz-resolver.mjs)、[finding] quick-reference.mdx 的协议索引与 packages/spec 现状漂移:三处小节计数不符 + connector-auth 有 schema 无参考页 #6319(content/docs/getting-started/quick-reference.mdx)、objectui 没有「发布性改动必须声明 changeset」闸门 —— changeset-guard.yml 的触发器决定了它只看得见已经带 changeset 的 PR(objectui#3518 因此整个从发布记录里消失) #6174(scripts/objectui-changeset-digest.mjs)零交集 —— 与 [finding] quick-reference.mdx 的协议索引与 packages/spec 现状漂移:三处小节计数不符 + connector-auth 有 schema 无参考页 #6319 同在 content/docs/ 但文件不同,已逐一核对。

---

Generated by Claude Code