Execute SQL¶

Execute a SQL and return the query ID of this execution. Use this ID to query the running status; after the query is successful, the status response returns the result ID (statement_id) required to read or download the results.

HTTP
POST $CLOUDSIGMA_API_BASE/query/execute

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

The identity executing the SQL also needs to have appropriate permissions on the target database; do not splice unprocessed user input directly into the SQL.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/query/execute" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "db_name": "sales",
    "query": "SELECT 1 AS n",
    "offset": 0,
    "limit": 20
  }'

Parameter reference

Request body

Field	Type	Description
`query`	string	the SQL to execute.
`db_name`	string	The database used when executing SQL.
`sql_type`	string	Caller-defined SQL type identifier.
`offset`	integer	The starting position of the first result window.
`limit`	integer	The number of rows in the result window; when 0 is not provided or is less than or equal to 0, the server uses 1000.

Successful response¶

The response returns only the query ID. Use the ID query execution status to get the status and Statement ID.

The response fields are as follows.

Response example

JSON
{
  "code": 200,
  "data": {
    "id": "query_01",
    "query_id": "query_01"
  }
}

Field reference

Field	Type	Description
`code`	integer	200 on success.
`data.id`	string	Query ID, same as data.query_id.
`data.query_id`	string	Query ID; used to query status or cancel execution.

Error response¶

Response example

JSON
{"code": 400, "message": "请求参数无效"}

Field reference

Field	Type	Description
`code`	string	Error code.
`msg`	string	Readable error message.
`data`	null	`null` in an error response.

Follow-up operations¶

Logging data.query_id (same as data.id). First query execution status; after the status indicates success, then query execution result or download execution result. Cancel execution when aborted.

Last updated on Sep 15, 2026