Query Engine API Reference
The Query Engine exposes REST APIs for query execution, analytics, caching, result export, scheduling, and cost estimation. All endpoints are served on port 8080 under the /v1 prefix and require tenant context via the X-Tenant-ID header.
Base URL
https://:hostname/v1Endpoint Groups
| Group | Base Path | Description |
|---|---|---|
| Query Endpoints | /v1/queries | Execute, cancel, and manage queries |
| Analytics Endpoints | /v1/analytics | Performance analytics, trends, insights |
| Cache Endpoints | /v1/cache | Cache management, invalidation, warming |
| Export Endpoints | /v1/queries | Export results to CSV, JSON, Parquet |
| Schedule Endpoints | /v1/schedules | Create and manage scheduled queries |
| Cost Endpoints | /v1/queries/cost | Query cost estimation and comparison |
Common Headers
| Header | Required | Description |
|---|---|---|
X-Tenant-ID | Yes | UUID of the tenant |
X-User-ID | Some endpoints | UUID of the executing user |
Authorization | Yes | Bearer JWT token |
Supported Query Engines
| Engine | Description |
|---|---|
TRINO | Default engine for complex analytics and multi-join queries |
CLICKHOUSE | Real-time tables and simple aggregations |
DUCKDB | Local analytical queries and embedded processing |
STARROCKS | High-throughput OLAP and materialized view serving |
SPARK_ASYNC | Large-scale scans exceeding 100GB |
Common Error Responses
| Status | Description |
|---|---|
| 400 | Invalid SQL syntax or request parameters |
| 401 | Missing or invalid authentication token |
| 403 | Query blocked by row-level security or quota limit |
| 404 | Query execution or resource not found |
| 408 | Query execution timeout exceeded |
| 429 | Query concurrency limit exceeded |