Repository navigation
docs: /analytics/query 的两处示例用 measures: ['revenue.sum'] —— 首段不是 cube 名,这条查询今天就答 400 #6291
Description
Activity
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/docsfor the exact string:file line context content/docs/api/client-sdk.mdx:267measures: ['revenue.sum', 'count']— thequeryexamplecontent/docs/api/client-sdk.mdx:279the explainexample, same spellingcontent/docs/api/data-api.mdx:338POST /analytics/queryrequest bodycontent/docs/api/data-api.mdx:355,:356response rows keyed "revenue.sum"content/docs/api/data-api.mdx:360columnsentry{ "name": "revenue.sum", … }The body names three sites; there are six.
:355/:356/:360are the response half of the same example — if only the request is corrected torevenue_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/queryexample today gets400 INVALID_FIELDnaming a field (sum) that appears nowhere on the page they copied from, or, on a deployment without the field probe, a raw driverno 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_sumat all six sites, plus a sentence indata-api.mdx's/analytics/querysection 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
nameinstead oflabel) is a different surface, as they noted. Noobjectui/cloudshadow.本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
认领(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
- Session:
- added a commit that references this issue
on Aug 8, 2026
在实现 #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)的部署上,这条示例今天就得到:即:照文档抄的查询跑不通,而且报错点名的是文档里根本没出现过的
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 无影子单。