Documentation.

Author: mp911de

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

@@ -76,17 +76,17 @@
 	String path() default "";
 
 	/**
-	 * Takes a MongoDB JSON (MQL) string defining the pre-filter against indexed fields. Alias for
-	 * {@link VectorSearch#filter}.
+	 * 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. Alias for
-	 * {@link VectorSearch#value}.
+	 * 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.
 	 */
@@ -96,7 +96,7 @@
 	/**
 	 * 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.
+	 * {@code limit()} and a {@link org.springframework.data.domain.Limit} parameter. Supports Value Expressions.
 	 *
 	 * @return number of documents to return in the results
 	 */
@@ -109,7 +109,8 @@
 	 * to return} to increase accuracy. 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#ANN}. Supports Value
+	 * Expressions.
 	 *
 	 * @return number of documents to return in the results
 	 */

src/main/antora/modules/ROOT/nav.adoc

@@ -45,6 +45,7 @@
 ** xref:repositories/create-instances.adoc[]
 ** xref:repositories/query-methods-details.adoc[]
 ** xref:mongodb/repositories/query-methods.adoc[]
+** xref:mongodb/repositories/vector-search.adoc[]
 ** xref:mongodb/repositories/modifying-methods.adoc[]
 ** xref:repositories/projections.adoc[]
 ** xref:repositories/custom-implementations.adoc[]

src/main/antora/modules/ROOT/pages/mongodb/repositories/vector-search.adoc

@@ -0,0 +1,8 @@
+:vector-search-intro-include: data-mongodb::partial$vector-search-intro-include.adoc
+:vector-search-model-include: data-mongodb::partial$vector-search-model-include.adoc
+:vector-search-repository-include: data-mongodb::partial$vector-search-repository-include.adoc
+:vector-search-scoring-include: data-mongodb::partial$vector-search-scoring-include.adoc
+:vector-search-method-derived-include: data-mongodb::partial$vector-search-method-derived-include.adoc
+:vector-search-method-annotated-include: data-mongodb::partial$vector-search-method-annotated-include.adoc
+
+include::{commons}@data-commons::page$repositories/vector-search.adoc[]

src/main/antora/modules/ROOT/partials/vector-search-intro-include.adoc

@@ -0,0 +1 @@
+To use Vector Search with MongoDB, you need a MongoDB Atlas instance that is either running in the cloud or by using https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/[Docker].

src/main/antora/modules/ROOT/partials/vector-search-method-annotated-include.adoc

@@ -0,0 +1,23 @@
+Annotated search methods use the `@VectorSearch` annotation to define parameters for the https://www.mongodb.com/docs/upcoming/reference/operator/aggregation/vectorSearch/[`$vectorSearch`] aggregation stage.
+
+.Using `@VectorSearch` Search Methods
+====
+[source,java]
+----
+interface CommentRepository extends Repository<Comment, String> {
+
+  @VectorSearch(indexName = "cos-index", filter = "{country: ?0}")
+  SearchResults<WithVector> searchAnnotatedByCountryAndEmbeddingWithin(String country, Vector embedding,
+      Score distance);
+
+  @VectorSearch(indexName = "my-index", filter = "{country: ?0}", numCandidates = "#{#limit * 20}",
+				searchType = VectorSearchOperation.SearchType.ANN)
+  List<WithVector> findAnnotatedByCountryAndEmbeddingWithin(String country, Vector embedding, Score distance, int limit);
+}
+----
+====
+
+Annotated Search Methods can define `filter` for pre-filter usage.
+
+`filter`, `limit`, and `numCandidates` support xref:page$mongodb/value-expressions.adoc[Value Expressions] allowing references to search method arguments.
+

src/main/antora/modules/ROOT/partials/vector-search-method-derived-include.adoc

@@ -0,0 +1,21 @@
+MongoDB Search methods must use the `@VectorSearch` annotation to define the index name for the https://www.mongodb.com/docs/upcoming/reference/operator/aggregation/vectorSearch/[`$vectorSearch`] aggregation stage.
+
+.Using `Near` and `Within` Keywords in Repository Search Methods
+====
+[source,java]
+----
+interface CommentRepository extends Repository<Comment, String> {
+
+  @VectorSearch(indexName = "my-index")
+  SearchResults<Comment> searchByEmbeddingNear(Vector vector, Score score);
+
+  @VectorSearch(indexName = "my-index")
+  SearchResults<Comment> searchByEmbeddingWithin(Vector vector, Range<Similarity> range);
+
+  @VectorSearch(indexName = "my-index")
+  SearchResults<Comment> searchByCountryAndEmbeddingWithin(String country, Vector vector, Range<Similarity> range);
+}
+----
+====
+
+Derived Search Methods can define domain model attributes to create the pre-filter for indexed fields.

src/main/antora/modules/ROOT/partials/vector-search-model-include.adoc

@@ -0,0 +1,15 @@
+====
+[source,java]
+----
+class Comment {
+
+  @Id String id;
+  String country;
+  String comment;
+
+  Vector embedding;
+
+  // getters, setters, …
+}
+----
+====

src/main/antora/modules/ROOT/partials/vector-search-repository-include.adoc

@@ -0,0 +1,19 @@
+.Using `SearchResult<T>` in a Repository Search Method
+====
+[source,java]
+----
+interface CommentRepository extends Repository<Comment, String> {
+
+  @VectorSearch(indexName = "my-index")
+  SearchResults<Comment> searchByCountryAndEmbeddingNear(String country, Vector vector, Score score,
+    Limit limit);
+
+  @VectorSearch(indexName = "my-index")
+  SearchResults<WithVector> searchAnnotatedByCountryAndEmbeddingWithin(String country, Vector embedding,
+      Score score);
+
+}
+
+SearchResults<Comment> results = repository.searchByCountryAndEmbeddingNear("en", Vector.of(…), Score.of(0.9), Limit.of(10));
+----
+====

src/main/antora/modules/ROOT/partials/vector-search-scoring-include.adoc

@@ -0,0 +1,32 @@
+MongoDB reports the score directly as similarity value.
+The scoring function must be specified in the index and therefore, Vector search methods do not consider the `Score.scoringFunction`.
+The scoring function defaults to `ScoringFunction.unspecified()` as there is no information inside of search results how the score has been computed.
+
+.Using `Score` and `Similarity` in a Repository Search Methods
+====
+[source,java]
+----
+interface CommentRepository extends Repository<Comment, String> {
+
+  @VectorSearch(…)
+  SearchResults<Comment> searchByEmbeddingNear(Vector vector, Score similarity);
+
+  @VectorSearch(…)
+  SearchResults<Comment> searchByEmbeddingNear(Vector vector, Similarity similarity);
+
+  @VectorSearch(…)
+  SearchResults<Comment> searchByEmbeddingNear(Vector vector, Range<Similarity> range);
+}
+
+repository.searchByEmbeddingNear(Vector.of(…), Score.of(0.9));                <1>
+
+repository.searchByEmbeddingNear(Vector.of(…), Similarity.of(0.9));           <2>
+
+repository.searchByEmbeddingNear(Vector.of(…), Similarity.between(0.5, 1));   <3>
+----
+
+<1> Run a search and return results with a similarity of `0.9` or greater.
+<2> Return results with a similarity of `0.9` or greater.
+<3> Return results with a similarity of between `0.5` and `1.0`  or greater.
+====
+