预览看板图表 SQL

执行图表 SQL 预览，返回查询结果而不保存图表。

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

调用前准备

先在查看数据看板列表中选择要预览 SQL 的数据看板。

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求体

将示例中的调用者专属值替换为实际值。

输入示例

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"
  }'

参数说明

参数	类型	是否必填	说明
sql_text	string	是	要预览的 SQL。

成功响应

接口同步执行 SQL，并返回本次预览的结果。最多返回 1000 行；truncated 为 true 时，表示实际结果超过该上限。

响应示例

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

字段说明

通用字段

字段	类型	说明
code	integer	成功时为 200。
data	object	SQL 预览结果。
columns	array	结果列。
result	array	结果数据。

预览结果

下面表格展开响应示例中的 data 对象；每一行是该对象的一个字段。

字段	类型	说明
query_id	string	查询 ID。
db_name	string	执行 SQL 的数据库名称。
statement_id	string	语句 ID。
status	string	查询状态。
err_msg	string	查询失败原因；查询失败时返回。
offset	integer	本次结果的起始偏移量，当前为 0。
limit	integer	本次预览最多返回的行数，当前为 1000。
total	integer	本次实际返回的行数，最大为 1000。
elapsed_ms	integer	本次预览耗时，单位为毫秒。
truncated	boolean	是否还有超出 1000 行上限的结果未返回。

结果列

下面表格展开 data 中的 columns 列表；每一行是列表中一个结果列的字段。

字段	类型	说明
name	string	列名。
type	string	列类型。

结果单元格

下面表格展开 data 中 result 列表的每个单元格；每一行是单元格对象的一个字段。

字段	类型	说明
String	string	单元格的字符串形式。
Valid	boolean	单元格是否包含有效值；为 false 时表示空值。

空结果

当响应中的 data 包含 empty_set 对象时，下面表格展开该对象。

字段	类型	说明
msg	string	非查询语句没有结果集时的说明。

错误响应

响应示例

{
  "code": 400,
  "message": "请求参数无效"
}

字段说明

字段	类型	说明
code	integer 或 string	错误代码或状态码。
message	string	错误信息。

最后更新于 2026 年 9 月 28 日