[WIP] IVF Index: Insert and Search by arkrishn94 · Pull Request #1187 · microsoft/DiskANN

Aditya Krishnan (arkrishn94) · 2026-06-18T15:47:46Z

I am still working on adding documentation, testing and cleaning up some parts of this. If you're interested, please take a look at traits.rs and index.rs to see the entry points for the algorithm.

Introduces diskann::ivf with the IvfIndex wrapper, five core glue traits (ListAccessor, SearchAccessor, SearchStrategy, InsertAccessor, IvfInsertStrategy), an example list-owned IVF-Flat provider, an exact oracle harness, and a test suite covering correctness, concurrency, inserts (including concurrent inserts), and error escalation.

Codecov Comments Bot (codecov-commenter) · 2026-06-18T16:11:20Z

Codecov Report

❌ Patch coverage is 93.97727% with 53 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.51%. Comparing base (d9ce362) to head (b70b235).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
diskann/src/ivf/test/provider.rs	88.95%	39 Missing ⚠️
diskann/src/ivf/test/cases/insert.rs	96.69%	4 Missing ⚠️
diskann/src/ivf/test/cases/correctness.rs	94.91%	3 Missing ⚠️
diskann/src/ivf/index.rs	97.75%	2 Missing ⚠️
diskann/src/ivf/test/cases/errors.rs	96.66%	2 Missing ⚠️
diskann/src/ivf/test/harness.rs	97.95%	2 Missing ⚠️
diskann/src/ivf/test/cases/concurrency.rs	98.73%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1187      +/-   ##
==========================================
+ Coverage   89.47%   89.51%   +0.03%     
==========================================
  Files         486      495       +9     
  Lines       92161    93050     +889     
==========================================
+ Hits        82458    83290     +832     
- Misses       9703     9760      +57

Flag	Coverage Δ
miri	`89.51% <93.97%> (+0.03%)`	⬆️
unittests	`89.16% <93.97%> (+0.04%)`	⬆️

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

Files with missing lines	Coverage Δ
diskann/src/ivf/test/cases/mod.rs	`100.00% <100.00%> (ø)`
diskann/src/ivf/test/cases/concurrency.rs	`98.73% <98.73%> (ø)`
diskann/src/ivf/index.rs	`97.75% <97.75%> (ø)`
diskann/src/ivf/test/cases/errors.rs	`96.66% <96.66%> (ø)`
diskann/src/ivf/test/harness.rs	`97.95% <97.95%> (ø)`
diskann/src/ivf/test/cases/correctness.rs	`94.91% <94.91%> (ø)`
diskann/src/ivf/test/cases/insert.rs	`96.69% <96.69%> (ø)`
diskann/src/ivf/test/provider.rs	`88.95% <88.95%> (ø)`

... and 18 files with indirect coverage changes

🚀 New features to boost your workflow:

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

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:13:58Z

+    }
+
+    /// Insert a vector under external id `id`.
+    pub fn insert<'a, S, T>(


Do we also want delete in this interface?

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:14:55Z

+        context: &'a P::Context,
+        id: &P::ExternalId,
+        vector: T,
+    ) -> impl SendFuture<ANNResult<()>>


Should we have the concept of an index that is read-only? I am thinking of designs where the index is loaded into memory for maintenance and then queries are served from a slower provider. In that case, we don't necessarily want to support insert/delete in the slower provider.

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:16:54Z

+    pub fn knn_search<'a, S, T, OB>(
+        &'a self,
+        k: NonZeroUsize,
+        nprobe: usize,


Should nprobe be a NonZeroUsize that we enforce is greater than or equal to k?

Also, how will this contract deal with parameters used for searching the centroid index (i.e. L_search)? Maybe it should take in a type CentroidSearchParams or something similar instead

Well, >= k maybe doesn't make sense, but maybe n_probe * min_size >= k? That would, however, mean we needed to enforce the minimum size strictly.

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:18:09Z

+
+            let k = k.get();
+            let mut queue = NeighborPriorityQueue::new(k);
+            let mut cmps: u32 = 0;


We should also count distance comparisons done to select centroids, right?

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:22:05Z

+}
+
+/// Per-call factory for IVF insert.
+pub trait InsertStrategy<'a, Provider, T>: Send + Sync


Trying to understand the vision for the dynamic case here--is the idea that we will later extend this to deletes, at which point we call it something like DynamicStrategy, or that there will be a separate DeleteStrategy object?

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:27:32Z

+
+After a maintenance accessor returns `Ok(())` from `apply`:
+
+1. Every visible point is assigned to exactly one live list.


This seems like something we do not want to deeply commit to in our architecture. Replication of points is a pretty standard technique in IVF.

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:28:23Z

