This quickstart uses an in-memory table so it works without downloading a dataset. If you already have a Vortex file, see Inspect a Vortex file.

Start the REPL

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

Or run it through Cargo:

cargo run -p spiral-cli -- sql --max-rows 20

Create a small table

SQL statements must end with ;.

CREATE TABLE metrics (
  id BIGINT,
  category TEXT,
  score DOUBLE,
  active BOOLEAN
);

Insert a few rows:

INSERT INTO metrics VALUES
  (1, 'search', 0.82, true),
  (2, 'search', 0.91, true),
  (3, 'vision', 0.74, false),
  (4, 'vision', 0.88, true);

The REPL prints:

OK, 4 row(s) affected

Inspect the session

Dot commands do not use semicolons:

.tables
.schema metrics

metrics is an in-memory table with an ordinal key. The SQL REPL starts with the SpiralDB catalog selected, so local tables are queried through the memory catalog. When a query runs, Spiral materializes the table through the same Vortex scan path used by file-backed tables.

Run a query

SELECT
  category,
  count(*) AS rows,
  sum(score) AS total_score
FROM memory.metrics
WHERE active IS NOT NULL
GROUP BY category
HAVING count(*) > 0
ORDER BY total_score DESC
LIMIT 10;

Inspect the plan

EXPLAIN
SELECT category, count(*) AS rows
FROM memory.metrics
GROUP BY category;

EXPLAIN prints the planned relation without executing the query. Use EXPLAIN ANALYZE when you want to execute the query and print an execution report:

EXPLAIN ANALYZE
SELECT category, count(*) AS rows
FROM memory.metrics
GROUP BY category;

Load a Vortex file

If you have a local Vortex file, register it as a table:

.open events ./events.vortex

If the file is sorted by a unique key, declare it:

.open events ./events.vortex --key event_id

Then query it like any other table:

SELECT *
FROM memory.events
LIMIT 20;

Use .quit or .exit to leave the REPL.