Query Endpoints

The query endpoints handle synchronous and asynchronous query execution, status tracking, result retrieval, cancellation, and history. Served by QueryController at /v1/queries.

Endpoints

POST /v1/queries/execute

Executes a SQL query synchronously and returns results immediately.

Headers: X-Tenant-ID, X-User-ID (required)

{
  "sql": "SELECT customer_id, SUM(amount) FROM orders GROUP BY customer_id LIMIT 100",
  "catalog": "delta",
  "schema": "public",
  "limit": 100,
  "useCache": true,
  "timeoutSeconds": 300,
  "parameters": {},
  "sessionProperties": {}
}

Returns a QueryResponse with columns, data, row count, execution time, and cache hit status.

POST /v1/queries/execute/async

Submits a query for asynchronous execution. Returns an execution ID for polling.

{
  "executionId": "uuid",
  "status": "QUEUED",
  "message": "Query submitted for async execution"
}

Poll GET /v1/queries/:executionId/status until status reaches COMPLETED, FAILED, or CANCELLED.

GET /v1/queries/:executionId/results

Retrieves paginated results for a completed query.

POST /v1/queries/:executionId/cancel

Cancels a running or queued query.

{
  "executionId": "uuid",
  "cancelled": true,
  "message": "Query cancelled"
}

GET /v1/queries/my-history

Returns paginated query execution history for the authenticated user.

GET /v1/queries/stats

Returns aggregate query statistics for the tenant over a configurable window.