Skip to content

Add: Exact filtered search in C and Go - #828

Closed
cpegeric wants to merge 1 commit into
unum-cloud:main-devfrom
cpegeric:filtered-search-exact
Closed

cpegeric wants to merge 1 commit into
unum-cloud:main-devfrom
cpegeric:filtered-search-exact

Conversation

@cpegeric

Copy link
Copy Markdown
Contributor

What

usearch_filtered_search gets an exact flag. When it's true, the search skips the graph: it applies the filter to every indexed vector and measures distances only to the accepted ones. The results are exact.

This uses the existing C++ path (index_dense_gt::filtered_search(..., exact), which calls search_exact_). The C API just didn't expose it.

Why

A graph walk with a selective filter still measures distances to the rejected vectors it passes through. So the fewer vectors a filter accepts, the more work each result costs. The exact scan's cost depends only on how many vectors the filter accepts.

Benchmark setup:

  • data: 1M wiki_all vectors, 768 dimensions, L2;
  • index: HNSW, connectivity=16, expansion_add=200, expansion_search=100;
  • queries: k=100, 200 queries, single thread;
  • filter: a key range covering the given fraction of the index.

Results (recall against brute force):

Accepted Graph walk exact = true
1% 91.1% @ 10 QPS (204K distances) 100% @ 138 QPS (10K distances)
3% 82.0% @ 21 QPS 100% @ 126 QPS
5% 90.7% @ 53 QPS 100% @ 106 QPS
10% 91.5% @ 79 QPS 100% @ 74 QPS
25% 91.8% @ 169 QPS 100% @ 41 QPS

The caller usually knows how selective its filter is, for example the cardinality of a bitmap of allowed keys. So it can choose exact when few vectors pass and the graph walk otherwise.

API changes

  • C: usearch_filtered_search(..., filter, filter_state, bool exact, keys, distances, error). This is a breaking change to the C signature. Pass false for today's behaviour.
  • Go: FilteredSearch, FilteredSearchUnsafe, FilteredSearchI8 and FilteredSearchU8 take exact bool after the handler.
  • Swift: the public API is unchanged. The internal call passes false, so Swift keeps searching the graph. I couldn't build the Swift package locally, because it needs Swift 6.0 and I have 5.10.

Tests

  • C: test_filtered_search_exact compares results with a brute-force scan of the accepted vectors, using usearch_distance. It checks the distances, their ascending order, and that every key passes the filter.
  • Go: TestFilteredSearchExact does the same on a deliberately sparse graph (Connectivity = 2). With exact = false it fails, so it does exercise the exact path. It also checks that FilteredSearchUnsafe returns the same keys.
  • Results: test_c, test_cpp and go test ./... pass.

🤖 Generated with Claude Code

`usearch_filtered_search` takes an `exact` flag. When set, the search skips the
graph, applies the filter to every indexed vector, and measures the distance only
to the accepted ones. The results are exact, and the search is faster than the
graph walk when the filter accepts a small fraction of the index, because the walk
measures distances to rejected vectors while it traverses them.

The Go `FilteredSearch`, `FilteredSearchUnsafe`, `FilteredSearchI8` and
`FilteredSearchU8` take the same flag. Swift keeps its API and searches the graph.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
XuPeng-SH added a commit to matrixorigin/matrixone that referenced this pull request Oct 28, 2026
…ory-sized models (#31468)

## What type of PR is this?

- [ ] API-change
- [ ] BUG
- [x] Improvement
- [ ] Documentation
- [x] Feature
- [ ] Test and CI
- [ ] Code Refactoring

## Which issue(s) this PR fixes:

issue #31467

## What this PR does / why we need it:

Design: `docs/design/20261026-hnsw-quantization.md` (status: proposed —
design review requested).

**Behavior**
- `QUANTIZATION` on HNSW: float32 / float16 / bf16 / float64 / int8 /
uint8 (int8/uint8 L2 only, one trained range per index; no widening;
fixed at CREATE, REINDEX keeps it).
- vecf16 / vecbf16 / vecint8 / vecuint8 columns are indexed, synced and
searched in their own element type; a vector already in the stored type
goes to usearch as is.
- The int8/uint8 range is kept in a key/value hidden table `hnsw_dict`
(only int8/uint8 indexes have it; existing indexes need no upgrade).
- `max_index_capacity` default 0: each model holds what fits 75% of
available host memory (dimension, stored width, M), as IVF-PQ; build and
sync use the index option, then the session variable, then the estimate.
Models reserve only the rows they receive.
- `hnsw_create(params, cfg)` counts, samples and streams the source
itself (no CROSS APPLY).
- Exact prefiltered search when the qualifying row count ≤
`hnsw_prefilter_exact_threshold` (default 5000, from a measured
exact-vs-walk crossover).

**Validation**
- Unit tests for every changed package (catalog, frontend, iscp,
table_function, sql/plan, vectorindex/..., bootstrap); BVT
`vector_hnsw_quantization` 179/179 and all existing HNSW BVT files pass.
- wiki_all 1M (768-d, M=100, ef_construction=400, ef_search=200, k=20,
200 queries x 8 concurrency, arm64 Mac); every build is a single model:

| | f32 | float16 | bf16 | int8 |
|---|---|---|---|---|
| build | 337.5 s | 869.5 s | 239.6 s | 148.3 s |
| recall@20 | 0.9965 | 0.9935 | 0.9922 | 0.9637 |
| warm QPS | 1201 | 830 | 1318 | 1292 |
| warm p50 | 5.89 ms | 8.55 ms | 5.11 ms | 5.52 ms |

**Limits**
- Uses the usearch fork (`cpegeric/usearch`, filtered search `exact`
flag) until unum-cloud/USearch#828 merges.
- A single large model is rewritten whole by each ISCP sync; CDC tail +
idxcron merge is the follow-up PR.
- float16 is slow on this arm64 build (usearch without SimSIMD);
bf16/int8 are not affected.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
Co-authored-by: XuPeng-SH <xupeng3112@163.com>
@ashvardanian ashvardanian mentioned this pull request Nov 13, 2026
@ashvardanian

ashvardanian commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

@cpegeric, thanks for this! Exact filtered search is built in now: a scan traversal plus a predicate, which Go exposes as DenseSearchConfig{Traversal: TraversalScan, Predicate: ...}. Both work on RAM and NVMe; GPU indexes refuse predicates, AMD and Apple GPUs refuse scans, and NVMe views are read-only, so inserts happen in RAM or on the GPU. Closing in favor of that, and I'd love your feedback on the Go API in the release candidate on main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants