# 查询执行结果

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

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

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

## 调用前准备

先[查询执行状态](get-execution-status.md)，确认状态为 `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`。 |

## 请求示例

```bash
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`。

```json
{
  "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` 值。 |

## 错误响应

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 15 45 40

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

## 后续操作

继续调整 `offset` 和 `limit` 读取后续行，或[下载执行结果](download-execution-result.md)。