Vector indexes

Supported index methods, creation syntax, session settings, and which paths actually accelerate queries.

Version
Latest
v0.1.0 · latest 3 min read
On this page
  1. Supported methods
  2. Rules
  3. Session settings
  4. How to tell what ran

Supported methods#

sqlsource
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. Omitting USING on a vector column is rejected.
  • One indexed column per index; composite (multi-column) vector indexes are rejected.
  • UNIQUE vector 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 TABLE time; an explicit CREATE INDEX gives you control over method and parameters.

Session settings#

sqlsource
SHOW vector.ann_enabled;        -- on | off (master switch)
SET vector.ann_enabled = off;   -- force exact scans

Supporting 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#

sqlsource
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.

Was this page helpful?