# 预览图表点的明细

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

`POST /data-dashboards/{dashboard_id}/charts/{chart_id}/drill-through`，只允许一个严格JSON请求对象。客户端提供图表维度和值，不能传任意SQL、表名或列名。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```json
{"dimensions":[{"role":"x","value":"华东"}]}
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 约束 |
| --- | --- | --- |
| dimensions | array（对象数组） | 与图表角色集合精确匹配，无重复或额外角色 |
| dimensions[].role | string | 以下图表对应的x、series或label |
| dimensions[].value | scalar 或 null | 字符串、数字、布尔或null；省略值按null，数组/对象拒绝 |

| 图表类型 | 必要配置 | 请求角色 |
| --- | --- | --- |
| metric | value | 无，dimensions为空或省略 |
| combo | x、barY、lineY | x |
| stacked_bar | x、y、series | x、series |
| scatter | x、y、label | x、label |
| line、bar、area、pie | x、y | x |

table及其他类型不支持。请求角色不是列名，也不用提交y度量。角色必须能映射到SQL中唯一的直接选出列，可有输出别名；计算表达式或匹配歧义拒绝。

使用保存的单表SELECT及其WHERE，追加点维度条件，生成SELECT *明细。支持的重写会去掉原聚合投影、GROUP BY、ORDER BY及LIMIT；原图表LIMIT不限制导出明细。JOIN、派生表、子查询、WITH、DISTINCT、HAVING、窗口、锁及SELECT INTO等拒绝。来源须匹配看板当前可用来源，不能凭保存在图表内的旧表名越过当前权限。

预览先以当前调用身份执行COUNT，再执行最多10行明细；null生成IS NULL，数值用原始JSON Number保留整数文本。两次查询没有同一快照保证，数据变化可能影响计数与预览一致性。此接口不接受at历史时间；前端历史快照模式禁用点下钻，不能把下钻当旧快照明细。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 字段说明

| data字段 | 类型 | 说明 |
| --- | --- | --- |
| columns | array（对象数组） | name、type |
| rows | array（二维数组） | 单元格对象含String和Valid，Valid=false表示空值 |
| preview_limit | integer | 固定10 |
| visible_total | integer | 当前身份可见的明细计数 |
| truncated | boolean | visible_total大于实际预览行数 |
| sql_text | string | 不带预览LIMIT的明细SQL，非原聚合SQL |
| database | string | 图表数据库 |

成功用code/msg/data封套。形状错误400/ErrParamInvalid；SQL、图表或角色无法安全映射400/ErrDataDashboardDrillThroughUnsupported；缺对象404；权限403和依赖503沿看板映射。

:::::
::::::
:::::::
