flowchart TB
Q["ORDER BY distance LIMIT k"] --> S{"table size\n+ settings?"}
S -->|"small table, or\nann_enabled=off,\nor filtered,\nor repeatable-read"| EX["EXACT scan\n100% recall\ncost grows with rows"]
S -->|"large table\n+ usable index\n+ unfiltered"| ANN["ANN (HNSW/IVF)\ncandidate retrieval\n+ exact re-rank\n~recall, fast"]
EX --> R["top-k rows"]
ANN --> RDiagram source · mermaidcopy included
flowchart TB
Q["ORDER BY distance LIMIT k"] --> S{"table size\n+ settings?"}
S -->|"small table, or\nann_enabled=off,\nor filtered,\nor repeatable-read"| EX["EXACT scan\n100% recall\ncost grows with rows"]
S -->|"large table\n+ usable index\n+ unfiltered"| ANN["ANN (HNSW/IVF)\ncandidate retrieval\n+ exact re-rank\n~recall, fast"]
EX --> R["top-k rows"]
ANN --> RThe trade-off#
| Exact scan | Approximate (HNSW) | |
|---|---|---|
| Recall | 100% by construction | High but < 100%; tunable via ef_search / oversampling |
| Latency | Grows linearly with rows | Grows slowly (graph traversal + re-rank) |
| Memory | No index structure | Graph + vectors resident (bounded by vector.max_memory_bytes) |
| Build cost | None | Paid at index build; rebuilt from rows after restore |
| Correctness risk | None | None for returned ordering — candidates are re-ranked with exact distances |
Only publish recall/latency numbers you measured yourself on your data, model dimension, and hardware. This documentation makes no performance claims — see Performance.
Decision guide#
- Start exact. No index,
ORDER BY distance LIMIT k, measure latency at your target row count. - Fast enough? Stop. Indexes add build time, memory, and operational surface for no benefit on small tables.
- Too slow past ~tens of thousands of rows? Add
USING hnsw, re-measure latency and recall against an exact baseline (SET vector.ann_enabled = offgives you the baseline on demand). - Tune only with evidence. Raise
ef_searchuntil recall meets your bar; stop when latency exceeds budget. Record the setting alongside the measurement.
Exactness guarantees worth knowing#
- Unfiltered, unindexed queries are always exact.
- Filtered queries run exact even when an index exists.
- Repeatable-read snapshots run exact to preserve snapshot semantics.
- ANN candidates are always re-ranked with exact distances before
LIMITis applied — approximation affects which candidates are considered, never the arithmetic.
Was this page helpful? Thanks — noted locally, nothing is sent anywhere.