Inline filtered search with adaptive L by magdalendobson · Pull Request #1131 · microsoft/DiskANN

magdalendobson · 2026-06-03T20:05:20Z

This PR implements the recommendation in the filtered search RFC to implement inline filtering with the adaptive L method as an optional addition.

…en/two-queue-adaptive-l

hildebrandmw

Thanks Magdalen! In addition to my inline comments - can you also add some integration tests exercising the functionality here? These go a surprisingly long way towards protecting the algorithm.

Also, can we bikeshed InlineSearch a little? Maybe FilteredSearch? Or InlineFilteredSearch? Not a huge deal, but InlineSearch seems a little opaque to me.

…w error

codecov-commenter · 2026-06-04T21:41:47Z

Codecov Report

❌ Patch coverage is 95.51913% with 41 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.50%. Comparing base (d44b9a8) to head (f47525c).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
diskann/src/graph/test/cases/inline.rs	96.74%	14 Missing ⚠️
diskann/src/graph/search/inline_filter_search.rs	94.33%	12 Missing ⚠️
diskann-benchmark/src/inputs/graph_index.rs	80.55%	7 Missing ⚠️
diskann-benchmark/src/backend/index/benchmarks.rs	85.71%	5 Missing ⚠️
diskann-benchmark-core/src/search/graph/inline.rs	98.79%	2 Missing ⚠️
diskann-benchmark/src/backend/index/search/knn.rs	94.44%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1131      +/-   ##
==========================================
+ Coverage   89.45%   89.50%   +0.04%     
==========================================
  Files         484      487       +3     
  Lines       91407    92398     +991     
==========================================
+ Hits        81765    82697     +932     
- Misses       9642     9701      +59

