Spiral’s user-facing batch workflow is still being built. This page defines the workflow vocabulary used across the docs so preview extension pages do not invent incompatible shapes.

Workflow

1. Use SQL to define the relation.
2. Use Extension table functions to produce deferred modality values.
3. Filter, join, sample, and order metadata before materializing bytes.
4. Choose a destination such as preview, artifact, Arrow, Vortex, or framework batch stream.

The current client exposes the first part of that path: SQL over Vortex files, in-memory tables, and table functions.

Example shape

The exact extension syntax is not public yet, but the intended shape is:

SELECT image_id, image_ref, label
FROM images.scan('./train/')
WHERE split = 'train'
ORDER BY image_id
LIMIT 128;

The query produces a relation. A later materialization or batch destination decides whether image_ref becomes decoded pixels, thumbnails, tensors, or an artifact.

Destination-aware planning

Destination matters:

• A terminal preview should avoid materializing more rows than displayed.
• A feature extraction artifact may prefer deterministic ordering and large sequential reads.
• A training batch stream may need bounded memory, prefetch, device placement, and repeatable sampling.

Spiral’s docs should make the destination explicit whenever a workflow moves past ordinary relation output.