vector-store: return similarity scores by QuerthDP · Pull Request #354 · scylladb/vector-store

QuerthDP · 2026-01-27T15:18:09Z

Extend the API to return similarity scores calculated
from the distance values and index's space type.

The similarity scores are needed to implement the optimization
to return similarity scores pre-calculated in Vector Store
when calling similarity_*() functions within ANN vector queries
with the exact same parameters as the ANN request.

The conversion from distance to similarity score is based on
comparing USearch's distance calculations versus jVector's
similarity scores calculations (which both Scylla and Cassandra use).

References: VECTOR-469

crates/vector-store/src/db_index.rs

crates/vector-store/src/lib.rs

crates/vector-store/tests/integration/opensearch.rs

crates/vector-store/tests/integration/usearch.rs

QuerthDP · 2026-01-28T09:55:39Z

Changelog:

remove the GetSpaceType message and use GetIndexIdsR instead

QuerthDP · 2026-01-28T11:15:40Z

Changelog:

refactor Distance struct to now check if distance value is finite and >=0 on creation

QuerthDP · 2026-01-28T11:31:15Z

Changelog:

add unit test for Distance validation

Copilot

Pull request overview

Extends the Vector Store ANN API to return similarity scores in addition to distances, deriving scores from distance values and the index space type.

Changes:

Add SimilarityScore type and compute similarity scores from ANN distances based on SpaceType.
Propagate space_type through the engine and expose similarity scores in the HTTP ANN response and OpenAPI spec.
Update index backends and clients/tests to handle validated distances and the expanded ANN response.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
crates/vector-store/tests/integration/usearch.rs	Updates integration tests to handle the additional `similarity_scores` return value.
crates/vector-store/tests/integration/opensearch.rs	Updates integration test to validate presence/shape of similarity scores in ANN results.
crates/vector-store/src/lib.rs	Introduces `SimilarityScore` and adds `Distance::new` validation + related unit test.
crates/vector-store/src/index/usearch.rs	Validates distances from USearch and propagates possible distance validation errors via iterators.
crates/vector-store/src/index/opensearch.rs	Validates ANN distances parsed from OpenSearch results and returns errors on invalid values.
crates/vector-store/src/httproutes.rs	Extends ANN HTTP response schema and computes `similarity_scores` using per-index `space_type`.
crates/vector-store/src/engine.rs	Stores `SpaceType` alongside index actors and returns it via `get_index_ids()`.
crates/httpclient/src/lib.rs	Extends `HttpClient::ann` to return `(primary_keys, distances, similarity_scores)`.
api/openapi.json	Updates OpenAPI schema/description to include `similarity_scores` and `SimilarityScore` schema.

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

crates/vector-store/src/lib.rs

crates/vector-store/src/httproutes.rs

QuerthDP · 2026-01-28T13:03:16Z

Changelog:

fix validator test using unnormalized vectors with dot product similarity
move Distance and Similarity to separate modules to disallow creating them by value
add tests for Distance to Similarity converstion
resolve Copilot's comments

ewienik · 2026-01-28T16:52:21Z

@knowack1 @m-szymon Do you have any comments?

knowack1

Looks super good. One nit comment - could be as follow-up if find it useful.

crates/vector-store/src/httproutes.rs

crates/vector-store/src/distance.rs

crates/vector-store/src/httproutes.rs

Add support for binary quantization space types. As for this patch, the only supported type is Hamming.

QuerthDP · 2026-02-10T13:00:48Z

Changelog:

refactored Distance to validate it's values according to the space type of the index
added support for Hamming space type and it's similarity score
rebased on master

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

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

crates/vector-store/src/similarity.rs

crates/vector-store/src/distance.rs

crates/vector-store/src/lib.rs

crates/vector-store/src/index/opensearch.rs

QuerthDP · 2026-02-10T14:01:15Z

Changelog:

