Use this guide when a query works but you want a clearer plan, more predictable local execution, or less terminal noise.

Set runtime workers explicitly

Start with an explicit worker count:

./target/debug/spiral sql --threads 8

--threads controls engine workers.

The default worker count is derived from available parallelism. Use explicit values when comparing local runs.

Limit preview rows intentionally

--max-rows changes how many rows the REPL asks the engine to collect for display:

./target/debug/spiral sql --max-rows 25

The REPL requests one extra row so it can report whether more rows are available. Add an explicit SQL ORDER BY ... LIMIT when you need a deterministic top-N result:

SELECT *
FROM events
ORDER BY event_time
LIMIT 25;

Inspect plans before timing

Use EXPLAIN for plan shape:

EXPLAIN
SELECT category, count(*)
FROM events
GROUP BY category;

Use EXPLAIN ANALYZE to execute the query and print an execution report:

EXPLAIN ANALYZE
SELECT category, count(*)
FROM events
GROUP BY category;

Declare correct keys

When a Vortex file is sorted by a unique key, declare it:

.open orders ./orders.vortex --key o_orderkey

Correct keys let Spiral preserve and exploit ordering. Incorrect keys can make operators fail when they validate the relation contract, so omit --key unless you know the data is sorted and unique.

Prefer top-k for inspection

ORDER BY with LIMIT uses the Top-K planning path:

SELECT id, score
FROM events
ORDER BY score DESC NULLS LAST
LIMIT 20;

Without LIMIT, the current binder only supports ascending NULLS FIRST ordering.

Implementation-level performance details belong in internal developer documentation or Rust module docs.