<span id="预览图表点的明细"></span>

# Preview details for a chart point

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

`POST /data-dashboards/{dashboard_id}/charts/{chart_id}/drill-through` allows one strictly parsed JSON request object. Clients provide chart dimensions and values, not arbitrary SQL, table names, or column names.

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

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

:::::
:::::{tab-item} Parameters

| Field | Type | Constraint |
| --- | --- | --- |
| dimensions | array (objects) | Must exactly match the chart role set, without duplicate or extra roles. |
| dimensions[].role | string | x, series, or label for the chart types below. |
| dimensions[].value | scalar or null | String, number, boolean, or null. Omitted values become null; arrays and objects are rejected. |

| Chart type | Required configuration | Request roles |
| --- | --- | --- |
| metric | value | None; dimensions empty or omitted. |
| 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 and other types are unsupported. Request roles are not column names; do not submit a y measure. Each role must map unambiguously to a directly selected SQL column, optionally with an output alias. Computed expressions and ambiguous mappings are rejected.

Uses the saved single-table SELECT and its WHERE, appending point-dimension conditions to generate SELECT * detail SQL. Supported rewriting removes the original aggregate projection, GROUP BY, ORDER BY, and LIMIT. The original chart LIMIT does not restrict exported details. JOIN, derived tables, subqueries, WITH, DISTINCT, HAVING, windows, locks, SELECT INTO, and similar constructs are rejected. The source must match the dashboard's currently available source. Old table names saved in a chart cannot bypass current permissions.

Preview executes COUNT as the current caller, then reads at most 10 detail rows. null generates IS NULL, and numbers retain integer text through the original JSON Number. The two queries do not guarantee a shared snapshot; changes can affect count/preview consistency. This API accepts no historical at timestamp. The frontend disables point drill-through in historical snapshot mode; drill-through does not retrieve old-snapshot details.

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Fields

| data field | Type | Description |
| --- | --- | --- |
| columns | array (objects) | name、type |
| rows | array (two-dimensional) | Cell objects contain String and Valid; Valid=false means null. |
| preview_limit | integer | Fixed at 10. |
| visible_total | integer | Detail count visible to the current identity. |
| truncated | boolean | visible_total exceeds the actual preview row count. |
| sql_text | string | Detail SQL without the preview LIMIT, not the original aggregate SQL. |
| database | string | Chart database. |

Success uses a code/msg/data envelope. Invalid shapes return 400/ErrParamInvalid; SQL, charts, or roles that cannot map safely return 400/ErrDataDashboardDrillThroughUnsupported. Missing objects return 404; permission 403 and dependency 503 follow dashboard mappings.

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