Return indexed vectors after disk search

[Yujie Zhang (yjiez)]

Summary

• add an optional disk-search API that returns each final hit with its canonical indexed vector
• run the existing search unchanged, then batch-load only the final result IDs
• reuse the existing scratch pool and cap final reads at 128 IDs per batch
• keep traversal, post-processing, caches, and search statistics untouched

This supersedes #1345 with the post-search approach requested in review.

Validation

• cargo check -p diskann-disk --tests
• cargo test -p diskann-disk --lib indexed_vectors
• CI format, clippy, docs, CodeQL, SDE, and Linux workspace tests

Benchmark

K=1000, L=2000, four order-balanced paired runs (AB, BA, BA, AB):

Dataset	QPS delta	Mean API latency	P95 API latency	Peak memory delta
Wikipedia-100K	-10.71%	+12.00%	+12.37%	+14.9 MiB
OpenAI-100K	-15.43%	+18.55%	+18.44%	+29.4 MiB

Recall is unchanged. Returned payload is 3,072,000 bytes/query for Wikipedia and 6,144,000 bytes/query for OpenAI.

The final-only approach uses less peak memory than traversal caching at the same K/L (23.3 MiB and 46.7 MiB), at the cost of rereading the final K nodes.

Runs: AB 1, BA 1, BA 2, AB 2. Cached comparison: 32388396932.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an opt-in disk search API in diskann-disk that returns each valid search hit along with its canonical indexed (stored) vector, implemented as a post-search batch load of only the final result IDs.

Changes:

• Introduces new public result types that include an indexed_vector per hit.
• Adds DiskIndexSearcher::search_with_indexed_vectors, which runs the existing search unchanged, truncates to stats.result_count, then batch-loads vectors for those IDs.
• Adds a unit test covering parity with legacy search (IDs/distances) and validating returned vectors across caching strategies and filter modes.

Suppressed comments (1)

diskann-disk/src/search/provider/disk_provider.rs:862

• SearchResultItemWithIndexedVector is part of the public API but currently lacks field-level documentation, while the existing SearchResultItem documents its fields. Mirroring that documentation here makes it clearer what indexed_vector represents (native stored vector, not PQ code, etc.).

pub struct SearchResultItemWithIndexedVector<AssociatedData, VectorData> {
    pub vertex_id: u32,
    pub data: AssociatedData,
    pub distance: f32,
    pub indexed_vector: Box<[VectorData]>,

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

❌ Patch coverage is 98.27586% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.58%. Comparing base (6f2ff48) to head (8642d25).

Files with missing lines	Patch %	Lines
diskann-disk/src/search/provider/disk_provider.rs	98.27%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1347   +/-   ##
=======================================
  Coverage   91.58%   91.58%           
=======================================
  Files         521      521           
  Lines       99598    99656   +58     
=======================================
+ Hits        91212    91267   +55     
- Misses       8386     8389    +3     

Flag	Coverage Δ
miri	91.58% <98.27%> (+<0.01%)	⬆️
unittests	91.26% <98.27%> (+<0.01%)	⬆️

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

Files with missing lines	Coverage Δ
diskann-disk/src/search/provider/disk_provider.rs	95.87% <98.27%> (+0.11%)	⬆️

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[weiyaoluo (SeliMeli)]

seems like we are asserting/test multiple behavior in one tests, can we split it so one thing to test per ut?