# 查看 SQL 历史概览

按时间范围和 SQL 来源汇总当前工作区内的 SQL 执行记录数量。结果只包含各执行状态的数量，不返回单条 SQL 执行记录。默认只统计当前身份的记录；具备相应权限时，可以统计工作区范围的记录。

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

## 调用前准备

准备有当前工作区访问权限的[个人访问令牌](../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[当前工作区 ID](../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。

## 请求示例

以下示例统计指定时间范围内、默认 SQL 来源的执行记录。

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/query/history/overview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "start": "2026-08-26T08:00:00Z",
    "end": "2026-08-26T09:00:00Z"
  }'
```

## 请求体

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| scope | string | 否 | 统计当前身份或当前工作区的记录。 |
| start | string | 否 | 统计开始时间，例如 2026-08-26T08:00:00Z。 |
| end | string | 否 | 统计结束时间，例如 2026-08-26T09:00:00Z。 |
| sql_source_type | string（字符串数组） | 否 | 按 SQL 来源类型筛选。非空数组按其值筛选。 |
| non_user | boolean | 否 | 是否同时统计非用户 SQL。 |

字段路径中的 [] 表示数组中的每一项。类型后的 [] 表示数组，例如 string[] 是字符串数组。

### 查看范围

| scope 值 | 可统计的记录 | 权限条件 |
| --- | --- | --- |
| self | 当前身份的记录。 | 默认范围。 |
| workspace | 工作区范围的记录。 | 需要工作区审计读取权限。 |

### 查询时间和 SQL 来源

时间需填写完整的日期、时间和时区。开始和结束时间都未填写时，默认统计请求前 5 分钟内的记录；可以只填写其中一个时间作为统计边界。

指定 SQL 来源时，以 sql_source_type 为准。未指定 SQL 来源时，non_user 为 true 会统计全部来源；false 或省略时，只统计用户 SQL 和外部 SQL。

## 成功响应

成功时返回 HTTP 200。data.total 为 0 表示本次筛选范围内没有可统计的记录，不表示查询失败。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 3,
    "success": 2,
    "running": 0,
    "failed": 1
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | string | 成功时为 OK。 |
| msg | string | 成功时为 OK。 |
| data.total | integer | 符合筛选条件的记录总数。 |
| data.success | integer | 状态为 Success 的记录数。 |
| data.running | integer | 状态为 Running 的记录数。 |
| data.failed | integer | 状态为 Failed 的记录数。 |

## 错误响应

错误响应使用 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。
  - 检查请求体和 scope 后重新提交。
* - 403
  - ErrForbidden
  - 当前身份没有读取所选范围 SQL 执行记录的权限。
  - 使用具有所需工作区读取权限的凭据，或改为默认的 self 范围。
* - 500
  - ErrServer
  - 服务无法完成 SQL 历史概览查询。
  - 记录请求时间、HTTP 状态和错误代码后重试；持续出现时联系支持人员。
```