Update documentation

Author: christophstrobl

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

@@ -25,7 +25,6 @@
 
 import org.bson.BinaryVector;
 import org.bson.Document;
-
 import org.springframework.data.domain.Limit;
 import org.springframework.data.domain.Vector;
 import org.springframework.data.mongodb.core.mapping.MongoVector;
@@ -38,7 +37,6 @@
 /**
  * Performs a semantic search on data in your Atlas cluster. This stage is only available for Atlas Vector Search.
  * Vector data must be less than or equal to 4096 dimensions in width.
- * <p>
  * <h3>Limitations</h3> You cannot use this stage together with:
  * <ul>
  * <li>{@link org.springframework.data.mongodb.core.aggregation.LookupOperation Lookup} stages</li>

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

@@ -63,7 +63,7 @@ public DefaultSearchIndexOperations(MongoOperations mongoOperations, String coll
 	}
 
 	@Override
-	public String ensureIndex(SearchIndexDefinition indexDefinition) {
+	public String createIndex(SearchIndexDefinition indexDefinition) {
 
 		Document index = indexDefinition.getIndexDocument(entityTypeInformation,
 				mongoOperations.getConverter().getMappingContext());

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

@@ -33,9 +33,23 @@ public interface IndexOperations {
 	 *
 	 * @param indexDefinition must not be {@literal null}.
 	 * @return the index name.
+	 * @deprecated in favor of {@link #createIndex(IndexDefinition)}.
 	 */
+	@Deprecated(since = "4.5", forRemoval = true)
 	String ensureIndex(IndexDefinition indexDefinition);
 
+	/**
+	 * Create the index for the provided {@link IndexDefinition} exists for the collection indicated by the entity
+	 * class. If not it will be created.
+	 *
+	 * @param indexDefinition must not be {@literal null}.
+	 * @return the index name.
+	 * @since 4.5
+	 */
+	default String createIndex(IndexDefinition indexDefinition) {
+		return ensureIndex(indexDefinition);
+	}
+
 	/**
 	 * Alters the index with given {@literal name}.
 	 *

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

@@ -33,7 +33,18 @@ public interface SearchIndexOperations {
 	 * @param indexDefinition must not be {@literal null}.
 	 * @return the index name.
 	 */
-	String ensureIndex(SearchIndexDefinition indexDefinition);
+	// TODO: keep or just go with createIndex?
+	default String ensureIndex(SearchIndexDefinition indexDefinition) {
+		return createIndex(indexDefinition);
+	}
+
+	/**
+	 * Create the index for the given {@link SearchIndexDefinition} in the collection indicated by the entity class.
+	 *
+	 * @param indexDefinition must not be {@literal null}.
+	 * @return the index name.
+	 */
+	String createIndex(SearchIndexDefinition indexDefinition);
 
 	/**
 	 * Alters the search index matching the index {@link SearchIndexDefinition#getName() name}.
@@ -42,6 +53,7 @@ public interface SearchIndexOperations {
 	 *
 	 * @param indexDefinition the index definition.
 	 */
