Skip to navigation
API ReferenceQuery Execution

Execute SQL statement

View as Markdown

Executes an SQL statement and returns the results. Supports both regular and streaming responses. For streaming, use Accept: application/stream+json header.

The database can be specified in the request body, or defaults to the database from the authentication token or system settings.

Streaming Large Results

For queries that may return large result sets, use the streaming response format:

Accept: application/stream+json

With streaming, results are returned as they become available using HTTP chunked transfer encoding. Each chunk contains a valid JSON object that can be parsed independently.

Parameterized Queries

For queries with variable inputs, use parameterized queries instead of string concatenation:

{
  "statement": "SELECT * FROM orders WHERE order_date > :start_date AND customer_id = :customer_id",
  "params": {
    "start_date": "2023-01-01",
    "customer_id": 12345
  }
}

Authentication

AuthorizationBearer
Access token obtained from the login endpoint
OR
AuthorizationBasic
HTTP Basic authentication with username and password

Headers

Accept-EncodingstringOptional

Supported compression algorithms for responses. Multiple algorithms can be specified as a comma-separated list. Common values include ‘gzip’, ‘deflate’, ‘br’ (Brotli), or combinations like ‘gzip, br’.

Note that for large result sets, compression may produce suboptimal results. Without compression the result sets can be chunks of rows and processed in a streaming fashion. With compression the entire result set must be compressed before it is returned to the client. Thus the entire result set will be decompressed on the client before any rows can be processed

AcceptenumOptionalDefaults to application/json
Supported response media types. Note that regardless of the Accept header, large queries results will always be returned via chunked encoding. Also see the note about compression in the AcceptEncoding section.
Allowed values:
Preferred-EncodingenumOptional

Indicates the preferred encoding type from those specified in Accept-Encoding. This header provides fine-grained control when Accept-Encoding contains multiple values, allowing the client to explicitly specify which encoding is preferred for this specific request.

Allowed values:
Preferred-Compression-LevelintegerOptional

Specifies the desired compression level for the selected encoding algorithm. Values typically range from 1 (fastest, least compression) to 9 (slowest, maximum compression). The exact behavior depends on the specific compression algorithm being used.

Query parameters

formatenumOptionalDefaults to array

Response format:

  • array - Returns schema and data as arrays (more efficient for large datasets)
  • collection - Returns data as JSON objects (more convenient for client processing)

Note: This parameter is only applicable when using Content-Type: text/plain. When using Content-Type: application/json, specify format in the request body.

Allowed values:
schemastringOptional

The schema to use for the SQL statement.

Note: This parameter is only applicable when using Content-Type: text/plain. When using Content-Type: application/json, specify schema in the request body.

Request

This endpoint expects an object.
statementstringRequired

Parameters to substitute in the SQL statement. The keys should match the parameter names in the statement (without the enclosing braces). String values are wrapped in single quotes, all other types are unquoted. Null values will be expanded as null.

Example: If your SQL is SELECT * FROM orders WHERE order_date > {start_date}, you would provide {"start_date": "2023-01-01"} in this field.

databasestringOptional
Target database name to execute the query against. If not specified, the database from authentication will be used.
formatenumOptionalDefaults to array

Response format:

  • array - Returns schema and data as arrays (more efficient for large datasets)
  • collection - Returns data as JSON objects (more convenient for client processing)
Allowed values:
paramsmap from strings to anyOptional

Parameters to substitute in the SQL statement. The keys should match the parameter names in the statement (without the enclosing braces). String values are wrapped in single quotes, all other types are unquoted. Null values will be expanded as null.

Example: If your SQL is SELECT * FROM orders WHERE order_date > {start_date}, you would provide {"start_date": "2023-01-01"} in this field.

fetch_sizeintegerOptional>=0Defaults to 0

Number of rows to return in each chunk for streaming responses. A value of 0 means the database can determine how many to return.

  • For interactive applications: Use smaller values (100-1000)
  • For batch processing: Use larger values (5000-10000)
max_rowsintegerOptional>=0Defaults to 9223372036854776000

The maximum number of rows to return. Note that the SQL LIMIT clause is much preferred, since the query engine will generate the total number of rows, but then only max_rows will be returned to the caller.

schemastringOptional
The schema to use for this statement

Response headers

X-QueryIdstringOptional
Unique identifier for the query
X-SQLStatestringOptional
SQL state result of the operation
X-SQLCodestringOptional
SQL code result of the operation

Response

Query executed successfully
object
OR
object

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
500
Internal Server Error