查询 SQL 执行记录

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

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：

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 执行失败。

{
  "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 为服务端返回的本地化公共错误信息，不应依赖其文本进行程序判断。

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

常见 HTTP 错误

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

后续操作

本接口用于执行历史检索。需要重跑或改写 SQL 时，携带记录中的语句前往执行 SQL。

最后更新于 2026 年 8 月 22 日