From 266d1b69c7b21e2215c3d29c42d36da924c62ab0 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 18:43:06 +0000 Subject: [PATCH] =?UTF-8?q?docs(api):=20`/analytics/query`=20=E7=9A=84=20`?= =?UTF-8?q?fields[]`=20=E5=8F=AA=E6=9C=89=20`name`=20/=20`type`=EF=BC=8C?= =?UTF-8?q?=E5=88=A0=E6=8E=89=E7=A4=BA=E4=BE=8B=E9=87=8C=E7=9A=84=20`label?= =?UTF-8?q?`=20/=20`format`=20=E5=B9=B6=E5=86=99=E6=98=8E=E4=B8=A4?= =?UTF-8?q?=E5=B1=82=E7=9A=84=E5=88=86=E5=B7=A5=20(#6369)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `POST /analytics/query` 的响应示例给 `data.fields[]` 三个条目都标了 `label`、 中间那个还标了 `format`，而这个端点的任何一条产出路径都只发 `{ name, type }`。 照文档写的客户端读 `fields[i].label` 渲染表头、读 `format` 格式化金额，拿到的 是 `undefined` —— 不像拼写错误那样当场 400，而是安静地渲染出空表头。 删掉这四个键，并补一段 Callout 说明两层的分工：display name 与 format 是 cube 的 metric/dimension **定义**的属性（`MetricSchema.label` / `.format`）， 从 cube 元数据读，不在查询结果里。只删键不解释，下一个读者会重新推导出同样的 错误期待。 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3 --- content/docs/api/data-api.mdx | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/content/docs/api/data-api.mdx b/content/docs/api/data-api.mdx index 2c3870466e..b6f4bf522b 100644 --- a/content/docs/api/data-api.mdx +++ b/content/docs/api/data-api.mdx @@ -371,15 +371,28 @@ Filtering uses the canonical Query DSL `where` object (the same MongoDB-style `F { "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": "count", "type": "number", "label": "Count" } + { "name": "industry", "type": "string" }, + { "name": "revenue_sum", "type": "number" }, + { "name": "count", "type": "number" } ], "sql": "SELECT ..." } } ``` + +**`fields[]` describes columns, not presentation.** Each entry carries exactly `name` and +`type` — that is the whole descriptor `AnalyticsResultResponseSchema` declares, and every +strategy answering this endpoint emits those two keys and nothing else. + +Display name and number format live one layer up, in the **cube's metric/dimension +definition** (`MetricSchema.label` / `MetricSchema.format`, `DimensionSchema.label`), and +are read from cube metadata — `GET /analytics/meta` below reports each measure's and +dimension's declared label as `title`. Reading `data.fields[i].label` or +`data.fields[i].format` off a query result yields `undefined`; a client that renders table +headers or formats amounts reads them from the cube metadata instead. + + ### `GET /analytics/meta` Get metadata for all registered cubes. Cubes are explicitly defined (via `defineCube`