+2. `assignment[point] == list` if and only if `point` is a member of `list`.
+3. Every live list has exactly one live centroid with the same logical id.
+4. Every list member has an available canonical vector and scan payload.
+5. Retired list ids are never reused for a different centroid.


Why can't we reuse list ids? This seems like something we might want to do.

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:29:26Z

+5. Retired list ids are never reused for a different centroid.
+6. Point identity mappings agree with point visibility in the partition.
+7. Inserts may trigger splits but not dissolves.
+8. Deletes may trigger dissolves but not splits.


Do we want to commit that deletes can't trigger splits? I think this is a bit contrary to some of our discussions on a batching API, and iirc we did at least one experiment that shows that this policy would degrade recall.

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:36:53Z

+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PointMove<Id, ListId> {
+    /// Internal point id being inserted, deleted, or reassigned.
+    pub id: Id,
+    /// Previous list, or `None` for a newly inserted point.
+    pub from: Option<ListId>,
+    /// New list, or `None` for a deleted point.
+    pub to: Option<ListId>,
+}


It might make debugging/reading code easier if we made this an enum over delete, insert, and reassign, but just a thought

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:45:00Z

+### Split Semantics
+
+A split retires one parent and installs two children, for a net increase of one
+live cluster. Parent ids are never reused. Candidate centroids for a region are


Why can't parent ids be reused?

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:46:21Z

+   current assignment.
+2. Stage deletion of each point id.
+3. Group deletes by list and compute projected post-delete sizes.
+4. Admit underfull victims without crossing `min_clusters`.


Is a victim a centroid that is being deleted, or the points in the deleted centroid's posting list? What does it mean to "admit" them?

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T18:49:05Z

+centroid cannot make a point already assigned to another surviving centroid
+prefer the removed centroid. Deletes never trigger a split in the same
+operation. A survivor above the split threshold remains eligible for the next
+insert-driven split.


We should add a section for a combined insert/delete batch API since that will likely be necessary. Also, I don't think we should allow deletes to over-fill a posting list. In fact, we should maintain an invariant that posting list updates passed via the PartitionUpdate can never exceed the maximum number of points. We can be flexible on the minimum number of points, but by being inflexible on the max we maintain openness to providers that do a fixed allocation for each posting list.

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T19:08:57Z

+- Design blob coordination separately rather than forcing disk and blob through
+  one generic publication protocol.
+
+## Testing Strategy


We should add some integration tests with exact baselines using the same framework as is used for DiskANN.

Magdalen Dobson Manohar (magdalendobson) · 2026-09-21T19:10:01Z

 // Index Implementations
 pub mod flat;
 pub mod graph;
+pub mod ivf;


Meta-question, do we want a separate diskann-ivf crate or do we want inclusion within diskann?

Great question. Not quite sure. If diskann is going to be the home for the algorithms, then maybe it should live there?

Magdalen Dobson Manohar (magdalendobson) · 2026-09-22T17:41:26Z

+    /// Errors from list selection or scanning.
+    type Error: ToRanked + Debug + Send + Sync + 'static;
+
+    /// Select exactly the available requested number of lists for the bound query.


This should probably also return some kind of stats object

Magdalen Dobson Manohar (magdalendobson) · 2026-09-23T18:24:08Z

+///
+/// The centroid catalog is authoritative. Approximate implementations, such as
+/// a graph navigator, must retain enough catalog information to reject retired
+/// ids and recover with exact selection when navigation cannot produce a usable


We expect a graph index to handle fallback to flat scan? Why is that? That's not typical for DiskANN in general, is there a reason it would be needed for an IVF centroid index?

Co-authored-by: Magdalen Manohar <magdalen@magdalen.localdomain>

Magdalen Dobson Manohar (magdalendobson) · 2026-10-01T17:18:37Z

