Execute cross-table SQL query

POST

/queries

Production API

Execute a SQL query across one or more dataset tables.

Request Body:

tables: Map of table names (as referenced in SQL) to table IDs
sql: SQL query to execute
maxRows: Maximum rows to return (default: 1000, max: 10000)
includeStats: Whether to include execution statistics

Response Formats (Accept header):

application/json (default): JSON response with rows, columns, and metadata
application/vnd.apache.arrow.stream: Raw Arrow IPC binary data with metadata in headers:
- X-Query-Id: Unique query identifier
- X-Row-Count: Number of rows returned
- X-Truncated: Whether results were truncated
- X-Table-Versions: JSON map of table ID to dataset version queried

Phase 1 Constraint: All tables must belong to the same team.

Authorizations

bearerAuth
cookieAuth

Request Body

object

tables

required

object

key

additional properties

Any of:

Dataset table ID (backwards compatible format)

string

sql

required

string

>= 1 characters

maxRows

integer

>= 1 <= 10000

includeStats

boolean

Responses

200

Query executed successfully

object

queryId

required

string

columns

required

Array<object>

object

name

required

Column name

string

type

required

Arrow data type of the column

string

rows

required

Array<object>

object

key

additional properties

nullable

rowCount

required

number

truncated

required

boolean

stats

object

executionTimeMs

required

Total query execution time in milliseconds

number

planningTimeMs

Time spent planning the query in milliseconds

number

bytesScanned

Total bytes read from storage

number

rowsScanned

Total rows scanned during query execution

number

usage

object

getOptsCold

required

GET operations (full object fetch) - cache miss

number

getOptsWarm

required

GET operations (full object fetch) - cache hit

number

getRangeCold

required

Range read operations - cache miss

number

getRangeWarm

required

Range read operations - cache hit

number

getRangesCold

required

Multi-range read operations - cache miss

number

getRangesWarm

required

Multi-range read operations - cache hit

number

headCold

required

HEAD (metadata) operations - cache miss

number

headWarm

required

HEAD (metadata) operations - cache hit

number

listCold

required

LIST operations (directory listing) - cache miss

number

listWarm

required

LIST operations (directory listing) - cache hit

number

putOperations

required

PUT operations (writes are never cached)

number

deleteOperations

required

DELETE operations

number

cacheHitRatePercent

required

Overall cache hit rate as a percentage (0-100)

number

readBytesCold

required

Total bytes read from upstream storage (cache miss)

number

readBytesWarm

required

Total bytes read from L2 cache (cache hit)

number

writeBytes

required

Total bytes written (PUT operations)

number

tableVersions

required

object

key

additional properties

number

400

Bad Request - Validation error or invalid input

object

error

required

string

code

string

details

nullable

retryable

boolean

401

Unauthorized - Authentication required or invalid token

object

error

required

string

code

string

details

nullable

retryable

boolean

403

Forbidden - Insufficient permissions

object

error

required

string

code

string

details

nullable

retryable

boolean

404

Not Found - Resource does not exist

object

error

required

string

code

string

details

nullable

retryable

boolean