# 查询 SQL 执行记录

按筛选条件查询当前工作区可见的 SQL 执行记录。默认只返回当前身份的记录；如需读取工作区范围的记录，请显式指定 `scope` 并确保当前身份具有相应读取权限。

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

## 调用前准备

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

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `scope` | string | 否 | 读取范围。省略时为 `self`，仅查询当前身份的记录；可设为 `workspace` 查询工作区范围的记录。`workspace` 需要单独的工作区审计读取权限。 |
| `status` | string | 否 | 按状态筛选：`Running`、`Success` 或 `Failed`。 |
| `user` | string（字符串数组） | 否 | 按执行用户筛选。仅在 `scope` 为 `workspace` 时可用于缩小范围。 |
| `databases` | string（字符串数组） | 否 | 按数据库名称筛选。 |
| `statement` | string | 否 | 按 SQL 文本进行包含匹配。 |
| `query_type` | string（字符串数组） | 否 | 按语句类别筛选：`DDL`、`DML`、`DQL`、`DCL`、`TCL` 或 `Other`。 |
| `duration` | unsigned integer | 否 | 最短执行时长筛选。仅当值大于 `0` 时生效。 |
| `start` | string | 否 | 起始时间，使用 RFC 3339 时间格式。与 `end` 都省略时，服务仅查询请求时刻前 5 分钟内的记录。 |
| `end` | string | 否 | 结束时间，使用 RFC 3339 时间格式。与 `start` 都省略时，服务仅查询请求时刻前 5 分钟内的记录。 |
| `statement_id` | string | 否 | 按语句 ID 筛选。完整 UUID 按精确值匹配，其他合法值按包含匹配；值只能包含字母、数字和连字符。 |
| `transaction_id` | string | 否 | 按事务 ID 精确筛选。 |
| `session_id` | string | 否 | 按会话 ID 精确筛选。 |
| `selected_field` | string（字符串数组） | 否 | 指定返回记录中的字段。省略时返回服务端的默认字段集合。无论是否指定，返回结果均会包含 `request_at`，以支持排序。 |
| `sql_source_type` | string（字符串数组） | 否 | 按 SQL 来源类型筛选。省略时仅查询 `cloud_user_sql` 和 `external_sql`。 |
| `offset` | unsigned integer | 否 | 从零开始的偏移量。默认值为 `0`。 |
| `limit` | unsigned integer | 否 | 单次返回的最大记录数。省略或传入 `0` 时为 `10`；大于 `1000` 时按 `1000` 处理。 |
| `order_by` | string（字符串数组） | 否 | 排序字段，可选 `request_at`、`response_at`、`duration`、`rows_read`、`bytes_scan` 或 `cu`。省略时按 `request_at` 降序排列。 |
| `order` | string | 否 | `order_by` 的排序方向。仅 `DESC` 保持降序，其他值按升序处理。 |
| `cu` | unsigned integer | 否 | 容量使用量阈值。仅当部署启用了该筛选能力且值大于 `0` 时生效。 |

## 请求示例

以下示例查询当前身份在指定时间范围内执行成功的 SQL：

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/query/history" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "Success",
    "databases": ["analytics"],
    "start": "2026-08-18T00:00:00Z",
    "end": "2026-08-18T01:00:00Z",
    "limit": 20,
    "order_by": ["request_at"],
    "order": "DESC"
  }'
```

## 成功响应

成功时返回 HTTP `200`。`data.query_list` 为空表示在本次筛选范围内没有可返回的记录；这不表示 SQL 执行失败。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 1,
    "offset": 0,
    "limit": 20,
    "query_list": [
      {
        "statement_id": "5c6f22fb-ef0e-4f46-b06f-c31e1a7afb48",
        "database": "analytics",
        "statement": "SELECT * FROM orders",
        "request_at": "2026-08-18T00:30:00Z",
        "response_at": "2026-08-18T00:30:01Z",
        "duration": 1000,
        "status": "Success",
        "query_type": "DQL",
        "result_count": 10
      }
    ]
  }
}
```

