Skip to content

Commit e1f66bb

Browse files
hotlongclaude
andauthored
docs(api): /analytics/queryfields[] 只有 name / type,删掉示例里的 label / format 并写明两层的分工 (#6369) (#6441)
`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 元数据读,不在查询结果里。只删键不解释,下一个读者会重新推导出同样的 错误期待。 Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3 Co-authored-by: Claude <noreply@anthropic.com>
1 parent 17d0954 commit e1f66bb

1 file changed

Lines changed: 16 additions & 3 deletions

File tree

content/docs/api/data-api.mdx

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -371,15 +371,28 @@ Filtering uses the canonical Query DSL `where` object (the same MongoDB-style `F
371371
{ "industry": "Healthcare", "revenue_sum": 80000, "count": 3 }
372372
],
373373
"fields": [
374-
{ "name": "industry", "type": "string", "label": "Industry" },
375-
{ "name": "revenue_sum", "type": "number", "label": "Revenue Sum", "format": "$0,0" },
376-
{ "name": "count", "type": "number", "label": "Count" }
374+
{ "name": "industry", "type": "string" },
375+
{ "name": "revenue_sum", "type": "number" },
376+
{ "name": "count", "type": "number" }
377377
],
378378
"sql": "SELECT ..."
379379
}
380380
}
381381
```
382382

383+
<Callout type="info">
384+
**`fields[]` describes columns, not presentation.** Each entry carries exactly `name` and
385+
`type` — that is the whole descriptor `AnalyticsResultResponseSchema` declares, and every
386+
strategy answering this endpoint emits those two keys and nothing else.
387+
388+
Display name and number format live one layer up, in the **cube's metric/dimension
389+
definition** (`MetricSchema.label` / `MetricSchema.format`, `DimensionSchema.label`), and
390+
are read from cube metadata — `GET /analytics/meta` below reports each measure's and
391+
dimension's declared label as `title`. Reading `data.fields[i].label` or
392+
`data.fields[i].format` off a query result yields `undefined`; a client that renders table
393+
headers or formats amounts reads them from the cube metadata instead.
394+
</Callout>
395+
383396
### `GET /analytics/meta`
384397

385398
Get metadata for all registered cubes. Cubes are explicitly defined (via `defineCube`

0 commit comments

Comments
 (0)