check upper boundary for Hamming distance
clamp the similarity score of DotProduct to [0.0, 1.0]
return Dimension as an option as the code doesn't prevent from creation of 0 dim vectors

QuerthDP · 2026-02-10T14:19:18Z

Changelog:

remove the similarity clamp to stay compatible with Cassandra

crates/vector-store/src/distance.rs

crates/vector-store/src/lib.rs

Add a check when creating a `Distance` value to ensure that distances corresponding to the space types satisfy the mathematical boundaries. Move to a separate module to disallow for creation by value.

Extend the API to return similarity scores calculated from the distance values and index's space type. The similarity scores are needed to implement the optimization to return similarity scores pre-calculated in Vector Store when calling `similarity_*()` functions within ANN vector queries with the exact same parameters as the ANN request. The conversion from distance to similarity score is based on comparing USearch's distance calculations versus jVector's similarity scores calculations (which both Scylla and Cassandra use). The conversion from Hamming distance to Hamming similarity was introduced by us as the quotient of matched bits and all stored bits, which is a number of Vector dimensions rounded up to the nearest multiple of 8 (as packed in bytes). References: VECTOR-469

QuerthDP · 2026-02-11T14:08:18Z

Changelog:

add httproutes::Distance to split the API related Distance struct from internal Distance

QuerthDP · 2026-02-11T14:40:17Z

@m-szymon please take a look if you're OK with the validation now

m-szymon · 2026-02-11T21:33:13Z

crates/vector-store/src/similarity.rs

