Vector Indexes
Find the rows whose embeddings are nearest a query vector, with an index that never answers from stale data.
A Vector Index finds the rows whose embeddings are closest to a query vector, for example the 100 frames that look most like a near-miss that your robot recorded. It uses approximate candidates and ranks them against the exact stored vectors. Each index version records its source Table version. A search rejects a source version mismatch.
An example
The Vector Index frame-search covers the embedding column of frames,
with the cosine metric. A search gives the index a query vector, such as the
embedding of one near-miss frame, and the number of results it wants. It
returns the matching rows of frames, each with its exact distance from the
query and its rank. Ranks start at 1.
What a Vector Index holds
A Vector Index is its own Resource, next to the Table that it covers. Its definition names:
- the source Table and its vector column, which must be a fixed-size list of floating-point values;
- the distance metric:
cosine,euclidean, ordot; and - the index engine and its build options.
The engine is vortex.ivf-rabitq. Its build options trade recall against
cost:
| Build option | Default | Effect |
|---|---|---|
partitions | Set by the engine | The number of clusters that the build creates. |
probes | 8 | The number of nearest clusters that a search reads. |
rerank | 100 | The number of candidates that a search ranks against the exact stored vectors. |
Raise probes and rerank when recall matters more than search cost.
How Vector Indexes work explains
what each option does.
Versions and staleness
create definition only search fails: not built
refresh build covers frames v12 search reads v12
frames v13 new rows appended search fails: stale
refresh build covers frames v13 search reads v13A Vector Index starts with a definition-only version. A refresh reads one exact Table version, builds an immutable index version, and publishes it in a commit. When the commit that you read selects a different Table version from the one the index covers, a search fails as stale. A source version mismatch requires a refresh.
A search always names its index. Spiral never replaces an exact similarity computation in an ordinary query with an approximate index.
Where next
- Create a Vector Index in Studio.
- Refresh a Vector Index after the source Table changes. An Automation can refresh it after every change.
- Search a Vector Index and read visible gallery pages.
- How Vector Indexes work: partitions, compact codes, and the exact rerank.
Availability
Each refresh rebuilds the complete index. Incremental refresh is planned.
Where it runs
A refresh builds the index on a Worker that a Task schedules, and writes the index files to Project storage. The selected ScanDAL reads the index files and exact source vectors. It executes in the application or through hosted Connect. Spiral's control plane stores the definition and publishes versions. See Architecture.
The Vector Indexes HTTP reference documents the resource operations.
HTTP API
The HTTP reference documents the contract at
/api/vector-indexes. It uses camelCase fields, tagged union payloads, and decimal
strings for 64-bit counts and timestamps. Existing Rust and CLI clients keep
using the compatible resource endpoints.
Physical index metadata is a base64 string in this API. The codec interprets the decoded bytes.