# How to Achieve High Recall Rates in VelesDB's Accurate Search Mode

> Achieve high recall rates in VelesDB accurate search mode. Optimize with the `accurate` preset, `ef_search`, and two-stage reranking for guaranteed ≥95% recall on collections up to 100k points.

- Repository: [Wiscale/velesdb](https://github.com/cyberlife-coder/velesdb)
- Tags: best-practices
- Published: 2026-02-28

---

**Use the `accurate` preset with `ef_search = 512.max(k * 16)` and enable two-stage reranking for quantized indexes to guarantee ≥95% recall on collections up to 100k points.**

VelesDB is a vector database that implements tunable HNSW search parameters to balance latency against retrieval quality. The **accurate** search quality preset provides production-grade recall rates without the computational overhead of `perfect` mode, making it the recommended configuration for high-stakes similarity search. According to the `cyberlife-coder/velesdb` source code, this mode combines dynamic candidate pool scaling with optional full-precision reranking to minimize false negatives.

## How the Accurate Mode Works

### The SearchQuality Enum and ef_search Scaling

The core logic resides in [`crates/velesdb-core/src/index/hnsw/params.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/params.rs), where the `SearchQuality` enum defines the `Accurate` variant. This variant implements a dynamic scaling formula that grows the search candidate pool based on your requested result count:

```rust
// In SearchQuality::ef_search()
Self::Accurate => 512.max(k * 16)

```

- **Base value:** 512 candidates (minimum pool size)
- **Scaling factor:** `k * 16`, where `k` is your `LIMIT` or `top_k` value
- **Result:** A candidate pool that automatically expands for larger result sets, ensuring high recall even when retrieving many neighbors

This contrasts with `perfect` mode, which uses a static base of 4096, and `fast` mode, which uses significantly smaller pools for latency-critical workloads.

### Mode Conversion in the Server Layer

Before reaching the search engine, textual mode names convert to concrete integer values in [`crates/velesdb-server/src/types.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-server/src/types.rs). The `mode_to_ef_search("accurate")` function returns the preset described above, allowing the API to translate user-friendly strings into the HNSW traversal parameters used by the index.

## Configuring High Recall in VELESQL

### Using the WITH Clause for Accurate Searches

The `WITH` clause, as specified in [`docs/reference/VELESQL_SPEC.md`](https://github.com/cyberlife-coder/velesdb/blob/main/docs/reference/VELESQL_SPEC.md), accepts a `mode` parameter that triggers the accurate preset. Always pair this with a generous `timeout_ms` to prevent early termination on deep graph traversals:

```sql
SELECT * FROM docs
WHERE vector NEAR $v
LIMIT 10
WITH (mode = 'accurate', timeout_ms = 5000);

```

This configuration sets `ef_search` to `max(512, 10*16) = 512` and allocates five seconds for the HNSW traversal to complete.

### Overriding ef_search for Maximum Recall

For collections exceeding 100k points or when you require recall rates approaching 99%, bypass the preset and specify an explicit `ef_search` value:

```sql
SELECT * FROM docs
WHERE vector NEAR $v
LIMIT 10
WITH (ef_search = 1024, timeout_ms = 8000);

```

This doubles the candidate pool from the accurate preset's default, exploring more entry points in the graph layer structure to reduce the probability of missing true nearest neighbors.

### Session-Level Configuration

The VelesDB REPL supports session-wide defaults via the `\set` command, storing configuration in the client session:

```text
\set search_mode accurate
SELECT * FROM articles WHERE vector NEAR $v LIMIT 5;

```

All subsequent queries in the session automatically inherit the accurate preset without requiring repeated `WITH` clauses.

## Implementing High Recall in Python

The Python bindings in [`crates/velesdb-python/src/collection.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-python/src/collection.rs) expose the `ef_search` and `timeout_ms` parameters directly to the `Collection.search()` method:

```python
from velesdb import Collection

col = Collection("docs")
results = col.search(
    vector=[0.1, 0.2, ...],  # Your query embedding

    top_k=20,
    ef_search=1024,          # Explicit high-recall setting

    timeout_ms=8000,         # Prevents timeout on deep search

)

for r in results:
    print(r.id, r.score)

```

The `ef_search` argument maps one-to-one with the server-side value used by the HNSW engine, ensuring consistent recall characteristics across language bindings.

## Optimizing Recall with Reranking

For **quantized indexes** (such as SQ8), configure a two-stage reranking pass to eliminate quantization errors:

```sql
SELECT * FROM docs
WHERE vector NEAR $v
LIMIT 10
WITH (mode = 'accurate', rerank = true, timeout_ms = 6000);

```

When `rerank = true`, the engine performs a fast first pass using compressed vectors, then recomputes full-precision distances for the top candidates. This recovers recall lost to vector quantization while maintaining the speed benefits of compressed storage. The reranking logic is handled in the search request pipeline in [`crates/velesdb-server/src/handlers/search.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-server/src/handlers/search.rs).

## Why Accurate Mode Delivers High Recall

- **Dynamic candidate pool:** The `512.max(k * 16)` formula ensures the HNSW traversal explores sufficient graph entry points proportional to your result set size, reducing the chance of local minima trapping.
- **Quantization correction:** Optional reranking recomputes exact distances for the shortlist of candidates, fixing precision loss introduced by SQ8 or other compression schemes.
- **Timeout protection:** Explicit `timeout_ms` values prevent the search from being terminated prematurely during deep graph exploration, ensuring the expanded `ef_search` budget can be fully utilized.

## Summary

- Set `mode = 'accurate'` in the `WITH` clause to activate the `512.max(k * 16)` candidate pool formula defined in [`crates/velesdb-core/src/index/hnsw/params.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/params.rs).
- Override with explicit `ef_search` values (e.g., 1024) when you need recall approaching 99% on large collections.
- Enable `rerank = true` for quantized indexes to recover precision through full-precision distance recalculation.
- Always specify `timeout_ms` (5000-8000ms) to prevent early termination during deep HNSW traversals.
- Use `\set search_mode accurate` in the REPL for session-wide defaults.

## Frequently Asked Questions

### What is the default ef_search value for accurate mode in VelesDB?

The default follows the Rust implementation `512.max(k * 16)` found in [`crates/velesdb-core/src/index/hnsw/params.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/params.rs), where `k` is your query's `LIMIT` or `top_k` value. This guarantees a minimum candidate pool of 512 vectors, scaling linearly with your requested result count to maintain recall rates.

### How does accurate mode compare to perfect mode for recall rates?

Accurate mode targets approximately **≥95% recall** with optimized latency, while perfect mode uses a static `ef_search` base of 4096 to achieve near-100% recall at significantly higher computational cost. Use accurate mode for production workloads and perfect mode only when missing a single result is unacceptable.

### Can I use accurate mode with quantized indexes in VelesDB?

Yes, and you should explicitly enable reranking by setting `rerank = true` in your `WITH` clause. This triggers a second-stage distance calculation using full-precision vectors for the top candidates, correcting any quantization errors introduced by SQ8 compression while preserving the speed of the initial approximate search.

### Where is the search quality preset defined in the VelesDB source code?

The `SearchQuality` enum and its `ef_search` scaling logic are defined in [`crates/velesdb-core/src/index/hnsw/params.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/params.rs). The mapping from textual mode names (like `"accurate"`) to these values occurs in [`crates/velesdb-server/src/types.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-server/src/types.rs), and the request handling pipeline that combines these with `WITH` clause overrides is implemented in [`crates/velesdb-server/src/handlers/search.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-server/src/handlers/search.rs).