On this page
Supported methods#
CREATE INDEX docs_emb_hnsw ON docs USING hnsw (embedding);| Method | Best for | Status in v0.1.0 |
|---|---|---|
hnsw |
General approximate search | Supported — see HNSW |
flat |
Tiny datasets, exact baseline | Supported |
ivf_flat |
Large datasets, partitioned scan | Supported (declared; small scans may still run exact) |
ivf_sq |
Large datasets, lower memory | Supported with limits (INT4 goes through float promotion) |
ivf_pq |
Large datasets, smallest memory | Supported with limits (float-native; INT4/binary rejected) |
diskann |
Larger-than-memory datasets | Supported (declared; verify recall on your data) |
sparse_inverted |
Sparse vectors | Experimental (sparse SQL surface is experimental) |
binary |
Binary vectors | Limited (declared; queries fall back to exact computation) |
An index declaration that is accepted but not yet accelerating a given path still returns correct results — the engine falls back to exact computation rather than wrong answers. EXPLAIN tells you which path a query actually took.
Rules#
- A vector index requires an explicit
USING <method>clause naming the method above. OmittingUSINGon a vector column is rejected. - One indexed column per index; composite (multi-column) vector indexes are rejected.
UNIQUEvector indexes are rejected.- Create vector indexes in autocommit, not inside
BEGIN ... COMMIT— index creation inside an explicit transaction is refused (see Troubleshooting). - A vector column gets an automatic HNSW structure at
CREATE TABLEtime; an explicitCREATE INDEXgives you control over method and parameters.
Session settings#
SHOW vector.ann_enabled; -- on | off (master switch)
SET vector.ann_enabled = off; -- force exact scansSupporting knobs (all under the vector. prefix):
| Setting | Controls |
|---|---|
vector.ann_enabled |
Master switch for index-backed search |
vector.ef_search |
HNSW candidate list size (higher = better recall, slower) |
vector.candidate_oversample |
Oversampling factor before re-rank |
vector.max_ann_rows |
Row ceiling for ANN eligibility |
vector.auto_ann_min_rows |
Table size (default 4096 rows) above which automatic index use is considered |
vector.max_memory_bytes |
Memory budget for ANN structures |
vector.max_index_vectors |
Index size cap |
vector.cache_graphs |
Whether to keep index graphs cached |
vector.compute |
auto (default) | cpu | gpu — compute backend request; gpu has no working backend in v0.1.0 and degrades to CPU, auto selects CPU |
Unknown vector.* names fail closed with an error rather than being silently ignored — a typo will not masquerade as a tuned setting.
How to tell what ran#
EXPLAIN SELECT id FROM docs ORDER BY embedding <-> [1.0, 0.0, 0.0] LIMIT 2;Read the Vector: lines: scan strategy, metric, limit, options, and estimated cost exact=… ann=…. If it says Vector Exact scan, your query ran exactly (correct, unaccelerated). If it names an index path, ANN served it. Small tables deliberately report Index: usable with an exact scan — the optimizer measured that scanning is cheaper. See Exact vs approximate.