Run SQL once and return results¶
POST /query/run shares a DTO with /query/execute. Both call Execute and wait for the service. Old comments/CLI help describe execute as async, but do not establish early HTTP return or background execution. The two HTTP actions mainly differ in returned content and handling of user SQL failures. WS Start provides the phased path that returns query_id before completion messages.
Request parameters¶
{"db_name":"sales","query":"SELECT NULL AS note","offset":0,"limit":20}
Field |
Type |
Condition |
|---|---|---|
db_name |
string |
Optional execution database; no fixed default database is assumed. |
query |
string |
Required, nonempty after trimming whitespace. Statements depend on the caller’s actual permissions and are not limited to SELECT. |
sql_type |
string |
Optional identifier; not used to choose the current engine execution mode. |
offset |
integer |
Result starting offset; the service imposes no additional nonnegative requirement. |
limit |
integer |
Result window, calculated as described below. |
For offset<1000, the cap is min(1000,1000-offset), or a smaller positive limit. For offset>=1000, the current calculation yields 0. Do not describe 1000 as a strict scan limit.
The operation first saves a running record and connection ID, executes SQL, then conditionally writes success/failure. If concurrent cancellation has changed the state to killed, completion preserves killed. If SQL writes data but final record persistence fails, not all side effects necessarily roll back. A single HTTP failure does not justify automatic SQL replay.
Successful response¶
Success returns HTTP 200, numeric code=200, and data as the result object. Results belong to this execution; do not submit the original SQL again to retrieve rows. Persisted user SQL failures such as syntax errors or missing objects/columns/functions may be inlined as status=failed and err_msg. Permission or infrastructure errors still use HTTP errors. Applicable database codes follow source classifications and existing tests. Neither HTTP 200 nor an SDK call without an exception establishes SQL success.
/query/execute and interactive services without this inline option retain older error handling. Syntax failures have a separate reread path, so not every error necessarily has non-200 HTTP status. Unknown fields/trailing values are not strictly rejected. Assess authentication, error envelopes, persistence, and actual execution separately.