Skip to main content
POST
/
sql
Execute SQL query
curl --request POST \
  --url https://{branch}.{region}.xata.tech/sql \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "params": [
    "<unknown>"
  ],
  "queries": [
    {
      "query": "<string>",
      "params": [
        "<unknown>"
      ],
      "arrayMode": true
    }
  ],
  "arrayMode": true
}
'
{
  "fields": [
    {
      "name": "<string>",
      "tableID": 123,
      "columnID": 123,
      "dataTypeID": 123,
      "dataTypeSize": 123,
      "dataTypeModifier": 123,
      "format": "<string>"
    }
  ],
  "command": "<string>",
  "rowCount": 123,
  "rows": [
    "<unknown>"
  ],
  "rowAsArray": true
}

Headers

​
Connection-String
string<uri>

PostgreSQL connection string (postgres://user:pass@host/db). The hostname encodes the target branch and endpoint type.

​
Array-Mode
enum<string>

When true, return rows as arrays instead of objects.

Available options:
true,
false
​
Raw-Text-Output
enum<string>

When true, return all values as strings without type conversion.

Available options:
true,
false
​
Batch-Isolation-Level
enum<string>

Transaction isolation level for batch queries.

Available options:
ReadCommitted,
ReadUncommitted,
RepeatableRead,
Serializable
​
Batch-Read-Only
enum<string>

When true, execute the batch transaction in read-only mode.

Available options:
true,
false
​
Batch-Deferrable
enum<string>

When true, execute the batch transaction in deferrable mode.

Available options:
true,
false

Body

application/json

SQL query request. Provide either query for a single query or queries for a batch.

​
query
string

SQL query to execute (single query mode).

​
params
any[]

Positional parameters for the query ($1, $2, ...).

​
queries
object[]

Array of queries for batch execution within a single transaction.

​
arrayMode
boolean

Override array mode for this query (single query mode only).

Response

Query executed successfully

Result of a single SQL query execution.

​
fields
object[]
required

Column metadata for the result set.

​
command
string
required

PostgreSQL command tag (e.g. SELECT, INSERT, UPDATE, DELETE).

​
rowCount
integer | null
required

Number of rows affected by the command.

​
rows
any[]
required

Result rows. Each row is an object (column-name keys) or an array (when array mode is enabled).

​
rowAsArray
boolean
required

Whether rows are returned as arrays (true) or objects (false).