How Neutron runs queries#

Neutron evaluates admitted SQL against exact Iceberg snapshots. Its central rule is that memory is a budget established before allocation, not a hope checked after the process grows.

Admission fixes meaning#

The query frontend parses one statement, classifies unsupported capabilities, resolves lake names, and chooses snapshots. Neutron receives a closed plan and scoped table access. It cannot attach an arbitrary catalog or turn read access into a write.

The dialect and semantic-table versions participate in identity. A change to parsing or value semantics invalidates cached assumptions rather than silently reusing a result from a different language.

Memory is explicit#

Operators reserve memory before retaining rows, keys, decoded pages, or spill metadata. Hash aggregation, joins, sorting, windows, and materialization each have bounded state paths. Speculative reads charge the same budget as demanded reads.

When an eligible query exhausts its assigned budget, Supernova can retry it with a larger class. The retry keeps the SQL and selected snapshots fixed. A query that cannot fit the available ceiling fails instead of letting the host decide through an uncontrolled out-of-memory kill.

Reads are pruned#

Catalog metadata identifies manifests, files, row groups, and statistics. Projection pruning avoids decoding columns that the surrounding query never consumes. Predicate evidence can remove files and groups before their data moves.

Metadata and data use separate bounded caches because a large data span must not evict the small manifests needed to plan the next read. Fetch and decode overlap within the reservation budget.

Determinism is graded#

Operators define ordering, null, floating-point, timestamp, decimal, JSON, and collection behavior against the dialect contract. Queries without order by do not promise presentation order. Queries with order-sensitive operations receive a fixed answer under their documented semantics.

Neutron can run beside the incumbent engine on the same query and snapshots. Comparison distinguishes exact, order-insensitive, tolerance-governed, and non-comparable results. Performance alone never overrides a value mismatch.

Wrong results are corruption#

A crash or resource refusal is visible and retryable. A plausible wrong row is worse because it can enter a model or decision unnoticed. Neutron therefore treats semantic disagreement as a correctness incident: preserve evidence, identify the first divergent operator, and keep the affected path out of primary service.

That posture explains why unsupported constructs fail by name. A precise refusal is safer than partial syntax that happens to return rows.