DOCSP-33428: vectorsearch builder (#143)

* DOCSP-33428: vectorsearch builder

* use other data class

* add taxonomy + small fixes

* JS PR fixes - remove projection stage

* fixes

* fixes

(cherry picked from commit 65f210d)

Author: rustagir

examples/build.gradle.kts

@@ -18,7 +18,7 @@ repositories {
 dependencies {
     implementation("org.mongodb:mongodb-driver-kotlin-coroutine:$kotlin_mongodb_version")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.1")
-    testImplementation(kotlin("test"))
+    testImplementation("org.jetbrains.kotlin:kotlin-test:1.8.10")
     implementation("org.slf4j:slf4j-api:2.0.5")
     implementation("ch.qos.logback:logback-classic:1.4.7")
     implementation("io.github.cdimascio:dotenv-kotlin:6.4.1")

examples/gradle.properties

@@ -1,2 +1,2 @@
 kotlin.code.style=official
-kotlin_mongodb_version=4.10.0
+kotlin_mongodb_version=4.11.0

examples/src/test/kotlin/AggregatesBuilderTest.kt

@@ -28,6 +28,7 @@ import com.mongodb.client.model.geojson.Position
 import com.mongodb.client.model.search.SearchOperator
 import com.mongodb.client.model.search.SearchOptions
 import com.mongodb.client.model.search.SearchPath
+import com.mongodb.client.model.search.VectorSearchOptions.vectorSearchOptions
 import com.mongodb.kotlin.client.coroutine.MongoClient
 import config.getConfig
 import kotlinx.coroutines.flow.firstOrNull
@@ -80,6 +81,15 @@ class AggregatesBuilderTest {
     )
     // :snippet-end:
 
+    // :snippet-start: vector-search-data-class
+    data class MovieAlt(
+        val title: String,
+        val year: Int,
+        val plot: String,
+        val plotEmbedding: List<Double>
+    )
+    // :snippet-end:
+
     companion object {
         val config = getConfig()
         private val client = MongoClient.create(config.connectionUri)
@@ -674,7 +684,15 @@ class AggregatesBuilderTest {
             // :snippet-end:
             Aggregates.sort(Sorts.descending(Results::count.name, "_id"))))
         val results = resultsFlow.toList()
-        val actual = listOf(Results("Drama", 8), Results("Crime", 3), Results("Action", 2), Results("Thriller", 1), Results("Sci-Fi", 1), Results("Romance", 1), Results("Mystery", 1),)
+        val actual = listOf(
+            Results("Drama", 8),
+            Results("Crime", 3),
+            Results("Action", 2),
+            Results("Thriller", 1),
+            Results("Sci-Fi", 1),
+            Results("Romance", 1),
+            Results("Mystery", 1)
+        )
         assertEquals(results, actual)
     }
 
@@ -951,4 +969,27 @@ class AggregatesBuilderTest {
         assertEquals(1, resultsFlow.toList().size)
         assertEquals(1, results.first().get("count", Document::class.java).get("lowerBound", java.lang.Long::class.java)?.toInt())
     }
+
+    /* NOTE: Test is not run by default. Vector search requires the creation of a vector search index on the collection before running.
+    */
+    @Ignore
+    fun vectorSearchTest() = runBlocking {
+        val resultsFlow = movieCollection.aggregate<Document>(
+            listOf(
+                // :snippet-start: vector-search
+                Aggregates.vectorSearch(
+                    SearchPath.fieldPath(MovieAlt::plotEmbedding.name),
+                    listOf(-0.0072121937, -0.030757688, -0.012945653),
+                    "mflix_movies_embedding_index",
+                    2.toLong(),
+                    1.toLong(),
+                    vectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))
+                )
+                // :snippet-end:
+            )
+        )
+        val results = resultsFlow.toList()
+        assertEquals(1, resultsFlow.toList().size)
+        assertEquals(1, results.first().get("count", Document::class.java).get("lowerBound", java.lang.Long::class.java)?.toInt())
+    }
 }

source/examples/generated/AggregatesBuilderTest.snippet.vector-search-data-class.kt

@@ -0,0 +1,6 @@
+data class MovieAlt(
+    val title: String,
+    val year: Int,
+    val plot: String,
+    val plotEmbedding: List<Double>
+)

source/examples/generated/AggregatesBuilderTest.snippet.vector-search.kt

@@ -0,0 +1,8 @@
+Aggregates.vectorSearch(
+    SearchPath.fieldPath(MovieAlt::plotEmbedding.name),
+    listOf(-0.0072121937, -0.030757688, -0.012945653),
+    "mflix_movies_embedding_index",
+    2.toLong(),
+    1.toLong(),
+    vectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))
+)

source/fundamentals/builders/aggregates.txt

@@ -4,6 +4,13 @@
 Aggregates Builders
 ===================
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, data insights, compute, atlas
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -668,7 +675,7 @@ The following examples use data modeled with the following Kotlin data class:
 .. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.bucket-data-class.kt
    :language: kotlin
 
-This exampled creates a pipeline stage that will attempt to create and evenly
+This example creates a pipeline stage that will attempt to create and evenly
 distribute documents into 5 buckets using the value of their ``price`` field:
 
 .. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.bucket-auto.kt
@@ -898,3 +905,46 @@ aggregation stage:
 Learn more about this helper from the
 `searchMeta() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__.
 
+.. _kotlin-atlas-vector-search:
+
+Atlas Vector Search
+-------------------
+
+.. important::
+
+   To learn about which versions of MongoDB Atlas support this feature, see
+   :atlas:`Limitations </atlas-vector-search/vector-search-stage/#limitations>`
+   in the Atlas documentation.
+
+Use the ``vectorSearch()`` method to create a :atlas:`$vectorSearch </atlas-vector-search/vector-search-stage/>`
+pipeline stage that specifies a **semantic search**. A semantic search is
+a type of search that locates pieces of information that are similar in meaning.
+
+To use this feature when performing an aggregation on a collection, you
+must create a vector search index and index your vector embeddings. To
+learn how to set up search indexes in MongoDB Atlas, see :atlas:`How to
+Index Vector Embeddings for Vector Search
+</atlas-search/field-types/knn-vector/>` in the Atlas documentation.
+
+The example in this section uses data modeled with the following Kotlin data class:
+
+.. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.vector-search-data-class.kt
+   :language: kotlin
+
+This example shows how to build an aggregation pipeline that uses the
+``vectorSearch()`` method to perform a vector search with the following
+specifications:
+
+- Searches ``plotEmbedding`` field values by using vector embeddings of a
+  string value
+- Uses the ``mflix_movies_embedding_index`` vector search index
+- Considers up to 2 nearest neighbors
+- Returns 1 document
+- Filters for documents in which the ``year`` value is at least ``2016``
+
+.. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.vector-search.kt
+   :language: kotlin
+
+To learn more about this helper, see the
+`vectorSearch() API documentation
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#vectorSearch(com.mongodb.client.model.search.FieldSearchPath,java.lang.Iterable,java.lang.String,long,long)>`__.