查询执行结果¶

查看你执行成功的 SQL 返回的数据。

如果结果很多，可以分几次读取：offset 表示跳过前多少行，limit 表示这次最多读取多少行。例如，先用 offset: 0, limit: 20 读取前 20 行；再用 offset: 20, limit: 20 读取接下来的 20 行。

POST https://moi.matrixorigin.cn/newmoi/query/result

调用前准备¶

先查询执行状态，确认状态为 success 并取得结果 ID（statement_id）。该接口只能读取当前身份成功执行的查询。

下方示例使用：

$AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。
$WORKSPACE_ID：查询所在的工作区 ID，通过 X-Workspace-ID Header 传递。
$STATEMENT_ID：状态响应中的结果 ID，即 data.statement_id。

请求体¶

字段	类型	是否必填	说明
`statement_id`	string	是	成功执行查询的结果 ID。
`offset`	integer	否	开始读取的行位置，从 `0` 开始。
`limit`	integer	否	本次最多返回的行数；未提供或小于等于 `0` 时，服务端使用 `1000`。

请求示例¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/query/result" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{\"statement_id\":\"$STATEMENT_ID\",\"offset\":0,\"limit\":20}"

成功响应¶

total 是本次返回的行数，不是完整结果集的总行数。result 中每一行按 columns 的顺序排列；Valid 为 false 表示该单元格为 NULL。

{
  "code": 200,
  "data": {
    "query_id": "query_01",
    "db_name": "sales",
    "statement_id": "statement_01",
    "status": "success",
    "offset": 0,
    "limit": 20,
    "total": 1,
    "columns": [
      {"name": "n", "type": "INT64"}
    ],
    "result": [
      [{"String": "1", "Valid": true}]
    ]
  }
}

响应字段如下。

本文中，字段路径中的 [] 表示数组中的每一项。例如，items[].name 表示 items 数组中每一项的 name 字段。

字段	类型	说明
`code`	integer	成功时为 `200`。
`data.query_id`	string	产生结果的查询 ID。
`data.db_name`	string	执行时指定的数据库。
`data.statement_id`	string	本次结果的 Statement ID。
`data.status`	string	成功读取结果时为 `success`。
`data.offset`	integer	本次开始读取的行位置。
`data.limit`	integer	本次请求的最大返回行数。
`data.total`	integer	本次实际返回的行数。
`data.columns[].name`	string	列名。
`data.columns[].type`	string	数据库返回的列类型。
`data.result[][].String`	string	单元格的字符串值。
`data.result[][].Valid`	boolean	是否为非 `NULL` 值。

错误响应¶

{"code": 404, "message": "SQL 查询结果不存在"}

常见 HTTP 错误¶

HTTP 状态码	常见原因	建议操作
`400`	请求体不是有效 JSON，或缺少 `statement_id`。	检查请求体和 Statement ID。
`401`	凭据缺失或无效。	检查访问令牌。
`403`	当前身份没有读取结果所需的数据库权限。	使用有权限的凭据，或联系管理员授权。
`404`	结果不存在、查询未成功完成，或结果不属于当前身份。	确认查询状态为 `success`，并检查 Statement ID。
`500`	服务端无法验证或读取结果。	记录错误信息后重试。
`503`	当前角色的执行连接不可用。	稍后重试。

后续操作¶

继续调整 offset 和 limit 读取后续行，或下载执行结果。

最后更新于 2026 年 8 月 22 日