Repository navigation
Conversation
`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>
2 of 7 tasks
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>
Closed
Member
|
@cpegeric, thanks for this! Exact filtered search is built in now: a scan traversal plus a predicate, which Go exposes as |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
usearch_filtered_searchgets anexactflag. When it'strue, 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 callssearch_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:
connectivity=16,expansion_add=200,expansion_search=100;Results (recall against brute force):
exact = trueThe caller usually knows how selective its filter is, for example the cardinality of a bitmap of allowed keys. So it can choose
exactwhen few vectors pass and the graph walk otherwise.API changes
usearch_filtered_search(..., filter, filter_state, bool exact, keys, distances, error). This is a breaking change to the C signature. Passfalsefor today's behaviour.FilteredSearch,FilteredSearchUnsafe,FilteredSearchI8andFilteredSearchU8takeexact boolafter the handler.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
test_filtered_search_exactcompares results with a brute-force scan of the accepted vectors, usingusearch_distance. It checks the distances, their ascending order, and that every key passes the filter.TestFilteredSearchExactdoes the same on a deliberately sparse graph (Connectivity = 2). Withexact = falseit fails, so it does exercise the exact path. It also checks thatFilteredSearchUnsafereturns the same keys.test_c,test_cppandgo test ./...pass.🤖 Generated with Claude Code