+/// Staged points, their canonical vectors, and their routes.
+///
+/// Batch position `i` refers to `ids[i]`, row `i` of `vectors`, and `routes[i]`.
+pub(in crate::ivf) struct StagedBatch<Id, L> {


What is the difference between pub(in crate::ivf) and pub(crate) here?

Magdalen Dobson Manohar (magdalendobson) · 2026-10-27T21:32:19Z

+    ///
+    /// - [`ReassignCount::None`] corresponds to no neighborhood gathering.
+    /// - [`ReassignCount::Count`] coresponds to a non-zero neighborhood size to be gathered.
+    pub reassign_count: ReassignCount,


Why should we allow this to be zero?

In case we want to do pure splits, without any neighborhood re-assignment.

Magdalen Dobson Manohar (magdalendobson) · 2026-10-27T21:33:25Z

+    /// - [`ReassignCount::Count`] coresponds to a non-zero neighborhood size to be gathered.
+    pub reassign_count: ReassignCount,
+    /// Positive number of Lloyd steps per parent.
+    pub split_iterations: NonZeroUsize,


Is the number of Lloyd steps something that we really want to configure? Are there like meaningful performance tradeoffs that the user might want to have a say in here?

Hmm fair enough. There is a sort of tradeoff here, could probably set it between 4-5 iterations. Below that quality degrades but is pretty fast, more than that gives minimal gains but is much slower.

Magdalen Dobson Manohar (magdalendobson) · 2026-10-27T21:34:00Z

+    pub reassign_count: ReassignCount,
+    /// Positive number of Lloyd steps per parent.
+    pub split_iterations: NonZeroUsize,
+    pub seed: u64,


Same question here I guess, is it really what we want to pass in a seed?

I see what you're saying. We want the Config to be only what the user passes in. I guess the seed should move to some kind of set of default values.

Magdalen Dobson Manohar (magdalendobson) · 2026-10-29T20:00:57Z

+
+        async move {
+            let mut accessor = strategy.build_accessor(context).into_ann_result()?;
+


Would be helpful to have some comments on this part

Magdalen Dobson Manohar (magdalendobson) · 2026-10-29T20:03:47Z

+        async move {
+            let mut accessor = strategy.build_accessor(context).into_ann_result()?;
+
+            let mut parents = BTreeSet::new();


Should this be a set?

Aditya Krishnan (arkrishn94) added 4 commits June 16, 2026 10:45

init rfc

64dedef

Merge remote-tracking branch 'origin/main' into u/adkrishnan/ivf-index

70ad067

delete rfc

b70b235

dynamic index glue/trait initial brainstorm

4a18959

Magdalen Dobson Manohar (magdalendobson) reviewed Sep 21, 2026

View reviewed changes

Magdalen Dobson Manohar (magdalendobson) reviewed Sep 22, 2026

View reviewed changes

Magdalen Dobson Manohar (magdalendobson) reviewed Sep 23, 2026

View reviewed changes

Add co-location sets to the initial contract (#1438)

092aa7d

Co-authored-by: Magdalen Manohar <magdalen@magdalen.localdomain>

Aditya Krishnan (arkrishn94) added this to DiskANN backlog Sep 29, 2026

Aditya Krishnan (arkrishn94) removed this from DiskANN backlog Sep 29, 2026

Aditya Krishnan (arkrishn94) linked an issue Sep 29, 2026 that may be closed by this pull request

Implement the accessor and the insert path #1191

Open

Aditya Krishnan (arkrishn94) added 3 commits September 29, 2026 11:55

initial index impl, lots more to go

d076377

lots to change but we're getting somewhere

83c451a

cutting superfluous things

a15c479

Magdalen Dobson Manohar (magdalendobson) reviewed Oct 1, 2026

View reviewed changes

Aditya Krishnan (arkrishn94) added 17 commits October 19, 2026 14:59

clusterer and assigner

855fb98

move to lloyd impl in diskann-quantization

e3beea5

some more small edits to clustering

a4cee32

clean up staging and remove provider

41c19b8

propagate to tests

b9f0d93

update gets a lifetime

deffb3c

route and nearest gets a callback

4e9e3a3

add search and generalize vector representation

d4b1cd9

consolidate setelements, routing and appending

2aae826

refactor modules a bit

a6e53c9

fold clustering into

291bc5b

conslidate clustering and assignment

794731d

some renaming

dbe1dd7

search accessor, accumulator

06ce7fc

small edits

5cc1dbf

clean up collectors in split

6ea9786

introducing plans

fe6f666

Aditya Krishnan (arkrishn94) changed the title ~~[WIP] IVF index interface~~ [WIP] IVF Index: Insert and Search Oct 27, 2026

Magdalen Dobson Manohar (magdalendobson) reviewed Oct 27, 2026

View reviewed changes

Aditya Krishnan (arkrishn94) added 6 commits October 28, 2026 17:54

this is something?

39472aa

break up plan into links

66cfe92

introducing Assign

94114cc

introducing Seed

5bab975

twomeans -> kmeans

bfd81e4

nuke the rfc

c062286

Magdalen Dobson Manohar (magdalendobson) reviewed Oct 29, 2026

View reviewed changes

add finish to update and separate split and re-assign

211d815


		After a maintenance accessor returns `Ok(())` from `apply`:

		1. Every visible point is assigned to exactly one live list.


		async move {
		let mut accessor = strategy.build_accessor(context).into_ann_result()?;

Conversation

Aditya Krishnan (arkrishn94) commented Jun 18, 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 Jun 18, 2026

Codecov Report

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!

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!

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!

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!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Aditya Krishnan (arkrishn94) commented Jun 18, 2026 •

edited

Loading