Skip to main content
POST
`POST /orgs/{org_id}/connectors/{connector_id}/query`

Authorizations

Authorization
string
header
required

Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.

Path Parameters

org_id
string
required
connector_id
string
required

Body

application/json
connection_ref
string
required

Connection ref on the node (from /browse/connections).

sql
string
required

The SQL to run. One statement on MySQL; multi-statement batches work on Postgres and SQL Server (the last result set is returned; on Postgres that's the last row-returning set — zero-row sets are invisible to the node's driver — while SQL Server returns the true last set even when empty).

max_rows
integer<int32> | null

Row cap on the returned result. Defaults to 500, ceiling 10000.

Required range: x >= 0
mode
string | null

read (default) | write. read is enforced node-side with engine-level read-only semantics; write additionally requires the connection's local policy (connections.json) to allow writes.

timeout_ms
integer<int64> | null

Node-side execution budget in milliseconds. Defaults to 30000, ceiling 60000.

Required range: x >= 0

Response

Query executed

columns
object[]
required
row_count
integer
required
Required range: x >= 0
rows
object[][]
required

Row-major, aligned with columns. Cells are plain JSON scalars: numbers stay numbers, exact decimals and timestamps are strings, binary is 0x-prefixed hex, NULL is null.

truncated
boolean
required

The node's row or byte cap bit — rows is a prefix of the real result.

rows_affected
integer<int64> | null

Rows changed by non-row-returning statements, when the engine reports it (Postgres/MySQL; null on SQL Server = unknown, not zero).

Required range: x >= 0