# 执行一次SQL并返回结果

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

`POST /query/run`，请求与/query/execute共用DTO，都是调用Execute并等待service返回。旧注释/CLI帮助把execute称async，不能据此承诺当前HTTP会提前返回或后台执行；两个HTTP动作主要区别是返回内容与用户SQL失败处理。WS Start才有先query_id后完成消息的分阶段路径。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```json
{"db_name":"sales","query":"SELECT NULL AS note","offset":0,"limit":20}
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 条件 |
| --- | --- | --- |
| db_name | string | 可选，执行数据库，不编造固定默认库 |
| query | string | 必填，去空白后非空；可执行语句权限以调用者实际权限为准，不限于SELECT |
| sql_type | string | 可选标识；未参与当前engine执行方式选择 |
| offset | integer | 结果起点，服务未额外要求非负 |
| limit | integer | 返回窗口，按下面实现计算 |

offset<1000时上限min(1000,1000-offset)，正limit更小时取limit；offset>=1000时当前计算为0，不能将1000写成严格扫描上限。

操作先保存running记录及连接ID，再执行SQL，条件更新成功/失败；若并发取消已改为killed，完成写入保留killed事实。SQL已写入数据而最终记录写失败时不能假设回滚全部副作用；一次HTTP失败也不能自动重放语句。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 字段说明

成功HTTP200、数字code=200、data为[结果对象](result-contract.md)。返回同次执行的结果，不应再把原SQL发第二次来获取行。持久化的语法、缺对象/列/函数等用户SQL失败可内联为status=failed和err_msg；权限或基础设施错误仍走HTTP错误。可内联的具体数据库码见源码分类及既有测试，不把HTTP200或SDK无异常当SQL成功。

未开启该内联选项的/query/execute及交互式service保留旧错误处理；语法失败有单独回读路径，不能概括为所有错误必为HTTP非200。请求并未严格拒绝未知字段/尾随值；认证、错误封套、持久化和真正执行分别判断。

:::::
::::::
:::::::
