Use this guide when you already have one or more Vortex files and want to check their schema and sample rows from the Spiral REPL.

Start with a low display limit

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

--max-rows limits the REPL preview size by collecting at most one extra row for display. Use an explicit SQL ORDER BY ... LIMIT when you need a deterministic sample.

Open the file

.open sample ./sample.vortex

The REPL prints the registered table name, file count, and key:

opened `sample` (1 file(s), ordinal key)

Inspect schema

.tables
.schema sample

Use .schema with no argument to print all registered table schemas.

Query a sample

Opened files are registered as local REPL tables in the memory catalog.

SELECT *
FROM memory.sample
LIMIT 20;

For a quick column check:

SELECT count(*) AS rows
FROM memory.sample;

Declare a key when you know one

If the file is sorted by a unique column or column tuple, reopen it with --key:

.open sample ./sample.vortex --key id

or:

.open sample ./sample.vortex --key=id

Use comma-separated columns for a compound key:

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

Only declare a column key when the data is sorted by that key and every key is unique. When in doubt, omit --key and use the ordinal key.

Register multiple files

Pass every path explicitly:

.open events ./part-000.vortex ./part-001.vortex ./part-002.vortex --key event_id

The interactive REPL does not expand shell globs. If you want to use shell expansion, generate the .open command outside the REPL and paste the expanded paths.