+	// TODO: keep or remove since it does not work reliably?
 	void updateIndex(SearchIndexDefinition indexDefinition);
 
 	/**

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

@@ -24,7 +24,7 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * MongoDB-specific extension to {@link Vector} based on Mongo's {@link Binary}. Note that only float32 and int8
+ * MongoDB-specific extension to {@link Vector} based on Mongo's {@link BinaryVector}. Note that only float32 and int8
  * variants can be represented as floating-point numbers. int1 returns an all-zero array for {@link #toFloatArray()} and
  * {@link #toDoubleArray()}.
  *

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

@@ -33,6 +33,7 @@
 ** xref:mongodb/change-streams.adoc[]
 ** xref:mongodb/tailable-cursors.adoc[]
 ** xref:mongodb/sharding.adoc[]
+** xref:mongodb/mongo-search-indexes.adoc[]
 ** xref:mongodb/mongo-encryption.adoc[]
 
 // Repository

src/main/antora/modules/ROOT/pages/mongodb/mongo-search-indexes.adoc

@@ -0,0 +1,124 @@
+[[mongo.search]]
+= MongoDB Search
+
+MongoDB enables users to do keyword or lexical search as well as vector search data using dedicated search indexes.
+
+[[mongo.search.vector]]
+== Vector Search
+
+MongoDB Vector Search uses the `$vectorSearch` aggregation stage to run queries against specialized indexes.
+Please refer to the MongoDB documentation to learn more about requirements and restrictions of `vectorSearch` indexes.
+
+[[mongo.search.vector.index]]
+=== Managing Vector Indexes
+
+`SearchIndexOperationsProvider` implemented by `MongoTemplate` are the entrypoint to `SearchIndexOperations` offering various methods for managing vector indexes.
+
+The following snippet shows how to create a vector index for a collection
+
+.Create a Vector Index
+[tabs]
+======
+Java::
++
+====
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+----
+VectorIndex index = new VectorIndex("vector_index")
+  .addVector("plotEmbedding"), vector -> vector.dimensions(1536).similarity(COSINE)) <1>
+  .addFilter("year"); <2>
+
+mongoTemplate.searchIndexOps(Movie.class) <3>
+  .createIndex(index);
+----
+<1> A vector index may cover multiple vector embeddings that can be added via the `addVector` method.
+<2> Vector indexes can contain additional fields to narrow down search results when running queries.
+<3> Obtain `SearchIndexOperations` bound to the `Movie` type which is used for field name mapping.
+====
+
+Mongo Shell::
++
+====
+[source,console,indent=0,subs="verbatim,quotes",role="secondary"]
+----
+db.movie.createSearchIndex("movie", "vector_index",
+  {
+    "fields": [
+      {
+        "type": "vector",
+        "numDimensions": 1536,
+        "path": "plot_embedding", <1>
+        "similarity": "cosine"
+      },
+      {
+        "type": "filter",
+        "path": "year"
+      }
+    ]
+  }
+)
+----
+<1> Field name `plotEmbedding` got mapped to `plot_embedding` considering a `@Field(name = "...")` annotation.
+====
+======
+
+Once created, vector indexes are not immediately ready to use although the `exists` check returns `true`.
+The actual status of a search index can be obtained via `SearchIndexOperations#status(...)`.
+The `READY` state indicates the index is ready to accept queries.
+
+[[mongo.search.vector.query]]
+=== Querying Vector Indexes
+
+Vector indexes can be queried by issuing an aggregation using a `VectorSearchOperation` via `MongoOperations` as shown in the following example
+
+.Query a Vector Index
+[tabs]
+======
+Java::
++
+====
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+----
+VectorSearchOperation search = VectorSearchOperation.search("vector_index") <1>
+  .path("plotEmbedding") <2>
+  .vector( ... )
+  .numCandidates(150)
+  .limit(10)
+  .quantization(SCALAR)
+  .withSearchScore("score"); <3>
+
+AggregationResults<MovieWithSearchScore> results = mongoTemplate
+  .aggregate(newAggregation(Movie.class, search), MovieWithSearchScore.class);
+----
+<1> Provide the name of the vector index to query since a collection may hold multiple ones.
+<2> The name of the path used for comparison.
+<3> Optionally add the search score with given name to the result document.
+====
+
+Mongo Shell::
++
+====
+[source,console,indent=0,subs="verbatim,quotes",role="secondary"]
+----
+db.embedded_movies.aggregate([
+  {
+    "$vectorSearch": {
+      "index": "vector_index",
+      "path": "plot_embedding", <1>
+      "queryVector": [ ... ],
+      "numCandidates": 150,
+      "limit": 10,
+      "quantization": "scalar"
+    }
+  },
+  {
+    "$addFields": {
+      "score": { $meta: "vectorSearchScore" }
+    }
+  }
+])
+----
+<1> Field name `plotEmbedding` got mapped to `plot_embedding` considering a `@Field(name = "...")` annotation.
+====
+======
+