Add raw Similarity, improve SearchResult detection.

Author: mp911de

src/main/java/org/springframework/data/domain/Score.java

@@ -68,30 +68,6 @@ public static Range<Score> between(Score min, Score max) {
 		return Range.from(Range.Bound.inclusive(min)).to(Range.Bound.inclusive(max));
 	}
 
-	/**
-	 * Creates a new {@link Range} by creating minimum and maximum {@link Score} from the given values without
-	 * {@link ScoringFunction#UNSPECIFIED specifying a scoring function}.
-	 *
-	 * @param minValue minimum value.
-	 * @param maxValue maximum value.
-	 * @return the {@link Range} between the given values.
-	 */
-	public static Range<Score> between(double minValue, double maxValue) {
-		return between(minValue, maxValue, ScoringFunction.UNSPECIFIED);
-	}
-
-	/**
-	 * Creates a new {@link Range} by creating minimum and maximum {@link Score} from the given values.
-	 *
-	 * @param minValue minimum value.
-	 * @param maxValue maximum value.
-	 * @param function the scoring function to use.
-	 * @return the {@link Range} between the given values.
-	 */
-	public static Range<Score> between(double minValue, double maxValue, ScoringFunction function) {
-		return between(Score.of(minValue, function), Score.of(maxValue, function));
-	}
-
 	public double getValue() {
 		return value;
 	}

src/main/java/org/springframework/data/domain/SearchResults.java

@@ -50,6 +50,7 @@ public List<SearchResult<T>> getContent() {
 	}
 
 	@Override
+	@SuppressWarnings("unchecked")
 	public Iterator<SearchResult<T>> iterator() {
 		return (Iterator<SearchResult<T>>) results.iterator();
 	}
@@ -64,11 +65,7 @@ public <U> SearchResults<U> map(Function<? super T, ? extends U> converter) {
 
 		Assert.notNull(converter, "Function must not be null");
 
-		List<SearchResult<U>> result = results.stream().map(it -> {
-
-			SearchResult<U> mapped = it.map(converter);
-			return mapped;
-		}).collect(Collectors.toList());
+		List<SearchResult<U>> result = results.stream().map(it -> it.<U> map(converter)).collect(Collectors.toList());
 
 		return new SearchResults<>(result);
 	}
@@ -93,7 +90,8 @@ public int hashCode() {
 
 	@Override
 	public String toString() {
-		return String.format("SearchResults: [results: %s]", StringUtils.collectionToCommaDelimitedString(results));
+		return results.isEmpty() ? "SearchResults: [empty]"
+				: String.format("SearchResults: [results: %s]", StringUtils.collectionToCommaDelimitedString(results));
 	}
 
 }

src/main/java/org/springframework/data/domain/Similarity.java

@@ -18,7 +18,7 @@
 import org.springframework.util.Assert;
 
 /**
- * Value object to represent a similarity score determined by a {@link ScoringFunction}. Similarity is expressed through
+ * Value object to represent a similarity value determined by a {@link ScoringFunction}. Similarity is expressed through
  * a numerical value ranging between {@code 0} and {@code 1} where zero represents the lowest similarity and one the
  * highest similarity.
  * <p>
@@ -35,27 +35,40 @@ private Similarity(double value, ScoringFunction function) {
 	}
 
 	/**
-	 * Creates a new {@link Similarity} from a plain {@code score} value using {@link ScoringFunction#UNSPECIFIED}.
+	 * Creates a new {@link Similarity} from a plain {@code similarity} value using {@link ScoringFunction#UNSPECIFIED}.
 	 *
-	 * @param score the score value without a specific {@link ScoringFunction}, ranging between {@code 0} and {@code 1}.
+	 * @param similarity the similarity value without a specific {@link ScoringFunction}, ranging between {@code 0} and
+	 *          {@code 1}.
 	 * @return the new {@link Similarity}.
 	 */