Flag	Coverage Δ
miri	`89.50% <95.51%> (+0.04%)`	⬆️
unittests	`89.15% <95.51%> (+0.05%)`	⬆️

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% <ø> (ø)`
...kann-benchmark/src/backend/index/search/plugins.rs	`73.58% <100.00%> (+7.58%)`	⬆️
diskann-benchmark/src/backend/index/spherical.rs	`100.00% <ø> (ø)`
diskann-benchmark/src/main.rs	`91.26% <100.00%> (+0.09%)`	⬆️
diskann/src/graph/search/multihop_search.rs	`100.00% <100.00%> (+0.58%)`	⬆️
diskann/src/graph/test/cases/multihop.rs	`95.79% <100.00%> (ø)`
diskann-benchmark/src/backend/index/search/knn.rs	`77.77% <94.44%> (+4.16%)`	⬆️
diskann-benchmark-core/src/search/graph/inline.rs	`98.79% <98.79%> (ø)`
diskann-benchmark/src/backend/index/benchmarks.rs	`71.22% <85.71%> (+2.43%)`	⬆️
diskann-benchmark/src/inputs/graph_index.rs	`51.43% <80.55%> (+3.44%)`	⬆️
... and 2 more

... and 13 files with indirect coverage changes

🚀 New features to boost your workflow:

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

magdalendobson · 2026-06-04T22:18:53Z

Thanks Magdalen! In addition to my inline comments - can you also add some integration tests exercising the functionality here? These go a surprisingly long way towards protecting the algorithm.

Also, can we bikeshed InlineSearch a little? Maybe FilteredSearch? Or InlineFilteredSearch? Not a huge deal, but InlineSearch seems a little opaque to me.

I've added some integration test. In addition to throwing some of the existing cases in multihop at it, I also designed a test that should return different results depending on whether or not the adaptive L feature is enabled.

Regarding the naming, I named it InlineSearch to be consistent with MultihopSearch (ie, multihop search isn't called MultihopFilteredSearch either). Should we maybe rename both to mention filtering?

harsha-simhadri · 2026-06-05T00:30:47Z

+///     specificity = 0.1% (1/1000)   → 8× L
+///   and so on up to a pre-set maximum multipler
+#[derive(Debug)]
+pub struct InlineSearch<'q, InternalId> {


not a blocker for this PR, but how does this compose with range search and diverse search functionalities?

From an algorithmic perspective, inline filtering (without any adaptation) will compose seamlessly with any other type of search, because it's just adding the extra step of checking match and keeping track of matched elements. However, from the perspective of our codebase as written right now, it would require new function signatures that accept a LabelProvider.

Thinking about how adaptive L in particular would compose with range search, we could use it within the initial graph search before deciding whether to move on to the unbounded part of range search. Similarly we could compose it with diverse search to increase L_search when few matching candidates are found.

ok, could you please document these to-dos as issues

Done: #1139

harsha-simhadri · 2026-06-05T00:33:36Z

+    I: VectorId,
+    A: ExpandBeam<T, Id = I> + SearchExt,
+    SR: SearchRecord<I> + ?Sized,
+{


would we want to allow a paginated API For this function?

Hmm, that's a good question. Using pagination and adaptive L seems like a strange thing to do. Adapting L_search is morally pretty similar to pagination, since it extends the search for longer when few matched results are found. If there was a user who wanted to use pure inline filtering and control length of the search via pagination only, on the other hand that seems reasonable.

The user might be in a position where the first search did not yield enough results that pass filters? In such a case, is our advise to retry with larger L?

This would be the advice if the user is sure that the number of results they are requesting actually exist.

Copilot

Pull request overview

This PR adds a new “inline filtered search” path (with optional adaptive L scaling) to the diskann graph search API and wires it through the benchmark harness and test suite.

Changes:

Introduces InlineSearch + AdaptiveL in diskann/src/graph/search/inline_filter_search.rs and re-exports them from diskann::graph::search.
Adds end-to-end and algorithm-focused tests for inline filtered traversal behavior.
Extends diskann-benchmark / diskann-benchmark-core to support a new topk-inline-filter search phase, including an example JSON and integration test.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
diskann/src/graph/test/cases/multihop.rs	Exposes test helpers/filters (`pub(super)`) for reuse by the new inline test suite.
diskann/src/graph/test/cases/mod.rs	Registers the new `inline` test module.
diskann/src/graph/test/cases/inline.rs	Adds end-to-end tests for `index.search(InlineSearch { .. })`, including adaptive-L behavior.
diskann/src/graph/search/multihop_search.rs	Alters scratch initialization (currently introduces a safety/correctness regression if scratch is reused).
diskann/src/graph/search/mod.rs	Adds the inline search module and publicly re-exports `InlineSearch`/`AdaptiveL`.
diskann/src/graph/search/inline_filter_search.rs	Implements inline filtered search and adaptive-L sizing; includes unit tests.
diskann-benchmark/src/main.rs	Adds an integration test that runs the new inline-filter example config.
diskann-benchmark/src/inputs/graph_index.rs	Adds `TopkInlineFilter` search phase + adaptive-L config parsing/validation.
diskann-benchmark/src/backend/index/spherical.rs	Registers and implements the inline-filter search plugin for spherical backend.
diskann-benchmark/src/backend/index/search/plugins.rs	Adds the `TopkInlineFilter` plugin type/kind mapping.
diskann-benchmark/src/backend/index/search/knn.rs	Adds `Knn` trait implementation for `benchmark_core::search::graph::InlineSearch`.
diskann-benchmark/src/backend/index/benchmarks.rs	Registers and implements the inline-filter search plugin for the main backend.
diskann-benchmark/example/graph-index-inline-filter.json	Adds a runnable benchmark example for `topk-inline-filter` with `adaptive_l`.
diskann-benchmark-core/src/search/graph/mod.rs	Exposes the new benchmark-core inline graph search helper module/type.
diskann-benchmark-core/src/search/graph/inline.rs	Adds benchmark-core `InlineSearch` wrapper + tests for inline filtering behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

hildebrandmw

Thanks Magdalen, my main concern here is getting in decent test coverage using the baseline testing infrastructure. It's more robust than ad-hoc metrics since it can store and validate a lot more information.

Also to bike shed, I do think InlineSearch is a bit vague. Maybe InlineFilteredSearch? Or FilteredKnn?

hildebrandmw · 2026-06-08T21:29:47Z

+
+use super::multihop::{BlockAndAdjust, EvenFilter, build_1d_provider, setup_grid_index};
+
+// Topology (3 levels below the start):


These tests still use the older style "looks kind of okay" approach to tests rather than using the more rigorous baseline tests that our other algorithms have moved to. This makes it significantly harder to refactor with confidence and also kind of forces us into a regime where the search sizes are pretty small.

For example, none of these integration test trigger the low-match regime of the adaptive L algorithm, so we aren't really protecting the behavior there.

Adding baselines should be relatively straightforward and greatly improves the quality of algorithm tests.

I added tests with baselines, including a test with specificity as low as .1%. Do they look good to you now?

If you comment out the unit tests for the adaptive-L, you will find the low-specificity tests that were added still never trigger the code in compute_daptive_l outside of the initial preamble (e.g., if matched == 0 || visited == 0). From what I can tell, even though a filter with a low selection percent are used, the filter is selecting for low IDs. Since the query is at [10, 10, 10] and the grid is constructed so lower coordinates have lower IDs, this actually means the selection criteria is crossed before any matches are actually found and it's always using the max multiplier.

You can test this yourself by running

cargo llvm-cov nextest --html --package diskann --cargo-profile ci

and opening ./target/llvm-cov/html/index.html and navigating to inline_filter_search.rs.

To actually test the algorithm, the initial exploration needs to see enough matched nodes before the decision point that the piecewise heuristic is actually triggered.

hildebrandmw · 2026-06-08T21:34:37Z

+
+    // Matched results tracked separately — scratch.best contains all nodes
+    // for greedy navigation, matched_results contains only filter-matching nodes.
+    let mut matched_results = Vec::new();


Should this be a NeighborPriorityQueue, or at least some other data structure that puts an upper-bound on its size?

I got a 7-10% gain in QPS from pushing results to a vector and sorting once at the end instead of using a NeighborPriorityQueue, which is why I chose not to use it. If you have alternative ideas I am happy to experiment with them!

hildebrandmw · 2026-06-09T22:31:00Z

+    adapt_cmps: usize,
+    adapt_hops: usize,
+    adapt_ids: Vec<u32>,
+}


In addition to my other comment about not triggering the piecewise functionality of adaptive-L, I think the tests here could use one more cleanup pass. Here is my suggestion:

If we want to leave ourselves open to expanding in the future, using one baseline per flavor (one for fixed-L, one for adaptive-L) instead of merging into a single struct makes this much easier. Additionally, run_inline_on_grid could then return an InlineBaseline directly instead of a mega-tuple.

It's okay to go nuts with generating multiple baselines per test.

Always include IDs and distances in baselines. This is very cheap extra protection. Basically, the more you throw in there, the better.

Probably worth also using a baseline for the three-level tests as that's cheap and captures strictly more information.

chenqingcha and others added 16 commits April 22, 2026 18:12

add greedy search

947d59b

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

35a90ea

…en/two-queue-adaptive-l

integrate two queue adaptive l search into benchmark

5eaf10a

commit to switch

20d0522

fix conflicts

7863946

merge with latest changes in main

fc593f8

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

ff89831

…en/two-queue-adaptive-l

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

d2b73b7

…en/two-queue-adaptive-l

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

4b536cc

…en/two-queue-adaptive-l

add inline search with optional adaptive l

e418879

fmt

599d5f8

add example json and integration test

bec45ca

clippy + fmt

cd914cc

remove added benchmarks

20d1e71

update documentation

22acc02

another doc update

4b00845

hildebrandmw reviewed Jun 3, 2026

View reviewed changes

Comment thread diskann-benchmark-core/src/search/graph/inline.rs

Magdalen Manohar added 5 commits June 4, 2026 15:29

respond to comments on inline_filter_search.rs

ee7fd3d

fmt

9208aaf

force AdaptiveL to be null in json, use AdaptiveL constructor to thro…

8dde86c

…w error

add test in diskann-benchmark-core for inline search

9c1d112

respond to PR comments

be183f8

added integration test

b9d32dd

harsha-simhadri reviewed Jun 5, 2026

View reviewed changes

magdalendobson linked an issue Jun 5, 2026 that may be closed by this pull request

Merge new filtered search algorithms to main #1136

Open

magdalendobson mentioned this pull request Jun 8, 2026

[RFC] What filtered search algorithms should DiskANN support? #1128

Merged

merge with main, add to spherical module

c3125d0

magdalendobson marked this pull request as ready for review June 8, 2026 17:54

magdalendobson requested review from a team and Copilot June 8, 2026 17:54

Copilot started reviewing on behalf of magdalendobson June 8, 2026 17:54 View session

Copilot AI reviewed Jun 8, 2026

View reviewed changes

magdalendobson and others added 5 commits June 8, 2026 14:02

Potential fix for pull request finding

36d5515

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

dbf6134

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

52b05f2

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

e63e620

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fix errors introduced by copilot

9cba7e1

harsha-simhadri approved these changes Jun 8, 2026

View reviewed changes

hildebrandmw reviewed Jun 8, 2026

View reviewed changes

hildebrandmw mentioned this pull request Jun 9, 2026

Add a FilteredAccessor for filtered search. #1141

Open

Magdalen Manohar added 2 commits June 9, 2026 19:34

add integration tests with baseline

0b8e9f0

fmt

ba56285

hildebrandmw reviewed Jun 9, 2026

View reviewed changes

Magdalen Manohar added 2 commits June 10, 2026 15:29

cleaned up tests

78e3cba

fmt + clippy

f47525c


		use super::multihop::{BlockAndAdjust, EvenFilter, build_1d_provider, setup_grid_index};

		// Topology (3 levels below the start):

Conversation

magdalendobson commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

magdalendobson commented Jun 4, 2026

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

magdalendobson commented Jun 3, 2026 •

edited

Loading

codecov-commenter commented Jun 4, 2026 •

edited

Loading