# 查询执行状态

读取当前身份已执行 SQL 的状态和结果 ID（`statement_id`）。只有状态为 `success` 时，才能使用该结果 ID 读取或下载结果。

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

## 调用前准备

准备个人访问令牌、工作区 ID，以及[执行 SQL](execute-sql.md)响应中的查询 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：查询所在的工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$QUERY_ID`：执行 SQL 响应中的 `data.query_id`。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `query_id` | string | 是 | [执行 SQL](execute-sql.md) 返回的查询 ID。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/query/describe" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{\"query_id\":\"$QUERY_ID\"}"
```

## 成功响应

`statement_id` 用于读取或下载结果，不能用 `query_id` 替代。状态为 `success` 时，可使用 Statement ID 获取结果。

```json
{
  "code": 200,
  "data": {
    "query_id": "query_01",
    "created_at": "2026-08-18T10:00:00Z",
    "statement_id": "statement_01",
    "db_name": "sales",
    "status": "success",
    "rows_affected": 1
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功时为 `200`。 |
| `data.query_id` | string | 查询 ID。 |
| `data.created_at` | string | 执行记录的创建时间。 |
| `data.statement_id` | string | 结果 ID；读取或下载本次 SQL 的结果时使用。 |
| `data.db_name` | string | 执行时指定的数据库。 |
| `data.status` | string | 执行状态。 |
| `data.err_msg` | string | 执行错误信息；仅在有错误信息时返回。 |
| `data.rows_affected` | integer | 受影响行数。 |

## 错误响应

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

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 常见原因
  - 建议操作
* - `400`
  - 请求体不是有效 JSON，或缺少 `query_id`。
  - 检查请求体和查询 ID。
* - `401`
  - 凭据缺失或无效。
  - 检查访问令牌。
* - `403`
  - 当前身份没有读取该查询记录的权限。
  - 使用创建该查询的身份，或联系管理员授权。
* - `404`
  - 查询 ID 不存在，或不属于当前身份。
  - 检查 `query_id`，并确认使用相同身份调用。
* - `500`
  - 服务端无法读取查询记录。
  - 记录错误信息后重试。
```

## 后续操作

状态表示已成功时，用返回的结果标识[查询执行结果](get-execution-result.md)或[下载执行结果](download-execution-result.md)。仍在执行且需要中止时[取消执行](cancel-execution.md)。