Skip to content

Execute read-only SQL query

POST
/v1/query/run
curl --request POST \
--url https://localhost:8080/v1/query/run \
--header 'Content-Type: application/json' \
--data '{ "limit": 100, "sql": "SELECT id, email FROM customers WHERE created_at > '\''2026-01-01'\'' ORDER BY id" }'

Env-enzo sidecar API: served by the per-request env-enzo container, not by env-manager, so this path is never called directly. Reach it through POST /v1/requests/{id}/query (session or X-API-Key; forwards sql only) or through the tunnel edge POST /v1/tunnels/{id}/edge/api/query/run (tunnel credentials; forwards the whole body). Both proxy the request body and this response verbatim.

Runs one read-only statement in DuckDB SQL dialect against the enclave’s local database, where each dataset of the request is a table named by its relation name (listed by GET /v1/requests/{id}/status). Statements starting with INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, REPLACE or MERGE are rejected with 400. Rows are capped at limit, itself capped at 10000; truncated reports whether the cap cut the result. columns carries the SELECT column order, which the alphabetically-keyed row objects lose.

Errors: 400 for an empty or write statement and for DuckDB parser/binder/catalog errors (the message is DuckDB’s own); 409 while the datasets are still loading right after activation (retry shortly, or poll GET /v1/requests/{id}/status until ready); 429 when the sidecar rate limit is exceeded; 500 for any other failure.

SQL statement to run

Media typeapplication/json
object
limit

Limit caps the number of rows returned. Omitted, 0, negative, or above 10000 all fall back to the 10000-row cap; when the cap truncates the result, the response sets truncated=true. Only honoured on the tunnel edge: the env-manager route POST /v1/requests/{id}/query forwards sql only.

integer
<= 10000

Example

100
sql
required

SQL is a single read-only statement in DuckDB SQL dialect, run against the enclave’s local DuckDB database. Table names are the request’s dataset relation names (see GET /v1/requests/{id}/status). Statements beginning with INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, REPLACE or MERGE are rejected with 400.

string

Example

SELECT id, email FROM customers WHERE created_at > '2026-01-01' ORDER BY id

Column order, rows and truncation flag

Media typeapplication/json
object
columns

Columns are the result column names in SELECT order. The row objects in results are JSON objects whose keys are serialised alphabetically, so this list is the only place the query’s column order survives.

Array<string>
results

Results holds one object per row, keyed by column name. DuckDB values map to their natural JSON type (numbers, strings, booleans, null); timestamps and dates are RFC 3339 strings and INTERVAL values are rendered as DuckDB prints them (e.g. “1 year 2 days 04:05:06”). Empty when the query matched no rows.

Array<object>
object
key
additional properties
truncated

Truncated is true when more rows were available than the effective limit allowed and the result was cut off at that limit.

boolean

Example

{
"columns": [
"id",
"email"
],
"truncated": false
}

Empty or write statement, or a DuckDB parser/binder/catalog error

Media typeapplication/json
object
error

Error is a human-readable message. For 400 it is either the validation failure (“sql field is required and cannot be empty”, “write operations are not allowed”) or DuckDB’s own parser/binder/catalog message so the SQL can be fixed; for 409 the datasets are still loading and the query should be retried shortly.

string

Example

{
"error": "Binder Error: Referenced column \"emial\" not found in FROM clause!"
}

Datasets still loading into the enclave; retry

Media typeapplication/json
object
error

Error is a human-readable message. For 400 it is either the validation failure (“sql field is required and cannot be empty”, “write operations are not allowed”) or DuckDB’s own parser/binder/catalog message so the SQL can be fixed; for 409 the datasets are still loading and the query should be retried shortly.

string

Example

{
"error": "Binder Error: Referenced column \"emial\" not found in FROM clause!"
}

Rate limit exceeded

Media typeapplication/json
object
error

Error is a human-readable message. For 400 it is either the validation failure (“sql field is required and cannot be empty”, “write operations are not allowed”) or DuckDB’s own parser/binder/catalog message so the SQL can be fixed; for 409 the datasets are still loading and the query should be retried shortly.

string

Example

{
"error": "Binder Error: Referenced column \"emial\" not found in FROM clause!"
}

Query execution failed

Media typeapplication/json
object
error

Error is a human-readable message. For 400 it is either the validation failure (“sql field is required and cannot be empty”, “write operations are not allowed”) or DuckDB’s own parser/binder/catalog message so the SQL can be fixed; for 409 the datasets are still loading and the query should be retried shortly.

string

Example

{
"error": "Binder Error: Referenced column \"emial\" not found in FROM clause!"
}