Every Spiral relation has a key. A key describes the ordering and uniqueness contract that operators may rely on. The current client exposes two key modes:

Ordinal keys

Ordinal keys use the source row order as the relation key. This is the default for Vortex files and the only key mode for in-memory REPL tables.

.open events ./events.vortex

Use the ordinal key when you do not know whether the file is sorted by a unique column key.

Column keys

Use a column key only when every row has a unique key and the table is sorted by that key.

.open orders ./orders.vortex --key o_orderkey
.open lineitem ./lineitem.vortex --key l_orderkey,l_linenumber

--key=o_orderkey and --key o_orderkey are equivalent.

Keys matter because Spiral plans around order. A correctly declared key can avoid a sort, enable range-addressable scans, and preserve deterministic batching.

Incorrect keys

A false key declaration can make a query fail when an operator validates the contract. Prefer the ordinal key when key ordering or uniqueness is uncertain.

Compound keys

Compound keys are comma-separated and ordered:

.open lineitem ./lineitem.vortex --key l_orderkey,l_linenumber

The first column is the leading key component.