Execute SQL

POST /v1/tenants/{tenant}/sql

Run SQL and inspect its result kindMissing write counts are unknown; inspect all outcomes before retrying a batch.

Prepare SQL and parametersBind values rather than inserting them into SQL text.
Execute the statement or batchSend the required session ID when using a session.
Read rows or write resultsCheck kind and any nested or failed outcomes.

Before you start

Use your database bearer token.

For this example, register demo.people and insert the quickstart rows. params binds $1 to the first array value.

Path parameters

Field	Type	Required
`tenant`	`string`	Required

Headers

Field	Type	Required	Description
`x-oc-db-user`	`string`	Optional	Acting database user (role, grant and row-policy checks). Send with x-oc-db-key.
`x-oc-db-key`	`string`	Optional	API key of the x-oc-db-user user.

Request body

application/json

Limits and accepted values

params binds $1, $2 and later placeholders in array order. It cannot be combined with a multi-statement batch.
A batch holds at most 256 statements. DDL and explicit transaction boundaries affect its atomicity; do not assume every statement rolls back together. See SQL compatibility.
session_id pins the statement to the transaction a BEGIN opened, equivalent to the X-OC-Session-Id header.
Optional headers: X-OC-Session-Id, X-OC-Statement-Timeout-Ms (408 on expiry), X-OC-Query-Id (client-chosen ULID, usable for cancellation; 409 if already running), X-OC-DB-User for database-user identity.

Field	Type	Required
`params`	`any JSON[]`	Optional

Fields in params

Field	Type	Required
`params`	`any JSON`	Optional

Field	Type	Required
`session_id`	`string`	Optional
`sql`	`string`	Required

Check kind first. A select returns rows and column metadata; writes report the counts the engine confirms. Batches can contain nested outcomes or stop after a failed statement, so inspect the whole result before retrying. Missing write counts mean unknown.

Response statuses

HTTP status reference

Status	What to do
200	OK
202	Accepted
400	Correct the request before retrying.
401	Check the credential and Authorization header.
402	Check feature access or available credits.
403	Check tenant access, roles and permissions.
404	Check the resource ID and API route.
408	Reduce query work or adjust the timeout.
409	Resolve the conflict before retrying.
413	Split or reduce the request body.
415	Send the required Content-Type.
422	Correct the values or unsupported combination.
429	Honor Retry-After when present; back off.
499	The client cancelled the request.
500	Check the outcome before retrying a write.
501	Check deployment support for this operation.
502	Check service availability and the write outcome.
503	Honor Retry-After when present; check write outcomes.

Request example

curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/sql" \
  --header "Authorization: Bearer ${OC_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary '{
  "sql": "SELECT id, score FROM demo.people WHERE score >= $1 ORDER BY id LIMIT 10",
  "params": [
    10
  ]
}'

Response example

Examples use synthetic values to show the response format.

Response status

{
  "kind": "select",
  "columns": [
    "id",
    "score"
  ],
  "rows": [
    {
      "id": "u1",
      "score": 10
    },
    {
      "id": "u2",
      "score": 20
    },
    {
      "id": "u3",
      "score": 30
    }
  ]
}

{
  "kind": "droptable_accepted",
  "schema": "demo.people",
  "status": "accepted"
}

202 belongs to a DROP TABLE statement, not the SELECT request shown here; inspect the actual returned reclamation/status fields.

Download the OpenAPI specification for the complete response schemas.

Before you startCopy Anchor Link

Path parametersCopy Anchor Link

HeadersCopy Anchor Link

Request bodyCopy Anchor Link

Read the resultCopy Anchor Link

Response statusesCopy Anchor Link

Before you start

Path parameters

Headers

Request body

Read the result

Response statuses