Query Endpoint

The /exec endpoint executes SQL queries and returns results as JSON.

Endpoint

GET /exec

Query Parameters

query

string

required

SQL query to execute. Must be URL-encoded.

limit

string

Limit the number of rows returned. Format: limit or skip,limit.Examples:

limit=100 - return first 100 rows
limit=50,100 - skip 50 rows, return next 100

Maximum controlled by http.json.query.max.response.rows (default: 10,000).

count

boolean

default:"false"

When true, only count rows without returning data. Response includes count field.

boolean

default:"false"

When true, exclude column metadata from response (no meta).

timings

boolean

default:"false"

When true, include query execution timings in response.

explain

boolean

default:"false"

When true, return query execution plan instead of results.

quoteLargeNum

boolean

default:"false"

When true, quote large numbers (LONG256) as strings to prevent precision loss in JSON.

cols

string

Comma-separated list of column names to return. Returns only specified columns.Example: cols=timestamp,sensor_id,temperature

Request Headers

Statement-Timeout

integer

Query timeout in milliseconds. Query is cancelled if it exceeds this duration.Example: 30000 (30 seconds)

Authorization

string

HTTP Basic authentication credentials (if authentication is enabled).Format: Basic base64(username:password)

Response

query

string

The executed SQL query.

columns

array

Array of column metadata objects (omitted if nm=true).

Show Column Object

name

string

Column name.

type

string

Column data type (e.g., TIMESTAMP, SYMBOL, DOUBLE, LONG, STRING).

dataset

array

Array of row arrays containing query results. Each row is an array of values matching the column order.

count

integer

Number of rows returned (or total count if count=true).

timings

object

Query execution timings in milliseconds (only if timings=true).

Show Timings Object

compiler

number

Time spent compiling the query.

execute

number

Time spent executing the query.

count

integer

Number of rows processed.

explain

object

Query execution plan (only if explain=true).

Error Response

query

string

The attempted SQL query.

error

string

Error message describing what went wrong.

position

integer

Character position in the query where the error occurred.

Examples

Basic SELECT Query

curl "http://localhost:9000/exec?query=SELECT+*+FROM+sensors+LIMIT+5"

{
  "query": "SELECT * FROM sensors LIMIT 5",
  "columns": [
    {"name": "timestamp", "type": "TIMESTAMP"},
    {"name": "sensor_id", "type": "SYMBOL"},
    {"name": "temperature", "type": "DOUBLE"},
    {"name": "humidity", "type": "DOUBLE"}
  ],
  "dataset": [
    ["2024-01-01T00:00:00.000000Z", "sensor_1", 23.5, 45.2],
    ["2024-01-01T00:01:00.000000Z", "sensor_2", 24.1, 46.8],
    ["2024-01-01T00:02:00.000000Z", "sensor_1", 23.8, 45.5],
    ["2024-01-01T00:03:00.000000Z", "sensor_3", 22.9, 44.1],
    ["2024-01-01T00:04:00.000000Z", "sensor_2", 24.3, 47.2]
  ],
  "count": 5
}

Query with Pagination

Skip the first 100 rows and return the next 50:

curl "http://localhost:9000/exec?query=SELECT+*+FROM+sensors&limit=100,50"

Count Only

Get row count without fetching data:

curl "http://localhost:9000/exec?query=SELECT+*+FROM+sensors&count=true"

{
  "query": "SELECT * FROM sensors",
  "count": 1000000
}

Query with Timings

curl "http://localhost:9000/exec?query=SELECT+avg(temperature)+FROM+sensors&timings=true"

{
  "query": "SELECT avg(temperature) FROM sensors",
  "columns": [
    {"name": "avg", "type": "DOUBLE"}
  ],
  "dataset": [
    [23.756]
  ],
  "count": 1,
  "timings": {
    "compiler": 0.234,
    "execute": 1.567,
    "count": 1000000
  }
}

INSERT Statement

curl "http://localhost:9000/exec?query=INSERT+INTO+sensors+VALUES('2024-01-01T12:00:00.000000Z','sensor_4',25.5,48.0)"

{
  "ddl": "OK"
}

CREATE TABLE

curl -G "http://localhost:9000/exec" \
  --data-urlencode "query=CREATE TABLE my_table (timestamp TIMESTAMP, value DOUBLE) timestamp(timestamp) PARTITION BY DAY"

{
  "ddl": "OK"
}

