Package org.springframework.data.domain

Class Similarity

java.lang.Object

org.springframework.data.domain.Score

org.springframework.data.domain.Similarity

All Implemented Interfaces:

Serializable

public final class Similarity
extends Score

Value object representing a normalized similarity score determined by a ScoringFunction.

Similarity values are constrained to the range [0.0, 1.0], where 0.0 denotes the least similarity and 1.0 the maximum similarity. This normalization allows for consistent comparison of similarity scores across different scoring models and systems.

Primarily used in vector search and approximate nearest neighbor arrangements where results are ranked based on normalized relevance. Vector searches typically return a collection of results ordered by their similarity to the query vector.

This class is designed for use in information retrieval contexts, recommendation systems, and other applications requiring normalized comparison of results.

A Similarity instance includes both the similarity value and information about the ScoringFunction used to generate it, providing context for proper interpretation of the score.

Instances are immutable and support range-based comparisons, making them suitable for filtering and ranking operations. The class extends Score to inherit common scoring functionality while adding similarity-specific semantics.

Since:

4.0

Author:

Mark Paluch

See Also:

• Score
• Serialized Form

Method Summary

Modifier and Type	Method	Description
static Range<Similarity>	between(double minValue, double maxValue)	Creates a new Range by creating minimum and maximum Similarity from the given values without specifying a specific scoring function.
static Range<Similarity>	between(double minValue, double maxValue, ScoringFunction function)	Creates a Range of Similarity values using raw values and a specified scoring function.
static Range<Similarity>	between(Similarity min, Similarity max)	Creates a Range between the given Similarity.
boolean	equals(Object o)
static Similarity	of(double similarity)	Creates a new Similarity from a plain similarity value using ScoringFunction.unspecified().
static Similarity	of(double similarity, ScoringFunction function)	Creates a new Similarity from a raw value and the associated ScoringFunction.
static Similarity	raw(double similarity, ScoringFunction function)	Create a raw Similarity value without validation.

Methods inherited from class org.springframework.data.domain.Score

between, getFunction, getValue, hashCode, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

of

public static Similarity of(double similarity)

Creates a new Similarity from a plain similarity value using ScoringFunction.unspecified().

Parameters:

similarity - the similarity value without a specific ScoringFunction, ranging between 0 and 1.

Returns:

the new Similarity.

of

public static Similarity of(double similarity,
 ScoringFunction function)

Creates a new Similarity from a raw value and the associated ScoringFunction.

Parameters:

similarity - the similarity value in the [0.0, 1.0] range.

function - the scoring function that produced this similarity.

Returns:

a new Similarity instance.

Throws:

IllegalArgumentException - if the value is outside the allowed range.

raw

public static Similarity raw(double similarity,
 ScoringFunction function)

Create a raw Similarity value without validation.

Intended for use when accepting similarity values from trusted sources such as search engines or databases.

Parameters:

similarity - the similarity value in the [0.0, 1.0] range.

function - the scoring function that produced this similarity.

Returns:

a new Similarity instance.

between

public static Range<Similarity> between(Similarity min,
 Similarity max)

Creates a Range between the given Similarity.

Parameters:

min - lower value.

max - upper value.

Returns:

the Range between the given values.

between

public static Range<Similarity> between(double minValue,
 double maxValue)

Creates a new Range by creating minimum and maximum Similarity from the given values without specifying a specific scoring function.

Parameters:

minValue - lower value, ranging between 0 and 1.

maxValue - upper value, ranging between 0 and 1.

Returns:

the Range between the given values.

between

public static Range<Similarity> between(double minValue,
 double maxValue,
 ScoringFunction function)

Creates a Range of Similarity values using raw values and a specified scoring function.

Parameters:

minValue - the lower similarity value.

maxValue - the upper similarity value.

function - the scoring function to associate with the values.

Returns:

a Range of Similarity values.

equals

public boolean equals(Object o)

Overrides:

equals in class Score