响应字段如下。

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.total` | integer | 符合筛选条件的记录总数。 |
| `data.offset` | unsigned integer | 本次响应使用的偏移量。 |
| `data.limit` | unsigned integer | 本次响应实际使用的单页上限。 |
| `data.query_list` | object（对象数组） | SQL 执行记录列表。 |
| `data.query_list[].statement_id` | string | 语句 ID。 |
| `data.query_list[].transaction_id` | string | 事务 ID；为空时省略。 |
| `data.query_list[].session_id` | string | 会话 ID；为空时省略。 |
| `data.query_list[].account` | string | 执行所用账户；为空时省略。 |
| `data.query_list[].user` | string | 执行用户；为空时省略。 |
| `data.query_list[].host` | string | 执行主机；为空时省略。 |
| `data.query_list[].database` | string | 执行时使用的数据库；为空时省略。 |
| `data.query_list[].statement` | string | SQL 语句文本；为空时省略。 |
| `data.query_list[].statement_tag` | string | 语句标签；为空时省略。 |
| `data.query_list[].statement_fingerprint` | string | 语句指纹；为空时省略。 |
| `data.query_list[].node_uuid` | string | 执行节点 UUID；为空时省略。 |
| `data.query_list[].node_type` | string | 执行节点类型；为空时省略。 |
| `data.query_list[].request_at` | string | 请求时间；为空时省略。 |
| `data.query_list[].response_at` | string | 响应时间；为空时省略。 |
| `data.query_list[].duration` | unsigned integer | 执行时长；为 `0` 时省略。 |
| `data.query_list[].status` | string | 执行状态；为空时省略。 |
| `data.query_list[].error_code` | string | 错误代码；为空时省略。 |
| `data.query_list[].error` | string | 错误信息；为空时省略。 |
| `data.query_list[].exec_plan` | string | 执行计划；为空时省略。 |
| `data.query_list[].rows_read` | unsigned integer | 读取行数；无值时省略。 |
| `data.query_list[].bytes_scan` | unsigned integer | 扫描字节数；无值时省略。 |
| `data.query_list[].statement_type` | string | 语句类型；为空时省略。 |
| `data.query_list[].query_type` | string | 查询类别；为空时省略。 |
| `data.query_list[].role_id` | unsigned integer | 执行角色 ID；无值时省略。 |
| `data.query_list[].sql_source_type` | string | SQL 来源类型；为空时省略。 |
| `data.query_list[].result_count` | integer | 结果行数；为 `0` 时省略。 |
| `data.query_list[].cu` | number | 容量使用量；无值时省略。 |
| `data.query_list[].connection_id` | integer | 数据库连接 ID；为 `0` 时省略。 |

## 错误响应

错误响应使用 `code`、`msg` 和 `data` 包络，`data` 为 `null`。`msg` 为服务端返回的本地化公共错误信息，不应依赖其文本进行程序判断。

```json
{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 请求体不是合法 JSON；`scope` 不是 `self` 或 `workspace`；筛选字段不符合约束；或 `statement_id`、`session_id` 含有不允许的字符。
  - 检查请求体、枚举值和时间格式后重新提交。
* - `403`
  - `ErrForbidden`
  - 当前身份没有读取所选范围 SQL 执行记录的权限。
  - 使用具有所需工作区读取权限的凭据，或改为默认的 `self` 范围。
* - `500`
  - `ErrServer`
  - 服务无法完成 SQL 执行记录查询。
  - 记录请求时间、HTTP 状态和错误代码后重试；持续出现时联系支持人员。
```

## 后续操作

本接口用于执行历史检索。需要重跑或改写 SQL 时，携带记录中的语句前往[执行 SQL](../data-processing/sql-execution/execute-sql.md)。