From 2f574482d990a00ffc5c00fdc9f70438864d4817 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 15:19:15 +0000 Subject: [PATCH] =?UTF-8?q?docs(api):=20/analytics/query=20=E7=A4=BA?= =?UTF-8?q?=E4=BE=8B=E7=9A=84=20measure=20=E6=8B=BC=E5=86=99=E6=94=B9?= =?UTF-8?q?=E4=B8=BA=20revenue=5Fsum,=E5=B9=B6=E5=86=99=E6=98=8E=E5=90=88?= =?UTF-8?q?=E6=B3=95=E6=8B=BC=E5=86=99=20(#6291)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 示例里 `revenue.sum` 的首段 `revenue` 不是 cube 名(cube 是 `account`), 所以它不是 cube 名限定符。#5918(PR #6292)落地后,这条示例在运行时得到 400 INVALID_FIELD 并点名 `revenue.sum` 本身,且不执行任何查询 —— 即照 文档抄的查询跑不通。 六处同批改正(请求 + 响应两个半边,避免出现「文档化的请求与文档化的 响应 key 对不上」),并在 data-api.mdx 的 /analytics/query 段落写明合法 拼写:对象自己的字段 + 聚合后缀,或 Cube 声明的 measure 名;点号仅在 作 cube 名限定符时合法。 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3 --- content/docs/api/client-sdk.mdx | 4 ++-- content/docs/api/data-api.mdx | 23 +++++++++++++++++++---- 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/content/docs/api/client-sdk.mdx b/content/docs/api/client-sdk.mdx index 4116b19622..4bdaaf52f7 100644 --- a/content/docs/api/client-sdk.mdx +++ b/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'], }); ``` diff --git a/content/docs/api/data-api.mdx b/content/docs/api/data-api.mdx index 86c56acf01..2c3870466e 100644 --- a/content/docs/api/data-api.mdx +++ b/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 } ``` + +**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 `.` 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`. + + Filtering uses the canonical Query DSL `where` object (the same MongoDB-style `FilterCondition` accepted by `find()`), not a `filters` array. @@ -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 ..."