Add algorithm and benchmark for filtered range search by magdalendobson · Pull Request #1228 · microsoft/DiskANN

Magdalen Dobson Manohar (magdalendobson) · 2026-07-06T15:37:56Z

This PR adds an algorithm for filtered range search to the DiskANN repository. Details of the algorithm, along with the experiments supporting it, are at this Wiki page.

This PR:

Adds the new algorithm to diskann, along with integration tests.
Adds the new algorithm as an option in diskann-benchmark, along with an integration test.
Adds filtered range groundtruth files in test_data.

Some enhancements/fixes to range search along the way:

Added range groundtruth in test_data for yfcc.
Fixed a bug where range search was not always honoring the maximum number of returned results.
Added integration tests for range search making sure a set maximum number of results is actually respected.

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

Codecov Comments Bot (codecov-commenter) · 2026-07-10T18:38:43Z

Codecov Report

❌ Patch coverage is 97.82383% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.71%. Comparing base (2ee97ff) to head (557d74a).

Files with missing lines	Patch %	Lines
...-benchmark-core/src/search/graph/filtered_range.rs	96.29%	7 Missing ⚠️
diskann-benchmark/src/index/benchmarks.rs	86.36%	6 Missing ⚠️
diskann-benchmark/src/index/search/plugins.rs	50.00%	3 Missing ⚠️
...kann/src/graph/test/cases/filtered_range_search.rs	98.90%	3 Missing ⚠️
diskann-benchmark/src/index/search/range.rs	94.11%	1 Missing ⚠️
diskann-benchmark/src/inputs/graph_index.rs	96.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1228      +/-   ##
==========================================
+ Coverage   91.46%   91.71%   +0.24%     
==========================================
  Files         516      519       +3     
  Lines       98276    99209     +933     
==========================================
+ Hits        89891    90989    +1098     
+ Misses       8385     8220     -165

Flag	Coverage Δ
miri	`91.71% <97.82%> (+0.24%)`	⬆️
unittests	`91.39% <97.82%> (+0.24%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
diskann-benchmark-core/src/search/graph/mod.rs	`100.00% <ø> (ø)`
diskann-benchmark-core/src/search/graph/range.rs	`95.33% <100.00%> (+0.40%)`	⬆️
diskann-benchmark/src/index/inmem/spherical.rs	`83.33% <ø> (ø)`
diskann-benchmark/src/index/result.rs	`88.05% <100.00%> (+39.04%)`	⬆️
diskann-benchmark/src/main.rs	`92.21% <100.00%> (+0.15%)`	⬆️
diskann-providers/src/index/diskann_async.rs	`96.74% <ø> (ø)`
diskann/src/graph/search/filtered_range_search.rs	`100.00% <100.00%> (ø)`
diskann/src/graph/search/inline_filter_search.rs	`99.47% <100.00%> (ø)`
diskann/src/graph/search/range_search.rs	`99.72% <100.00%> (+0.82%)`	⬆️
diskann/src/graph/test/cases/range_search.rs	`98.05% <100.00%> (+0.37%)`	⬆️
... and 6 more

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Mark Hildebrand (hildebrandmw)

Thanks Magdalen. I've left a number of comments throughout the PR, but they all fall into a few general themes.

This PR duplicates a lot of logic when that duplication should be abstracted instead. The worst offender is probably DistanceFiltered.
We need to move away from messing around with the internal of scratch space (in_range, range_frontier, visited etc) - that can quickly become very brittle.
The logic in the filtered search implementation can be tightened.
We should start tagging baselines with more verbose descriptions of what the test is covering and what the corner cases being exercised are.
Please keep to high level trait objects in diskann-benchmark instead of generics. The former is significantly better for compile times.

In addition, is the intention of this algorithm for research, or is there a production ask for it? I ask because maintaining such algorithms/code is not free. If this is meant for research, please put it behind an experimental feature flag to avoid committing us to it long term.

Mark Hildebrand (hildebrandmw) · 2026-07-10T15:42:37Z

+                    merged
+                        .entry(neighbor.id)
+                        .and_modify(|best: &mut Neighbor<_>| {
+                            if neighbor.distance < best.distance {


What's happening here? Why are we expecting repeats for IDs and why is picking the best the right choice?

Overwriting the distance was an error and I've gotten rid of it now. We are expecting repeats because we are merging the best elements found so far with all the filter-satisfying elements found so far, which might have overlap.

Mark Hildebrand (hildebrandmw) · 2026-07-10T15:44:14Z

+            in_range.sort_unstable_by(|left, right| {
+                left.distance
+                    .total_cmp(&right.distance)
+                    .then_with(|| left.id.cmp(&right.id))


Don't Neighbors already sort themselves?

No, because scratch.best is merged with the predicate-satisfying points, which are not in sorted order.

Mark Hildebrand (hildebrandmw) · 2026-07-10T19:16:27Z

+    }
+
+    /// Create range search with full options.
+    #[allow(clippy::too_many_arguments)]


We should probably listen to clippy here. This is a lot of arguments, and while it mirrors Range - I don't think that's sufficient justification. There are several problems:

There's no real documentation about how these are expected to affect the algorithm.

Callers of FilteredRange::with_options just have a sea of values, which can be difficult to remember.

Any changes to the parameters requires a breaking change for all callers.

It would be way better to use a builder interface for these. As a side-benefit, the same builder could be used for both Range and FilteredRange.

Thanks, I set up a builder

Mark Hildebrand (hildebrandmw) · 2026-07-10T19:48:27Z

 ///
 /// Both variants carry the item `T` since rejected items are useful for graph navigation.
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]


Why are PartialEq and Eq needed? The code compiles fine without them.

I think this was leftover from an intermediate state. Removed now.

Mark Hildebrand (hildebrandmw) · 2026-07-10T19:50:10Z

+    let (filtered_stats, filtered_results) =
+        run_filtered_range_search(&index, query.as_slice(), filtered_range, &filter);
+
+    let baseline = RangeSearchBaseline {


There's probably a better way to construct these baselines. A constructor taking the stats object and the Range could automatically fill in a lot of the fields (and we could capture all the fields of `Range~ rather then just like 3).