Query with Timeout

curl -H "Statement-Timeout: 5000" \
  "http://localhost:9000/exec?query=SELECT+*+FROM+large_table"

Select Specific Columns

curl "http://localhost:9000/exec?query=SELECT+*+FROM+sensors&cols=timestamp,temperature"

{
  "query": "SELECT * FROM sensors",
  "columns": [
    {"name": "timestamp", "type": "TIMESTAMP"},
    {"name": "temperature", "type": "DOUBLE"}
  ],
  "dataset": [
    ["2024-01-01T00:00:00.000000Z", 23.5],
    ["2024-01-01T00:01:00.000000Z", 24.1]
  ],
  "count": 2
}

Error Examples

Syntax Error

curl "http://localhost:9000/exec?query=SELCT+*+FROM+sensors"

{
  "query": "SELCT * FROM sensors",
  "error": "'from' expected",
  "position": 0
}

Table Not Found

curl "http://localhost:9000/exec?query=SELECT+*+FROM+nonexistent"

{
  "query": "SELECT * FROM nonexistent",
  "error": "table does not exist [table=nonexistent]",
  "position": 14
}

Query Timeout

curl -H "Statement-Timeout: 100" \
  "http://localhost:9000/exec?query=SELECT+*+FROM+huge_table"

{
  "query": "SELECT * FROM huge_table",
  "error": "Query timeout. Please add HTTP header 'Statement-Timeout' with timeout in ms [timeout=100ms]",
  "position": 0
}

Supported SQL Operations

The /exec endpoint supports all SQL operations:

SELECT - Query data
INSERT - Insert rows
UPDATE - Update rows (with conditions)
CREATE TABLE - Create new tables
ALTER TABLE - Modify table structure
DROP - Drop tables or columns
TRUNCATE - Remove all rows from a table
COPY - Not supported over REST (use PostgreSQL wire protocol)

Data Types

Column types in the response:

Type	JSON Representation	Example
`BOOLEAN`	boolean	`true`
`BYTE`	number	`127`
`SHORT`	number	`32767`
`INT`	number	`2147483647`
`LONG`	number	`9223372036854775807`
`FLOAT`	number	`3.14`
`DOUBLE`	number	`3.141592653589793`
`STRING`	string	`"hello"`
`SYMBOL`	string	`"BTCUSD"`
`TIMESTAMP`	string (ISO 8601)	`"2024-01-01T00:00:00.000000Z"`
`DATE`	string (ISO 8601)	`"2024-01-01"`
`UUID`	string	`"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"`
`LONG256`	string (hex)	`"0x123abc..."`
`GEOHASH`	string	`"sp052w"`
`BINARY`	null	`null`

Best Practices

Use the limit parameter to control response size. The default maximum is 10,000 rows.

Enable timings=true during development to optimize query performance.

Always URL-encode query parameters. Use -G --data-urlencode with curl or equivalent in your HTTP library.

The query cache improves performance for repeated queries. Queries with sensitive information (e.g., passwords) are not cached.

REST API

PostgreSQL Wire Protocol

InfluxDB Line Protocol

SQL Functions

Endpoint

Query Parameters

Request Headers

Response

Error Response

Examples

Basic SELECT Query

Count Only

Query with Timings

INSERT Statement

CREATE TABLE

Query with Timeout

Select Specific Columns

Error Examples

Syntax Error

Table Not Found

Query Timeout

Supported SQL Operations

Data Types

Best Practices

Build docs developers (and LLMs) love

REST API

PostgreSQL Wire Protocol

InfluxDB Line Protocol

SQL Functions

​Endpoint

​Query Parameters

​Request Headers

​Response

​Error Response

​Examples

​Basic SELECT Query

​Query with Pagination

​Count Only

​Query with Timings

​INSERT Statement

​CREATE TABLE

​Query with Timeout

​Select Specific Columns

​Error Examples

​Syntax Error

​Table Not Found

​Query Timeout

​Supported SQL Operations

​Data Types

​Best Practices

Build docs developers (and LLMs) love

Endpoint

Query Parameters

Request Headers

Response

Error Response

Examples

Basic SELECT Query

Query with Pagination

Count Only

Query with Timings

INSERT Statement

CREATE TABLE

Query with Timeout

Select Specific Columns

Error Examples

Syntax Error

Table Not Found

Query Timeout

Supported SQL Operations

Data Types

Best Practices