Query admission and limits

Query admission protects the single engine process from concurrency and intermediate-result overload. Limits are process-wide startup controls.

Current defaults

Numeric ceilings accept 0 as disabled where stated by --help. --max-concurrent-queries=0 disables the admission gate and --query-timeout-ms=0 disables the deadline; reserve those settings for a controlled bulk workload with an independent envelope. The process exact-native flag has a minimum of one byte: a local operator-memory value of zero does not disable that shared backstop. Only --memory-governor=off disables it.

Admission behavior

When all execution slots are occupied:

1. a request joins the bounded waiting queue if space exists;
2. it competes for a released slot when work completes; FIFO order is not guaranteed;
3. it fails with a queue timeout if no slot arrives before the deadline; or
4. it fails immediately as server busy when the queue is full or disabled.

Protocol ping is deliberately outside query admission so health remains observable under query saturation.

queue_us in system.queries and system.query_log separates admission wait from execution work.

Execution ceilings

The monotonic query deadline is checked at bounded execution checkpoints. CANCEL QUERY, wire request cancellation, and peer disconnect use the same cooperative cancellation path.

Output row and byte ceilings prevent a valid query from materializing or rendering an unbounded response. Operator memory/cardinality ceilings protect hash aggregation, join, sort, window, and dedup state.

These limits are complementary: a low-row result can still have a large intermediate join or sort, and a million narrow rows can still exceed the byte ceiling.

Exact aggregate memory

count_distinct, uniq, and uniq_exact use exact state in the current release. Their hash buckets, metadata arrays, replacement peaks, and string arena chunks are charged before allocation to both the statement-local operator budget and one process-wide counter shared by concurrent queries. Exact aggregate input crosses the native ABI in batches of at most 4,096 rows, so a large string scan cannot allocate one carrier per source row before budget and cancellation checks run.

The process ceiling resolves at startup as:

min(--query-global-exact-memory-bytes, 50% of resolved process/cgroup limit)

If the process limit cannot be detected, the finite configured ceiling remains. A local --query-max-operator-memory-bytes=0 trusted-bulk override does not bypass it. A rejected local or global reservation fails the statement with a stable NYXDB_EXEC_BUDGET_EXCEEDED: ... memory ... diagnostic, destroys its native state, releases the global reservation, and leaves the process available for the next query.

Cancellation and client disconnect

The request envelope's 16-byte correlation ID can target a pending or executing one-shot through wire operation OP_CANCEL_REQUEST (0x0A). Registration occurs before bounded admission, and the control operation bypasses query admission, so an overloaded queue cannot prevent cancellation. This is separate from the numeric engine query_id used by SQL CANCEL QUERY and telemetry.

Production one-shots also attach a peer-liveness probe. Raw TCP FIN/reset and WebSocket Close become NYXDB_EXEC_CANCELLED: client disconnected at the next checkpoint, including through parallel storage reads. WebSocket checkpoints service Ping/Pong and preserve bounded pipelined application frames instead of discarding them. The checkpoint interval is a maximum in work units, not a wall-clock cancellation SLA.

See Experimental wire protocol for request/response framing and the supported target operations.

Diagnose saturation

SELECT query_id, statement, state, elapsed_us, queue_us,
       peak_memory_bytes, rows_scanned, rows_returned,
       op_join_us, op_aggregate_us, op_sort_us
FROM system.queries
ORDER BY elapsed_us DESC;

SELECT ended_ms, query_id, statement, ok, error, queue_us,
       exec_us, peak_memory_bytes, rows_scanned
FROM system.query_log
WHERE ok = '0'
ORDER BY ended_ms DESC
LIMIT 100;

For an exact-aggregate memory rejection, expect completed rows_scanned, a nonzero recorded peak, and the sticky memory reason in system.query_log even though current memory has been released. For a disconnected one-shot, expect the distinct client-disconnected cancellation reason rather than a generic transport error.

Cancel only after recording the query and owner:

CANCEL QUERY 42;

Tune safely

• Size concurrency from CPU, storage latency, and the heaviest admitted operator—not client count.
• Keep queue depth finite so overload produces bounded failure instead of hidden latency.
• Set client deadlines longer than the server deadline plus expected queue and transport time.
• Paginate or aggregate large one-shot results.
• Use EXPLAIN and pruning counters before increasing operator budgets.
• Separate bulk ingest periods from latency-sensitive query service when possible.
• Load-test the combined connection, query, stream, and ingest envelope.

Retry server-busy or queue-timeout failures with bounded exponential backoff and jitter only when the operation is safe to repeat. A transport failure after DDL or DML was sent is ambiguous; reconcile server state before retrying.