+            Distance::Cosine(_) | Distance::DotProduct(_) => (2.0 - d) / 2.0,
+            Distance::Euclidean(_) => 1.0 / (1.0 + d),
+            Distance::Hamming((_, dim)) => {
+                // Round up to nearest multiple of 8 to reflect that we store hamming distances packed in bytes


I don't understand why do we care about packing here. Isn't it just padded. If we define 57 dimensions is it possible to get distance 64?

When you have 57 dim vector, after quantization you will get 64 bits representing this vector. We always round up to the full byte.

yes, but the additional 7 bits are just padding. For all vectors it will be the same.

[zero] => [0, 0, ... 0, 0, 0, 0, 0, 0, 0, 0] [one] => [1, 1, ... 1, 0, 0, 0, 0, 0, 0, 0]

max distance is still 57.

You are right! You will never get 64 distance from usearch, as padding bits are always equal.

crates/vector-store/src/index/opensearch.rs

knowack1 · 2026-02-12T14:37:28Z

crates/vector-store/src/similarity.rs

+            Distance::Cosine(_) | Distance::DotProduct(_) => (2.0 - d) / 2.0,
+            Distance::Euclidean(_) => 1.0 / (1.0 + d),
+            Distance::Hamming((_, dim)) => {
+                // Round up to nearest multiple of 8 to reflect that we store hamming distances packed in bytes


When you have 57 dim vector, after quantization you will get 64 bits representing this vector. We always round up to the full byte.

QuerthDP force-pushed the return-similarity-scores branch from 0c4570d to 0fc4799 Compare January 27, 2026 15:25

QuerthDP changed the title ~~Return similarity scores~~ vector-store: return similarity scores Jan 27, 2026

QuerthDP marked this pull request as ready for review January 27, 2026 15:26

QuerthDP requested review from ewienik, knowack1 and smoczy123 and removed request for ewienik January 27, 2026 15:26

ewienik requested changes Jan 27, 2026

View reviewed changes

QuerthDP force-pushed the return-similarity-scores branch from 0fc4799 to ef9dfbe Compare January 28, 2026 09:53

QuerthDP force-pushed the return-similarity-scores branch from ef9dfbe to d0a64ac Compare January 28, 2026 11:15

QuerthDP requested a review from ewienik January 28, 2026 11:15

QuerthDP force-pushed the return-similarity-scores branch from d0a64ac to d08bc63 Compare January 28, 2026 11:30

QuerthDP requested a review from Copilot January 28, 2026 11:35

Copilot started reviewing on behalf of QuerthDP January 28, 2026 11:35 View session

Copilot AI reviewed Jan 28, 2026

View reviewed changes

crates/vector-store/src/lib.rs Outdated Show resolved Hide resolved

crates/vector-store/src/lib.rs Outdated Show resolved Hide resolved

crates/vector-store/src/httproutes.rs Outdated Show resolved Hide resolved

QuerthDP force-pushed the return-similarity-scores branch from d08bc63 to 40edafc Compare January 28, 2026 13:01

ewienik previously approved these changes Jan 28, 2026

View reviewed changes

knowack1 previously approved these changes Jan 29, 2026

View reviewed changes

crates/vector-store/src/httproutes.rs Outdated Show resolved Hide resolved

m-szymon reviewed Jan 29, 2026

View reviewed changes

crates/vector-store/src/distance.rs Outdated Show resolved Hide resolved

crates/vector-store/src/distance.rs Outdated Show resolved Hide resolved

crates/vector-store/src/httproutes.rs Show resolved Hide resolved

vector_store: support Hamming space type

badccb7

Add support for binary quantization space types. As for this patch, the only supported type is Hamming.

QuerthDP dismissed stale reviews from knowack1 and ewienik via bb56708 February 10, 2026 12:59

QuerthDP force-pushed the return-similarity-scores branch from 40edafc to bb56708 Compare February 10, 2026 12:59

QuerthDP requested review from Copilot, ewienik, knowack1 and m-szymon February 10, 2026 13:00

Copilot started reviewing on behalf of QuerthDP February 10, 2026 13:01 View session

Copilot AI reviewed Feb 10, 2026

View reviewed changes

crates/vector-store/src/similarity.rs Outdated Show resolved Hide resolved

crates/vector-store/src/distance.rs Outdated Show resolved Hide resolved

crates/vector-store/src/lib.rs Outdated Show resolved Hide resolved

crates/vector-store/src/index/opensearch.rs Show resolved Hide resolved

QuerthDP force-pushed the return-similarity-scores branch from bb56708 to 24cb867 Compare February 10, 2026 13:59

QuerthDP force-pushed the return-similarity-scores branch from 24cb867 to bb61f61 Compare February 10, 2026 14:19

ewienik requested changes Feb 11, 2026

View reviewed changes

crates/vector-store/src/distance.rs Show resolved Hide resolved

crates/vector-store/src/lib.rs Outdated Show resolved Hide resolved

QuerthDP added 2 commits February 11, 2026 15:06

vector-store: refactor Distance to error out on invalid values

8a62d73

Add a check when creating a `Distance` value to ensure that distances corresponding to the space types satisfy the mathematical boundaries. Move to a separate module to disallow for creation by value.

QuerthDP force-pushed the return-similarity-scores branch from bb61f61 to 6fe0458 Compare February 11, 2026 14:07

QuerthDP requested a review from ewienik February 11, 2026 14:08

ewienik approved these changes Feb 11, 2026

View reviewed changes

m-szymon reviewed Feb 11, 2026

View reviewed changes

m-szymon approved these changes Feb 11, 2026

View reviewed changes

knowack1 approved these changes Feb 12, 2026

View reviewed changes

Conversation

QuerthDP commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QuerthDP commented Jan 28, 2026

Uh oh!

QuerthDP commented Jan 28, 2026

Uh oh!

QuerthDP commented Jan 28, 2026

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!

QuerthDP commented Jan 28, 2026

Uh oh!

ewienik commented Jan 28, 2026

Uh oh!

knowack1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QuerthDP commented Feb 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QuerthDP commented Feb 10, 2026

Uh oh!

QuerthDP commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

QuerthDP commented Feb 11, 2026

Uh oh!

QuerthDP commented Feb 11, 2026

Uh oh!

m-szymon Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

knowack1 Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

m-szymon Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

knowack1 Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

knowack1 Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

QuerthDP commented Jan 27, 2026 •

edited

Loading