-	public static Similarity of(double score) {
-		return of(score, ScoringFunction.UNSPECIFIED);
+	public static Similarity of(double similarity) {
+		return of(similarity, ScoringFunction.UNSPECIFIED);
 	}
 
 	/**
-	 * Creates a new {@link Similarity} from a {@code score} value using the given {@link ScoringFunction}.
+	 * Creates a new {@link Similarity} from a {@code similarity} value using the given {@link ScoringFunction}.
 	 *
-	 * @param score the score value, ranging between {@code 0} and {@code 1}.
-	 * @param function the scoring function that has computed the {@code score}.
+	 * @param similarity the similarity value, ranging between {@code 0} and {@code 1}.
+	 * @param function the scoring function that has computed the {@code similarity}.
 	 * @return the new {@link Similarity}.
 	 */
-	public static Similarity of(double score, ScoringFunction function) {
+	public static Similarity of(double similarity, ScoringFunction function) {
 
-		Assert.isTrue(score >= (double) 0.0F && score <= (double) 1.0F, "Similarity must be in [0,1] range.");
+		Assert.isTrue(similarity >= 0.0 && similarity <= 1.0, "Similarity must be in [0,1] range.");
 
-		return new Similarity(score, function);
+		return new Similarity(similarity, function);
+	}
+
+	/**
+	 * Creates a new raw {@link Similarity} from a {@code similarity} value using the given {@link ScoringFunction}.
+	 * Typically, this method is used when accepting external similarity values coming from a database search result.
+	 *
+	 * @param similarity the similarity value, ranging between {@code 0} and {@code 1}.
+	 * @param function the scoring function that has computed the {@code similarity}.
+	 * @return the new {@link Similarity}.
+	 */
+	public static Similarity raw(double similarity, ScoringFunction function) {
+		return new Similarity(similarity, function);
 	}
 
 	/**
@@ -77,7 +90,7 @@ public static Range<Similarity> between(Similarity min, Similarity max) {
 	 * @param maxValue maximum value, ranging between {@code 0} and {@code 1}.
 	 * @return the {@link Range} between the given values.
 	 */
-	public static Range<Score> between(double minValue, double maxValue) {
+	public static Range<Similarity> between(double minValue, double maxValue) {
 		return between(minValue, maxValue, ScoringFunction.UNSPECIFIED);
 	}
 
@@ -89,8 +102,8 @@ public static Range<Score> between(double minValue, double maxValue) {
 	 * @param function the scoring function to use.
 	 * @return the {@link Range} between the given values.
 	 */
-	public static Range<Score> between(double minValue, double maxValue, ScoringFunction function) {
-		return (Range) between(Similarity.of(minValue, function), Similarity.of(maxValue, function));
+	public static Range<Similarity> between(double minValue, double maxValue, ScoringFunction function) {
+		return between(Similarity.of(minValue, function), Similarity.of(maxValue, function));
 	}
 
 	@Override
@@ -100,4 +113,5 @@ public boolean equals(Object o) {
 		}
 		return super.equals(other);
 	}
+
 }

src/main/java/org/springframework/data/repository/query/Parameters.java

@@ -124,8 +124,7 @@ protected Parameters(ParametersSource parametersSource, Function<MethodParameter
 			}
 
 			if (Range.class.isAssignableFrom(parameter.getType())
-					&& ResolvableType.forMethodParameter(methodParameter).getGeneric(0)
-							.isAssignableFrom(Score.class)) {
+					&& Score.class.isAssignableFrom(ResolvableType.forMethodParameter(methodParameter).getGeneric(0).toClass())) {
 				scoreRangeIndex = i;
 			}
 

src/main/java/org/springframework/data/repository/query/QueryMethod.java

@@ -26,6 +26,7 @@
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.ScrollPosition;
+import org.springframework.data.domain.SearchResult;
 import org.springframework.data.domain.SearchResults;
 import org.springframework.data.domain.Slice;
 import org.springframework.data.domain.Sort;
@@ -42,6 +43,7 @@
 import org.springframework.data.util.TypeInformation;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
+import org.springframework.util.ClassUtils;
 
 /**
  * Abstraction of a method that is designated to execute a finder query. Enriches the standard {@link Method} interface
@@ -282,13 +284,21 @@ public final boolean isPageQuery() {
 	}
 
 	/**
-	 * Returns whether the finder will return a {@link SearchResults} of results.
+	 * Returns whether the finder will return a {@link SearchResults} (or collection of {@link SearchResult}) of results.
 	 *
 	 * @return
 	 * @since 4.0
 	 */
-	public final boolean isSearchQuery() {
-		return org.springframework.util.ClassUtils.isAssignable(SearchResults.class, unwrappedReturnType);
+	public boolean isSearchQuery() {
+
+		if (ClassUtils.isAssignable(SearchResults.class, unwrappedReturnType)) {
+			return true;
+		}
+
+		TypeInformation<?> returnType = metadata.getReturnType(method);
+		TypeInformation<?> componentType = returnType.getComponentType();
+
+		return componentType != null && SearchResult.class.isAssignableFrom(componentType.getType());
 	}
 
 	/**

src/main/java/org/springframework/data/repository/util/QueryExecutionConverters.java

@@ -38,6 +38,7 @@
 import org.springframework.core.convert.support.ConfigurableConversionService;
 import org.springframework.core.convert.support.DefaultConversionService;
 import org.springframework.data.domain.Page;
+import org.springframework.data.domain.SearchResult;
 import org.springframework.data.domain.SearchResults;
 import org.springframework.data.domain.Slice;
 import org.springframework.data.domain.Window;
@@ -255,6 +256,7 @@ public static TypeInformation<?> unwrapWrapperTypes(TypeInformation<?> type, Typ
 		boolean needToUnwrap = type.isCollectionLike() //
 				|| Slice.class.isAssignableFrom(rawType) //
 				|| GeoResults.class.isAssignableFrom(rawType) //
+				|| SearchResult.class.isAssignableFrom(rawType) //
 				|| SearchResults.class.isAssignableFrom(rawType) //
 				|| rawType.isArray() //
 				|| supports(rawType) //

src/test/java/org/springframework/data/domain/SimilarityUnitTests.java

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.domain;
+
+import static org.assertj.core.api.Assertions.*;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Unit tests for {@link Similarity}.
+ *
+ * @author Mark Paluch
+ */
+class SimilarityUnitTests {
+
+	@Test
+	void shouldBeBounded() {
+
+		assertThatIllegalArgumentException().isThrownBy(() -> Similarity.of(-1));
+		assertThatIllegalArgumentException().isThrownBy(() -> Similarity.of(1.01));
+	}
+
+	@Test
+	void shouldConstructRawSimilarity() {
+
+		Similarity similarity = Similarity.raw(2, ScoringFunction.UNSPECIFIED);
+
+		assertThat(similarity.getValue()).isEqualTo(2);
+	}
+
+	@Test
+	void shouldConstructGenericSimilarity() {
+
+		Similarity similarity = Similarity.of(1);
+
+		assertThat(similarity).isEqualTo(Similarity.of(1)).isNotEqualTo(Score.of(1)).isNotEqualTo(Similarity.of(0.5));
+		assertThat(similarity).hasToString("1.0");
+		assertThat(similarity.getFunction()).isEqualTo(ScoringFunction.UNSPECIFIED);
+	}
+
+	@Test
+	void shouldConstructMeteredSimilarity() {
+
+		Similarity similarity = Similarity.of(1, VectorScoringFunctions.COSINE);
+
+		assertThat(similarity).isEqualTo(Similarity.of(1, VectorScoringFunctions.COSINE))
+				.isNotEqualTo(Score.of(1, VectorScoringFunctions.COSINE)).isNotEqualTo(Similarity.of(1));
+		assertThat(similarity).hasToString("1.0 (COSINE)");
+		assertThat(similarity.getFunction()).isEqualTo(VectorScoringFunctions.COSINE);
+	}
+
+	@Test
+	void shouldConstructRange() {
+
+		Range<Similarity> range = Similarity.between(0.5, 1);
+
+		assertThat(range.getLowerBound().getValue()).contains(Similarity.of(0.5));
+		assertThat(range.getLowerBound().isInclusive()).isTrue();
+
+		assertThat(range.getUpperBound().getValue()).contains(Similarity.of(1));
+		assertThat(range.getUpperBound().isInclusive()).isTrue();
+	}
+
+	@Test
+	void shouldConstructRangeWithFunction() {
+
+		Range<Similarity> range = Similarity.between(0.5, 1, VectorScoringFunctions.COSINE);
+
+		assertThat(range.getLowerBound().getValue()).contains(Similarity.of(0.5, VectorScoringFunctions.COSINE));
+		assertThat(range.getLowerBound().isInclusive()).isTrue();
+
+		assertThat(range.getUpperBound().getValue()).contains(Similarity.of(1, VectorScoringFunctions.COSINE));
+		assertThat(range.getUpperBound().isInclusive()).isTrue();
+	}
+
+}

src/test/java/org/springframework/data/repository/query/ParametersUnitTests.java

@@ -31,6 +31,9 @@
 import org.springframework.data.domain.OffsetScrollPosition;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
+import org.springframework.data.domain.Range;
+import org.springframework.data.domain.Score;
+import org.springframework.data.domain.Similarity;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.domain.Window;
 import org.springframework.data.repository.Repository;
@@ -230,6 +233,22 @@ void considersGenericType() throws Exception {
 		assertThat(parameters.getParameter(0).getType()).isEqualTo(Long.class);
 	}
 
+	@Test // GH-
+	void considersScoreRange() throws Exception {
+
+		var parameters = getParametersFor("methodWithScoreRange", Range.class);
+
+		assertThat(parameters.hasScoreRangeParameter()).isTrue();
+	}
+
+	@Test // GH-
+	void considersSimilarityRange() throws Exception {
+
+		var parameters = getParametersFor("methodWithSimilarityRange", Range.class);
+
+		assertThat(parameters.hasScoreRangeParameter()).isTrue();
+	}
+
 	private Parameters<?, Parameter> getParametersFor(String methodName, Class<?>... parameterTypes)
 			throws SecurityException, NoSuchMethodException {
 
@@ -268,6 +287,10 @@ interface SampleDao extends Repository<User, String> {
 
 		void methodWithSingle(Single<String> single);
 
+		void methodWithScoreRange(Range<Score> single);
+
+		void methodWithSimilarityRange(Range<Similarity> single);
+
 		Page<Object> customPageable(SomePageable pageable);
 
 		Window<Object> customScrollPosition(OffsetScrollPosition request);