docs(api): /analytics/query 示例的 measure 拼写改为 revenue_sum,并写明合法拼写 (#6291) (#6372)

示例里 `revenue.sum` 的首段 `revenue` 不是 cube 名(cube 是 `account`),
所以它不是 cube 名限定符。#5918(PR #6292)落地后,这条示例在运行时得到
400 INVALID_FIELD 并点名 `revenue.sum` 本身,且不执行任何查询 —— 即照
文档抄的查询跑不通。

六处同批改正(请求 + 响应两个半边,避免出现「文档化的请求与文档化的
响应 key 对不上」),并在 data-api.mdx 的 /analytics/query 段落写明合法
拼写:对象自己的字段 + 聚合后缀,或 Cube 声明的 measure 名;点号仅在
作 cube 名限定符时合法。


Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3

Co-authored-by: Claude <noreply@anthropic.com>

Author: hotlong

content/docs/api/client-sdk.mdx

@@ -264,7 +264,7 @@ for the underlying endpoint contract.
 // Semantic analytics query (cube-style)
 const result = await client.analytics.query({
   cube: 'account',
-  measures: ['revenue.sum', 'count'],
+  measures: ['revenue_sum', 'count'],
   dimensions: ['industry'],
   where: { status: 'active' },
   limit: 100,
@@ -276,7 +276,7 @@ const meta = await client.analytics.meta('account');
 // Dry-run a query to its generated SQL (POST /analytics/sql)
 const explained = await client.analytics.explain({
   cube: 'account',
-  measures: ['revenue.sum'],
+  measures: ['revenue_sum'],
 });
 ```
 

content/docs/api/data-api.mdx

@@ -335,13 +335,28 @@ Execute an analytics query.
 ```json
 {
   "cube": "account",
-  "measures": ["revenue.sum", "count"],
+  "measures": ["revenue_sum", "count"],
   "dimensions": ["industry"],
   "where": { "status": "active" },
   "limit": 100
 }
 ```
 
+<Callout type="info">
+**How to spell a measure.** A `measures` entry is either a measure the Cube **declares**,
+or one of the inferred spellings: the bare `count` (`COUNT(*)`), or one of the object's
+**own** field names plus an aggregation suffix — `_sum`, `_avg`, `_min`, `_max`,
+`_count_distinct`. So "the sum of `revenue`" is `revenue_sum`.
+
+A dot is legal **only** as the `<cube>.` qualifier: `account.revenue_sum` resolves to the
+same measure as `revenue_sum` (the response column keeps whichever of the two you sent).
+Any other dotted spelling — `revenue.sum`, `owner.amount_sum` — is refused with
+`400 INVALID_FIELD` naming the spelling you sent, and nothing is executed: measures do not
+traverse relationships, only dimensions do, so there is no related column for a dotted
+measure to aggregate. To aggregate a related column, declare a Cube whose measure names it
+in its own `sql`.
+</Callout>
+
 <Callout type="info">
 Filtering uses the canonical Query DSL `where` object (the same MongoDB-style `FilterCondition` accepted by `find()`), not a `filters` array.
 </Callout>
@@ -352,12 +367,12 @@ Filtering uses the canonical Query DSL `where` object (the same MongoDB-style `F
   "success": true,
   "data": {
     "rows": [
-      { "industry": "Technology", "revenue.sum": 150000, "count": 5 },
-      { "industry": "Healthcare", "revenue.sum": 80000, "count": 3 }
+      { "industry": "Technology", "revenue_sum": 150000, "count": 5 },
+      { "industry": "Healthcare", "revenue_sum": 80000, "count": 3 }
     ],
     "fields": [
       { "name": "industry", "type": "string", "label": "Industry" },
-      { "name": "revenue.sum", "type": "number", "label": "Revenue Sum", "format": "$0,0" },
+      { "name": "revenue_sum", "type": "number", "label": "Revenue Sum", "format": "$0,0" },
       { "name": "count", "type": "number", "label": "Count" }
     ],
     "sql": "SELECT ..."