Query Execution

The Query Engine supports two primary execution modes -- synchronous and asynchronous -- each designed for different workload patterns. This section covers the complete query execution subsystem, from initial submission through validation, optimization, engine routing, execution, and result delivery.

Execution Modes

Mode	Endpoint	Best For	Default Timeout
Synchronous	`POST /v1/queries/execute`	Interactive queries, small result sets, dashboard queries	300 seconds
Asynchronous	`POST /v1/queries/execute/async`	Large scans, batch processing, long-running analytics	No hard limit

Both modes share the same core pipeline: validation, cache lookup, engine routing, RLS injection, execution, and result caching. The difference is in how the client receives results.

Query Request Structure

Every query begins with a QueryRequest payload submitted to the Query Engine. The request DTO is defined in QueryRequest.java:

public class QueryRequest {
    private UUID queryId;
    private UUID tenantId;
 
    @NotBlank(message = "SQL query is required")
    @Size(max = 100000, message = "Query text cannot exceed 100,000 characters")
    private String sql;
 
    private String catalog;
    private String schema;
    private Integer limit;
    private Integer offset;
    private Boolean useCache;
    private Integer timeoutSeconds;
    private Map<String, Object> parameters;
    private Map<String, String> sessionProperties;
    private Map<String, Object> metadata;
}

Field Reference

Field	Type	Required	Default	Description
`sql`	String	Yes	--	The SQL query to execute (max 100,000 characters)
`catalog`	String	No	`delta`	Trino catalog to target
`schema`	String	No	`default`	Schema within the catalog
`limit`	Integer	No	10,000	Maximum rows to return
`useCache`	Boolean	No	`true`	Whether to check and populate the query cache
`timeoutSeconds`	Integer	No	300	Timeout in seconds for synchronous execution
`parameters`	Map	No	--	Parameterized query values
`sessionProperties`	Map	No	--	Trino session properties to set
`metadata`	Map	No	--	Billing context, cost center, workload type

Query Response Structure

All execution endpoints return a QueryResponse:

{
  "executionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "COMPLETED",
  "engineType": "TRINO",
  "columns": [
    { "name": "customer_id", "type": "VARCHAR", "nullable": true },
    { "name": "total_orders", "type": "BIGINT", "nullable": true }
  ],
  "data": [
    { "customer_id": "C-001", "total_orders": 42 },
    { "customer_id": "C-002", "total_orders": 17 }
  ],
  "rowCount": 2,
  "totalRows": 2,
  "bytesScanned": 1048576,
  "executionTimeMs": 245,
  "cacheHit": false,
  "hasMore": false,
  "submittedAt": "2026-02-12T10:00:00Z",
  "completedAt": "2026-02-12T10:00:00.245Z",
  "statistics": {
    "cpuTimeMs": 180,
    "wallTimeMs": 245,
    "queuedTimeMs": 5,
    "analysisTimeMs": 12,
    "planningTimeMs": 28,
    "peakMemoryBytes": 67108864,
    "inputRows": 50000,
    "inputBytes": 1048576,
    "outputRows": 2,
    "outputBytes": 128,
    "completedSplits": 4
  }
}

Query Status Enumeration

The QueryStatus enum defines the lifecycle states of a query execution:

Status	Description
`PENDING`	Query received, awaiting processing
`QUEUED`	Query accepted into the execution queue
`RUNNING`	Query actively executing on the target engine
`COMPLETED`	Query finished successfully with results available
`FAILED`	Query execution failed with an error
`CANCELLED`	Query was cancelled by the user or system
`TIMEOUT`	Query exceeded the configured timeout

Supported Engine Types

The EngineType enum lists all supported execution backends:

Engine	Use Case	Routing Trigger
`TRINO`	Complex analytics, window functions, multi-join queries	Default for most queries; complex SQL patterns
`CLICKHOUSE`	Real-time tables (events, clicks, metrics), simple aggregations	Tables matching real-time patterns; simple queries under 1M rows
`DUCKDB`	Local analytical queries, embedded processing	Small datasets, local file queries
`STARROCKS`	High-throughput OLAP, materialized view serving	Pre-aggregated data, high-concurrency reads
`SPARK_ASYNC`	Large-scale scans exceeding 100GB	Estimated scan size above 100GB threshold

Subsections

Page	Description
Synchronous Execution	Sync execution flow, timeout handling, cache integration
Asynchronous Execution	Async submission, status polling, result retrieval
Query Lifecycle	Full lifecycle from submit through validate, optimize, execute, return
Query Cancellation	Cancelling running and queued queries
Query History	Querying execution history with search and pagination
Query Statistics	Execution statistics, success rates, latency percentiles

Engine Architecture Synchronous Execution