Thanks for the suggestion, I added a constructor

Mark Hildebrand (hildebrandmw) · 2026-07-10T19:53:40Z

-pub(crate) fn run<I>(
-    runner: &dyn Range<I>,
+pub(crate) fn run<I, R, F>(
+    runner: &R,


Why did this change from a &dyn Range to a true generic? The former is quite important to keep compile times down.

Presumably it's because there's a different in the parameters being passed. Please find an alternate solution that isn't as regressive on compile times.

I found an alternative way to do this, so the generic isn't used anymore

…en/range_filter

While working on #1228, I noticed that there were some issues with our current implementation of range search and its testing. The main issue with testing is that there were no tests ensuring the `max_results` parameter was respected. I have added two tests that ensure this now. The main code had several issues with how `max_results` was handled: 1. The `max_results` parameter was allowed to be less than the initial L_search. This is a conceptual issue because the user expects `max_results` to stop the search from continuing for too long, and the compute used in the initial search will always be controlled by `initial_search_l`. 2. A `max_results` check was not enforced before deciding to continue to the second round search. This meant that if the max results was reached via the initial search, it might not be respected. 3. The second round search was not terminated when `max_results` was reached, meaning it would continue to perform unnecessary work. This PR fixes these issues by adding additional checks of `max_results` at the correct points in the code. --------- Co-authored-by: Magdalen Manohar <[email protected]>

While working on microsoft#1228, I noticed that there were some issues with our current implementation of range search and its testing. The main issue with testing is that there were no tests ensuring the `max_results` parameter was respected. I have added two tests that ensure this now. The main code had several issues with how `max_results` was handled: 1. The `max_results` parameter was allowed to be less than the initial L_search. This is a conceptual issue because the user expects `max_results` to stop the search from continuing for too long, and the compute used in the initial search will always be controlled by `initial_search_l`. 2. A `max_results` check was not enforced before deciding to continue to the second round search. This meant that if the max results was reached via the initial search, it might not be respected. 3. The second round search was not terminated when `max_results` was reached, meaning it would continue to perform unnecessary work. This PR fixes these issues by adding additional checks of `max_results` at the correct points in the code. --------- Co-authored-by: Magdalen Manohar <[email protected]>

Mark Hildebrand (hildebrandmw)

Thanks Magdalen, appreciate the work on this iteration!

Mark Hildebrand (hildebrandmw) · 2026-07-24T17:04:25Z

+    {
+        let context = DP::Context::default();
+        let filtered_range_search =
+            graph::search::FilteredRange::builder(parameters.starting_l(), parameters.radius())


I see what's happening here: we want to keep the parameters the same to manage monomorphization in diskann-benchmark. But, it might be better to define a conversion from Range to FilteredRange rather than going back through the builder (which runs the risk of going stale). I'm not sure what the implications are, though, if we ever decide that FilteredRange needs to have additional parameters, but I guess we'll cross that bridge when we come to it.

Defined a conversion

…en/range_filter

Magdalen Manohar and others added 30 commits May 14, 2026 17:56

finish up recall computation patch

97b36ef

Merge branch 'main' of github.com:microsoft/DiskANN

07b3671

Merge branch 'main' of github.com:microsoft/DiskANN

eac3ffb

fix conflict

17780f8

fix conflict

43eb517

Merge branch 'main' of github.com:microsoft/DiskANN

1d3a52b

Merge branch 'main' of github.com:microsoft/DiskANN

17eac62

Merge branch 'main' of github.com:microsoft/DiskANN

0ab4baa

Merge branch 'main' of github.com:microsoft/DiskANN

4ddca60

fix conflict

54ee01b

Merge branch 'main' of github.com:microsoft/DiskANN

9e1743f

Merge branch 'main' of github.com:microsoft/DiskANN

93504e6

Merge branch 'main' of github.com:microsoft/DiskANN

b7c27ce

Merge branch 'main' of github.com:microsoft/DiskANN

1dafc55

Merge branch 'main' of github.com:microsoft/DiskANN

33285e2

Merge branch 'main' of github.com:microsoft/DiskANN

824bdb3

Merge branch 'main' of github.com:microsoft/DiskANN

826600f

Merge branch 'main' of github.com:microsoft/DiskANN

1bea9c5

add range groundtruth calculator, rename vector_filters_file

c864722

fmt, clippy, add missing file

bd05e0f

Potential fix for pull request finding

1477ac4

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

Potential fix for pull request finding

4f6f80a

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

fix: return error for filter bitmap mismatch

2044ba1

standardize naming to kebab case

df844be

standardize variable names, one more kebab-case instance

6827f9d

merge with main

eb70a6f

add range filter algorithm

5edc8e9

cargo fmt

db3f379

add range searhc

37796db

add benchmark search file

39a319f

regenerate baselines after bug fix

1e51766

Mark Hildebrand (hildebrandmw) requested changes Jul 10, 2026

View reviewed changes

Merge branch 'main' of github.com:microsoft/DiskANN into users/magdal…

c2ad6f9

…en/range_filter

Magdalen Dobson Manohar (magdalendobson) mentioned this pull request Jul 13, 2026

Clean up range search #1253

Merged

Magdalen Manohar added 4 commits July 13, 2026 16:42

remove range search parts to split out to separate PR

1895710

added a description field for each test

cb78955

overwrite benchmarks to include descriptions

c79529f

fmt + clippy

e5bf7ba

Magdalen Manohar added 10 commits July 14, 2026 18:31

address comments about filtered range search

eefcd3e

use vector sort + dedup instead of hashset

918a6c0

get rid of unnecessary PartialEq and Eq

bbf3a35

add tests

4585f84

add a builder for range search params

b0a6677

get rid of duplicate builder

9571fd0

change old description

251a0ba

remove duplicated code

1440049

tighten up benchmark

85bf3af

remove edits done by clippy

e30697f

Magdalen Dobson Manohar (magdalendobson) force-pushed the users/magdalen/range_filter branch from fff67b6 to e30697f Compare July 15, 2026 14:21

Magdalen Manohar added 2 commits July 16, 2026 16:06

fix merge conflict

e4bbced

fmt

34fb7a0

Mark Hildebrand (hildebrandmw) reviewed Jul 24, 2026

View reviewed changes

Magdalen Manohar added 2 commits August 5, 2026 14:11

Merge branch 'main' of github.com:microsoft/DiskANN into users/magdal…

b7bd288

…en/range_filter

respond to review comments

557d74a

Magdalen Dobson Manohar (magdalendobson) commented Aug 5, 2026

View reviewed changes

Comment thread diskann/src/graph/search/filtered_range_search.rs Outdated

Magdalen Manohar added 2 commits August 5, 2026 20:33

Merge branch 'main' of github.com:microsoft/DiskANN into users/magdal…

fd54c57

…en/range_filter

respond to review comments within diskann

bd8fb7b

Uh oh!

Conversation

Magdalen Dobson Manohar (magdalendobson) commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Codecov Comments Bot (codecov-commenter) commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Mark Hildebrand (hildebrandmw) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mark Hildebrand (hildebrandmw) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Magdalen Dobson Manohar (magdalendobson) commented Jul 6, 2026 •

edited

Loading

Codecov Comments Bot (codecov-commenter) commented Jul 10, 2026 •

edited

Loading