feat: support multi-query batch distance calculation in CalDistanceById#2422
feat: support multi-query batch distance calculation in CalDistanceById#2422LHT129 wants to merge 1 commit into
Conversation
|
/label S-waiting-on-review |
LHT129
added
kind/improvement
Merge Protections🟢 All 2 merge protections satisfied — ready to merge. Show 2 satisfied protections🟢 Require kind label
🟢 Require version label
|
|
Warning Gemini encountered an error creating the review. You can try again by commenting |
There was a problem hiding this comment.
Pull request overview
Extends the Index::CalDistanceById(const DatasetPtr&, ids, count, bool) API to support multi-query inputs (query->GetNumElements() > 1) and introduces a capability flag to advertise this behavior across selected index implementations.
Changes:
- Updated API documentation to define the multi-query
N × countrow-major distances layout and invalid-ID sentinel behavior. - Added
IndexFeature::SUPPORT_BATCH_CAL_DISTANCE_BY_IDand registered it for several in-scope algorithms. - Implemented a default multi-query loop in
InnerIndexInterface::CalDistanceById(const DatasetPtr&, ...).
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| include/vsag/index.h | Documents multi-query behavior and output layout for CalDistanceById(DatasetPtr, ...). |
| include/vsag/index_features.h | Adds SUPPORT_BATCH_CAL_DISTANCE_BY_ID feature flag. |
| src/algorithm/inner_index_interface.h | Updates interface docs for multi-query batch distance semantics. |
| src/algorithm/inner_index_interface.cpp | Adds default multi-query implementation for CalDistanceById(DatasetPtr, ...). |
| src/algorithm/hgraph/hgraph_build.cpp | Registers the new batch-distance feature for HGraph. |
| src/algorithm/ivf/ivf.cpp | Registers the new batch-distance feature for IVF (fp32 path). |
| src/algorithm/bruteforce/bruteforce.cpp | Registers the new batch-distance feature for BruteForce. |
| src/algorithm/pyramid/pyramid.cpp | Registers the new batch-distance feature for Pyramid. |
| src/algorithm/lazy_hgraph/lazy_hgraph.cpp | Registers the new batch-distance feature for LazyHGraph. |
| src/algorithm/sindi/sindi.cpp | Registers the new batch-distance feature for SINDI. |
ce4e4d8 to
4b0203f
Compare
4b0203f to
c655622
Compare
c655622 to
d2d5afa
Compare
d2d5afa to
ecc9190
Compare
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (877 changed lines across 30 files).
Submitted 4 inline comments.
Reviewed commit 6e40881.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (922 changed lines across 30 files).
Submitted 6 inline comments.
Reviewed commit d33b2c2.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (964 changed lines across 30 files).
Submitted 2 inline comments.
Reviewed commit db1e930.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (965 changed lines across 30 files).
Submitted 1 inline comment.
Reviewed commit 3bb1437.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (985 changed lines across 30 files).
Submitted 3 inline comments.
Reviewed commit 4b867ec.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (985 changed lines across 30 files).
Submitted 3 inline comments.
Reviewed commit 3a145f5.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (992 changed lines across 30 files).
Submitted 3 inline comments.
Reviewed commit 977edd0.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (989 changed lines across 30 files).
Submitted 5 inline comments.
Reviewed commit 3769288.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (989 changed lines across 30 files).
Submitted 6 inline comments.
Reviewed commit 0646c48.
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (993 changed lines across 30 files).
Submitted 3 inline comments.
Reviewed commit 56e5501.
|
Tick the box to add this pull request to the merge queue (same as
|
vsag-bot
left a comment
vsag-bot
left a comment
There was a problem hiding this comment.
Automated inline review completed.
Review effort: high (993 changed lines across 30 files).
Submitted 5 inline comments.
Reviewed commit 00b2f43.
| * If positive, returns the top-k smallest distances in ascending order along with | ||
| * matching IDs. The result Dim is min(topk, count). Invalid IDs (missing labels) are | ||
| * ranked last and only appear if there are fewer than topk valid IDs. | ||
| * @return result is valid distance of input ids. If topk == -1, Dim() is count and the |
There was a problem hiding this comment.
[P3] Do not promise metadata omitted by legacy raw overrides
This says topk == -1 returns Dim() == count, but direct raw-pointer calls to HGraph and Pyramid leave both shape fields at zero, while DiskANN and HNSW also leave Dim() unset. Callers following the new contract can treat a nonempty distance buffer as empty; populate consistent metadata in those implementations or qualify the contract.
| * Callers should check SUPPORT_BATCH_CALC_DISTANCE_BY_ID before relying on | ||
| * multi-query behavior; unsupported indexes return an error. Both the input | ||
| * IDs and result distances use row-major layout with count IDs per query: | ||
| * ids[i * count + j] is the j-th ID for query i, and distances[i * count + j] |
There was a problem hiding this comment.
[P3] Use the reduced top-k row stride in the layout description
This unconditionally describes result rows with stride count, but positive top-k results are packed with stride min(topk, count). For the second and later queries, distances[i * count + j] can therefore read past the returned allocation. Qualify this formula as the topk == -1 layout and direct top-k callers to GetDim().
- Add multi-query support to CalDistanceById batch interfaces - Add topk parameter for returning top-k smallest distances with IDs - Support HGraph, IVF, BruteForce, Pyramid, LazyHGraph, SINDI - DiskANN/HNSW reject topk != -1 - Row-major layout for multi-query IDs and distances - Invalid IDs ranked last with distance -1 - Feature flag SUPPORT_BATCH_CALC_DISTANCE_BY_ID Signed-off-by: LHT129 <tianlan.lht@antgroup.com>
Summary
Extend
CalDistanceById(const DatasetPtr&, ids, count, bool, topk=-1)to acceptDatasetPtrwithNumElements > 1, computing distances for each query against its own row of IDs. Theidsinput is a row-major matrix withnum_queries * countentries, wherecountis the number of IDs per query. The result distances buffer has the same row-major layout:distances[i * count + j]= distance from queryitoids[i * count + j].-1indicates an invalid ID.Closes #2421
Changes
include/vsag/index.h: Updated API documentation forCalDistanceById(DatasetPtr, ...)to describe multi-query behaviorinclude/vsag/index_features.h: AddedSUPPORT_BATCH_CAL_DISTANCE_BY_IDfeature flagsrc/algorithm/inner_index_interface.h/.cpp: Implemented default multi-query loop inCalDistanceById(DatasetPtr, ...). WhenNumElements > 1, constructs per-query sub-DatasetPtrs and iterates over each query row with its corresponding row of IDsSUPPORT_BATCH_CAL_DISTANCE_BY_IDfor indexes that support batch distance behaviortopk == -1and explicitly rejecttopk != -1because top-k output is not supported thereBackward Compatibility
Default runtime behavior is unchanged when
topk == -1andNumElements == 1: callers receive the full unsorted distance array without returned IDs.topk != -1enables sorted top-k(id, distance)output. The public virtual batch method signature changes by adding the finaltopkparameter, so out-of-tree subclasses must update their overrides.Scope
topk == -1;topk != -1returns unsupported