Preview dashboard chart SQL

Execute a chart SQL preview, returning query results without saving the chart.

POST https://api.moi.matrixorigin.cn/v5/data-dashboards/{dashboard_id}/preview

Preparation before calling

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

• $AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.

• $WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.

• $DASHBOARD_ID: dashboard_id to use, specifying the target resource via the request path.

Request body

Replace caller-specific values in the example with actual values.

sql_textstringRequired

The SQL to preview.

Request example

curl -X POST "https://api.moi.matrixorigin.cn/v5/data-dashboards/$DASHBOARD_ID/preview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sql_text": "SELECT 1 AS value"
  }'

Successful response

The endpoint executes SQL synchronously and returns up to 1,000 rows. truncated: true indicates that more rows exist beyond this limit.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "query_id": "query-001",
    "db_name": "analytics",
    "statement_id": "stmt-001",
    "status": "success",
    "limit": 1000,
    "total": 1,
    "columns": [
      {
        "name": "value",
        "type": "BIGINT"
      }
    ],
    "result": [
      [{"String": "1", "Valid": true}]
    ],
    "elapsed_ms": 12,
    "truncated": false
  }
}

The response fields are as follows.

Field	Type	Description
code	string	OK on success.
msg	string	OK on success.
data.query_id	string	Query ID.
data.db_name	string	Database used to execute the SQL.
data.statement_id	string	Statement ID.
data.status	string	Query status.
data.err_msg	string	Error message, returned when the query fails.
data.offset	integer	Result offset; currently zero and omitted when zero.
data.limit	integer	Maximum rows in this preview, currently 1,000.
data.total	integer	Number of rows returned, up to 1,000.
data.elapsed_ms	integer	Preview duration in milliseconds.
data.truncated	boolean	Whether additional rows exceed the 1,000-row limit.
data.columns	array	Result column.
data.columns[].name	string	Column name.
data.columns[].type	string	Column type.
data.result	array	Result data.
data.result[][].String	string	Cell value as a string.
data.result[][].Valid	boolean	Whether the cell has a value; false indicates null.
data.empty_set.msg	string	Message returned when a statement has no result set.

Error response

This example corresponds to HTTP 400.

codestring

Error code, such as ErrParamInvalid or ErrDataDashboardNotFound.

msgstring

HTTP status text, such as Bad Request or Not Found.

{
  "code": "ErrParamInvalid",
  "msg": "Bad Request"
}

Last updated on Oct 19, 2026