Add support for returning SearchResult from repository query methods.

Closes: #4960

Author: mp911de

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoTemplate.java

@@ -1079,7 +1079,7 @@ <T, R> GeoResults<R> doGeoNear(NearQuery near, Class<?> domainType, String colle
 			result.add(geoResult);
 		}
 
-		Distance avgDistance = new Distance(
+		Distance avgDistance = Distance.of(
 				result.size() == 0 ? 0 : aggregate.divide(new BigDecimal(result.size()), RoundingMode.HALF_UP).doubleValue(),
 				near.getMetric());
 
@@ -2688,7 +2688,9 @@ protected <S, T> List<T> doFind(String collectionName,
 
 		if (LOGGER.isDebugEnabled()) {
 
-			Document mappedSort = preparer instanceof SortingQueryCursorPreparer sqcp ?  getMappedSortObject(sqcp.getSortObject(), entity) : null;
+			Document mappedSort = preparer instanceof SortingQueryCursorPreparer sqcp
+					? getMappedSortObject(sqcp.getSortObject(), entity)
+					: null;
 			LOGGER.debug(String.format("find using query: %s fields: %s sort: %s for class: %s in collection: %s",
 					serializeToJsonSafely(mappedQuery), mappedFields, serializeToJsonSafely(mappedSort), entityClass,
 					collectionName));
@@ -3623,7 +3625,7 @@ public GeoResult<T> doWith(Document object) {
 
 			T doWith = delegate.doWith(object);
 
-			return new GeoResult<>(doWith, new Distance(distance, metric));
+			return new GeoResult<>(doWith, Distance.of(distance, metric));
 		}
 	}
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoTemplate.java

@@ -3312,7 +3312,7 @@ public Mono<GeoResult<T>> doWith(Document object) {
 
 			double distance = getDistance(object);
 
-			return delegate.doWith(object).map(doWith -> new GeoResult<>(doWith, new Distance(distance, metric)));
+			return delegate.doWith(object).map(doWith -> new GeoResult<>(doWith, Distance.of(distance, metric)));
 		}
 
 		double getDistance(Document object) {

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/AggregationResults.java

@@ -105,4 +105,5 @@ public Document getRawResults() {
 		Object object = rawResults.get("serverUsed");
 		return object instanceof String stringValue ? stringValue : null;
 	}
+
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/convert/GeoConverters.java

@@ -270,7 +270,7 @@ enum DocumentToCircleConverter implements Converter<Document, Circle> {
 			Assert.notNull(center, "Center must not be null");
 			Assert.notNull(radius, "Radius must not be null");
 
-			Distance distance = new Distance(toPrimitiveDoubleValue(radius));
+			Distance distance = Distance.of(toPrimitiveDoubleValue(radius));
 
 			if (source.containsKey("metric")) {
 
@@ -335,7 +335,7 @@ enum DocumentToSphereConverter implements Converter<Document, Sphere> {
 			Assert.notNull(center, "Center must not be null");
 			Assert.notNull(radius, "Radius must not be null");
 
-			Distance distance = new Distance(toPrimitiveDoubleValue(radius));
+			Distance distance = Distance.of(toPrimitiveDoubleValue(radius));
 
 			if (source.containsKey("metric")) {
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/geo/Sphere.java

@@ -63,7 +63,7 @@ public Sphere(Point center, Distance radius) {
 	 * @param radius
 	 */
 	public Sphere(Point center, double radius) {
-		this(center, new Distance(radius));
+		this(center, Distance.of(radius));
 	}
 
 	/**

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/MongoSimpleTypes.java

@@ -29,6 +29,7 @@
 import org.bson.types.Decimal128;
 import org.bson.types.ObjectId;
 import org.bson.types.Symbol;
+
 import org.springframework.data.mapping.model.SimpleTypeHolder;
 
 import com.mongodb.DBRef;

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/NearQuery.java

@@ -19,6 +19,7 @@
 
 import org.bson.Document;
 import org.jspecify.annotations.Nullable;
+
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.geo.CustomMetric;
 import org.springframework.data.geo.Distance;
@@ -329,7 +330,7 @@ public NearQuery with(Pageable pageable) {
 	 */
 	@Contract("_ -> this")
 	public NearQuery maxDistance(double maxDistance) {
-		return maxDistance(new Distance(maxDistance, getMetric()));
+		return maxDistance(Distance.of(maxDistance, getMetric()));
 	}
 
 	/**
@@ -345,7 +346,7 @@ public NearQuery maxDistance(double maxDistance, Metric metric) {
 
 		Assert.notNull(metric, "Metric must not be null");
 
-		return maxDistance(new Distance(maxDistance, metric));
+		return maxDistance(Distance.of(maxDistance, metric));
 	}
 
 	/**
@@ -388,7 +389,7 @@ public NearQuery maxDistance(Distance distance) {
 	 */
 	@Contract("_ -> this")
 	public NearQuery minDistance(double minDistance) {
-		return minDistance(new Distance(minDistance, getMetric()));
+		return minDistance(Distance.of(minDistance, getMetric()));
 	}
 
 	/**
@@ -405,7 +406,7 @@ public NearQuery minDistance(double minDistance, Metric metric) {
 
 		Assert.notNull(metric, "Metric must not be null");
 
-		return minDistance(new Distance(minDistance, metric));
+		return minDistance(Distance.of(minDistance, metric));
 	}
 
 	/**
@@ -611,7 +612,7 @@ public NearQuery withReadPreference(ReadPreference readPreference) {
 	 * Get the {@link ReadConcern} to use. Will return the underlying {@link #query(Query) queries}
 	 * {@link Query#getReadConcern() ReadConcern} if present or the one defined on the {@link NearQuery#readConcern}
 	 * itself.
-	 * 
+	 *
 	 * @return can be {@literal null} if none set.
 	 * @since 4.1
 	 * @see ReadConcernAware

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/VectorSearch.java

@@ -0,0 +1,123 @@
+/*
+ * 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.mongodb.repository;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.core.annotation.AliasFor;
+import org.springframework.data.mongodb.core.aggregation.VectorSearchOperation;
+
+/**
+ * Annotation to declare Vector Search queries directly on repository methods. Vector Search queries are used to search
+ * for similar documents based on vector embeddings typically returning
+ * {@link org.springframework.data.domain.SearchResults} and limited by either a
+ * {@link org.springframework.data.domain.Score} (within) or a {@link org.springframework.data.domain.Range} of scores
+ * (between).
+ * <p>
+ * Vector search must define an index name using the {@link #indexName()} attribute. The index must be created in the
+ * MongoDB Atlas cluster before executing the query. Any misspelling of the index name will result in returning no
+ * results.
+ * <p>
+ * When using pre-filters, you can either define {@link #filter()} or use query derivation to define the pre-filter.
+ * {@link org.springframework.data.domain.Vector} and distance parameters are considered once these are present. Vector
+ * search supports sorting and will consider {@link org.springframework.data.domain.Sort} parameters.
+ *
+ * @author Mark Paluch
+ * @since 5.0
+ * @see org.springframework.data.domain.Score
+ * @see org.springframework.data.domain.Vector
+ * @see org.springframework.data.domain.SearchResults
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+@Documented
+@Query
+@Hint
+public @interface VectorSearch {
+
+	/**
+	 * Configuration whether to use
+	 * {@link org.springframework.data.mongodb.core.aggregation.VectorSearchOperation.SearchType#ANN} or
+	 * {@link org.springframework.data.mongodb.core.aggregation.VectorSearchOperation.SearchType#ENN} for the search.
+	 *
+	 * @return the search type to use.
+	 */
+	VectorSearchOperation.SearchType searchType() default VectorSearchOperation.SearchType.DEFAULT;
+
+	/**
+	 * Name of the Atlas Vector Search index to use. Atlas Vector Search doesn't return results if you misspell the index
+	 * name or if the specified index doesn't already exist on the cluster.
+	 *
+	 * @return name of the Atlas Vector Search index to use.
+	 */
+	@AliasFor(annotation = Hint.class, value = "indexName")
+	String indexName();
+
+	/**
+	 * Indexed vector type field to search. This is defaulted from the domain model using the first Vector property found.
+	 *
+	 * @return an empty String by default.
+	 */
+	String path() default "";
+
+	/**
+	 * Takes a MongoDB JSON (MQL) string defining the pre-filter against indexed fields. Supports Value Expressions. Alias
+	 * for {@link VectorSearch#filter}.
+	 *
+	 * @return an empty String by default.
+	 */
+	@AliasFor(annotation = Query.class)
+	String value() default "";
+
+	/**
+	 * Takes a MongoDB JSON (MQL) string defining the pre-filter against indexed fields. Supports Value Expressions. Alias
+	 * for {@link VectorSearch#value}.
+	 *
+	 * @return an empty String by default.
+	 */
+	@AliasFor(annotation = Query.class, value = "value")
+	String filter() default "";
+
+	/**
+	 * Number of documents to return in the results. This value can't exceed the value of {@link #numCandidates} if you
+	 * specify {@link #numCandidates}. Limit accepts Value Expressions. A Vector Search method cannot define both,
+	 * {@code limit()} and a {@link org.springframework.data.domain.Limit} parameter. Supports Value Expressions.
+	 *
+	 * @return number of documents to return in the results.
+	 */
+	String limit() default "";
+
+	/**
+	 * Number of nearest neighbors to use during the search. Value must be less than or equal to ({@code <=})
+	 * {@code 10000}. You can't specify a number less than the {@link #limit() number of documents to return}. We
+	 * recommend that you specify a number at least {@code 20} times higher than the {@link #limit() number of documents
+	 * to return} to increase accuracy.
+	 * <p>
+	 * This over-request pattern is the recommended way to trade off latency and recall in your ANN searches, and we
+	 * recommend tuning this parameter based on your specific dataset size and query requirements. Required if the query
+	 * uses
+	 * {@link org.springframework.data.mongodb.core.aggregation.VectorSearchOperation.SearchType#ANN}/{@link org.springframework.data.mongodb.core.aggregation.VectorSearchOperation.SearchType#DEFAULT}.
+	 * Supports Value Expressions.
+	 *
+	 * @return number of nearest neighbors to use during the search.
+	 */
+	String numCandidates() default "";
+
+}

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/aot/AotQueryCreator.java

@@ -25,8 +25,10 @@
 import org.jspecify.annotations.Nullable;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Range;
+import org.springframework.data.domain.Score;
 import org.springframework.data.domain.ScrollPosition;
 import org.springframework.data.domain.Sort;
+import org.springframework.data.domain.Vector;
 import org.springframework.data.geo.Distance;
 import org.springframework.data.geo.Point;
 import org.springframework.data.mongodb.core.convert.MongoCustomConversions;
@@ -129,6 +131,21 @@ public Range<Distance> getDistanceRange() {
 			return null;
 		}
 
+		@Override
+		public @Nullable Vector getVector() {
+			return null;
+		}
+
+		@Override
+		public @Nullable Score getScore() {
+			return null;
+		}
+
+		@Override
+		public @Nullable Range<Score> getScoreRange() {
+			return null;
+		}
+
 		@Override
 		public @Nullable Point getGeoNearLocation() {
 			return null;

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/aot/MongoRepositoryContributor.java

@@ -23,7 +23,6 @@
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.jspecify.annotations.Nullable;
-
 import org.springframework.core.annotation.AnnotatedElementUtils;
 import org.springframework.data.mongodb.core.MongoOperations;
 import org.springframework.data.mongodb.core.aggregation.AggregationUpdate;
@@ -160,10 +159,11 @@ private QueryInteraction createStringQuery(RepositoryInformation repositoryInfor
 
 	private static boolean backoff(MongoQueryMethod method) {
 
-		boolean skip = method.isGeoNearQuery() || method.isScrollQuery() || method.isStreamQuery();
+		boolean skip = method.isGeoNearQuery() || method.isScrollQuery() || method.isStreamQuery()
+				|| method.isSearchQuery();
 
 		if (skip && logger.isDebugEnabled()) {
-			logger.debug("Skipping AOT generation for [%s]. Method is either geo-near, streaming or scrolling query"
+			logger.debug("Skipping AOT generation for [%s]. Method is either geo-near, streaming, search or scrolling query"
 					.formatted(method.getName()));
 		}
 		return skip;

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/AbstractMongoQuery.java

@@ -164,7 +164,7 @@ private Query applyAnnotatedReadPreferenceIfPresent(Query query) {
 	}
 
 	@SuppressWarnings("NullAway")
-	private MongoQueryExecution getExecution(ConvertingParameterAccessor accessor, FindWithQuery<?> operation) {
+	MongoQueryExecution getExecution(ConvertingParameterAccessor accessor, FindWithQuery<?> operation) {
 
 		if (isDeleteQuery()) {
 			return new DeleteExecution<>(executableRemove, method);
@@ -345,7 +345,7 @@ private Document bindParameters(String source, ConvertingParameterAccessor acces
 	 * @return never {@literal null}.
 	 * @since 3.4
 	 */
-	protected ParameterBindingContext prepareBindingContext(String source, ConvertingParameterAccessor accessor) {
+	protected ParameterBindingContext prepareBindingContext(String source, MongoParameterAccessor accessor) {
 
 		ValueExpressionEvaluator evaluator = getExpressionEvaluatorFor(accessor);
 		return new ParameterBindingContext(accessor::getBindableValue, evaluator);

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/ConvertingParameterAccessor.java

@@ -22,11 +22,14 @@
 import java.util.List;
 
 import org.jspecify.annotations.Nullable;
+
 import org.springframework.data.domain.Limit;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Range;
+import org.springframework.data.domain.Score;
 import org.springframework.data.domain.ScrollPosition;
 import org.springframework.data.domain.Sort;
+import org.springframework.data.domain.Vector;
 import org.springframework.data.geo.Distance;
 import org.springframework.data.geo.Point;
 import org.springframework.data.mongodb.core.convert.MongoWriter;
@@ -73,6 +76,11 @@ public PotentiallyConvertingIterator iterator() {
 		return new ConvertingIterator(delegate.iterator());
 	}
 
+	@Override
+	public Vector getVector() {
+		return delegate.getVector();
+	}
+
 	@Override
 	public @Nullable ScrollPosition getScrollPosition() {
 		return delegate.getScrollPosition();
@@ -95,6 +103,16 @@ public Sort getSort() {
 		return getConvertedValue(delegate.getBindableValue(index), null);
 	}
 
+	@Override
+	public @org.jspecify.annotations.Nullable Score getScore() {
+		return delegate.getScore();
+	}
+
+	@Override
+	public @org.jspecify.annotations.Nullable Range<Score> getScoreRange() {
+		return delegate.getScoreRange();
+	}
+
 	@Override
 	public @Nullable Range<Distance> getDistanceRange() {
 		return delegate.getDistanceRange();
@@ -208,7 +226,7 @@ private static Collection<?> asCollection(@Nullable Object source) {
 
 		if (source instanceof Iterable<?> iterable) {
 
-			if(source instanceof Collection<?> collection) {
+			if (source instanceof Collection<?> collection) {
 				return new ArrayList<>(collection);
 			}
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoParameterAccessor.java

@@ -16,6 +16,7 @@
 package org.springframework.data.mongodb.repository.query;
 
 import org.jspecify.annotations.Nullable;
+
 import org.springframework.data.domain.Range;
 import org.springframework.data.geo.Distance;
 import org.springframework.data.geo.Point;