Merge branch 'master' into DOCSP-36218-filters-data-class

rustagir · web-flow · commit 7825e036ab33 · 2025-01-16T11:20:40.000-05:00
diff --git a/examples/src/test/kotlin/AggregatesBuilderTest.kt b/examples/src/test/kotlin/AggregatesBuilderTest.kt
@@ -34,6 +34,7 @@ import config.getConfig
 import kotlinx.coroutines.flow.firstOrNull
 import kotlinx.coroutines.flow.toList
 import kotlinx.coroutines.runBlocking
+import org.bson.BinaryVector
 import org.bson.Document
 import org.bson.codecs.pojo.annotations.BsonId
 import org.bson.types.ObjectId
@@ -970,7 +971,8 @@ class AggregatesBuilderTest {
         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.
+    /* 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 {
@@ -979,7 +981,7 @@ class AggregatesBuilderTest {
                 // :snippet-start: vector-search
                 Aggregates.vectorSearch(
                     SearchPath.fieldPath(MovieAlt::plotEmbedding.name),
-                    listOf(-0.0072121937, -0.030757688, -0.012945653),
+                    BinaryVector.floatVector(floatArrayOf(0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f)),
                     "mflix_movies_embedding_index",
                     1.toLong(),
                     exactVectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))
diff --git a/examples/src/test/kotlin/BulkTest.kt b/examples/src/test/kotlin/BulkTest.kt
@@ -6,7 +6,10 @@ import com.mongodb.client.model.DeleteOneModel
 import com.mongodb.client.model.Filters
 import com.mongodb.client.model.InsertOneModel
 import com.mongodb.client.model.ReplaceOneModel
+import com.mongodb.client.model.ReplaceOptions
+import com.mongodb.client.model.Sorts
 import com.mongodb.client.model.UpdateOneModel
+import com.mongodb.client.model.UpdateOptions
 import com.mongodb.client.model.Updates
 import com.mongodb.kotlin.client.coroutine.MongoClient
 import config.getConfig
@@ -95,6 +98,11 @@ internal class BulkTest {
         val insert = Person(1, "Celine Stork", location = "San Diego, CA")
         val doc = ReplaceOneModel(filter, insert)
         // :snippet-end:
+
+        // :snippet-start: replace-model-options
+        val opts = ReplaceOptions().sort(Sorts.ascending("_id"))
+        // :snippet-end:
+
         // Junit test for the above code
         val insertTest = collection.bulkWrite(listOf(doc))
         assertTrue(insertTest.wasAcknowledged())
@@ -107,6 +115,11 @@ internal class BulkTest {
         val update = Updates.inc(Person::age.name, 1)
         val doc = UpdateOneModel<Person>(filter, update)
         // :snippet-end:
+
+        // :snippet-start: update-model-options
+        val opts = UpdateOptions().sort(Sorts.ascending("_id"))
+        // :snippet-end:
+
         // Junit test for the above code
         val updateTest = collection.bulkWrite(listOf(doc))
         assertTrue(updateTest.wasAcknowledged())
diff --git a/examples/src/test/kotlin/ChangeTest.kt b/examples/src/test/kotlin/ChangeTest.kt
@@ -1,5 +1,8 @@
 
 import com.mongodb.client.model.Filters
+import com.mongodb.client.model.ReplaceOptions
+import com.mongodb.client.model.Sorts
+import com.mongodb.client.model.UpdateOptions
 import com.mongodb.client.model.Updates
 import com.mongodb.kotlin.client.coroutine.MongoClient
 import config.getConfig
@@ -63,6 +66,11 @@ internal class ChangeTest {
         println("Matched document count: $result.matchedCount")
         println("Modified document count: $result.modifiedCount")
         // :snippet-end:
+
+        // :snippet-start: update-one-options
+        val opts = UpdateOptions().sort(Sorts.ascending(PaintOrder::color.name))
+        // :snippet-end:
+
         // Junit test for the above code
         assertEquals(1, result.modifiedCount)
     }
@@ -90,6 +98,11 @@ internal class ChangeTest {
         println("Matched document count: $result.matchedCount")
         println("Modified document count: $result.modifiedCount")
         // :snippet-end:
+
+        // :snippet-start: replace-one-options
+        val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))
+        // :snippet-end:
+
         // Junit test for the above code
         assertEquals(1, result.modifiedCount)
     }
diff --git a/snooty.toml b/snooty.toml
@@ -12,6 +12,7 @@ toc_landing_pages = [
     "/fundamentals/builders",
     "/usage-examples",
     "/api-documentation",
+    "/fundamentals/builders/aggregates",
 ]
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
diff --git a/source/examples/generated/AggregatesBuilderTest.snippet.vector-search.kt b/source/examples/generated/AggregatesBuilderTest.snippet.vector-search.kt
@@ -1,6 +1,6 @@
 Aggregates.vectorSearch(
     SearchPath.fieldPath(MovieAlt::plotEmbedding.name),
-    listOf(-0.0072121937, -0.030757688, -0.012945653),
+    BinaryVector.floatVector(floatArrayOf(0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f)),
     "mflix_movies_embedding_index",
     1.toLong(),
     exactVectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))
diff --git a/source/examples/generated/BulkTest.snippet.replace-model-options.kt b/source/examples/generated/BulkTest.snippet.replace-model-options.kt
@@ -0,0 +1 @@
+val opts = ReplaceOptions().sort(Sorts.ascending("_id"))
diff --git a/source/examples/generated/BulkTest.snippet.update-model-options.kt b/source/examples/generated/BulkTest.snippet.update-model-options.kt
@@ -0,0 +1 @@
+val opts = UpdateOptions().sort(Sorts.ascending("_id"))
diff --git a/source/examples/generated/ChangeTest.snippet.replace-one-options.kt b/source/examples/generated/ChangeTest.snippet.replace-one-options.kt
@@ -0,0 +1 @@
+val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))
diff --git a/source/examples/generated/ChangeTest.snippet.update-one-options.kt b/source/examples/generated/ChangeTest.snippet.update-one-options.kt
@@ -0,0 +1 @@
+val opts = UpdateOptions().sort(Sorts.ascending(PaintOrder::color.name))
diff --git a/source/fundamentals.txt b/source/fundamentals.txt
@@ -14,7 +14,7 @@ Fundamentals
    Stable API </fundamentals/stable-api>
    Databases & Collections </fundamentals/databases-collections>
    Data Formats </fundamentals/data-formats>
-   CRUD Operations /fundamentals/crud
+   CRUD Operations </fundamentals/crud>
    Builders </fundamentals/builders>
    Aggregation </fundamentals/aggregation>
    Aggregation Expressions </fundamentals/aggregation-expression-operations>
diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt
@@ -108,11 +108,21 @@ builders in the {+driver-short+}:
 Available Builders
 ------------------
 
-- :ref:`Aggregates <aggregates-builders>` for building aggregation pipelines.
+- :ref:`Aggregates <aggregates-builders>` for building aggregation
+  pipelines.
+
+  - :ref:`kotlin-atlas-vector-search` for using the
+    ``Aggregates.vectorSearch()`` method to use the Atlas Vector
+    Search feature.
+
 - :ref:`Filters <filters-builders>` for building query filters.
+
 - :ref:`Indexes <indexes-builders>` for creating index keys.
-- :ref:`Projections <projections-builders>` for building projections. 
+
+- :ref:`Projections <projections-builders>` for building projections.
+
 - :ref:`Sorts <sorts-builders>` for building sort criteria.
+
 - :ref:`Updates <updates-builders>` for building updates.
 
 The :ref:`kotlin-builders-data-classes` guide provides examples on
diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt
@@ -17,6 +17,10 @@ Aggregates Builders
    :depth: 2
    :class: singlecol
 
+.. toctree::
+
+   Atlas Vector Search </fundamentals/builders/vector-search>
+
 Overview
 --------
 
@@ -906,46 +910,3 @@ 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 an exact 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
-- 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,com.mongodb.client.model.search.VectorSearchOptions)>`__.
diff --git a/source/fundamentals/builders/updates.txt b/source/fundamentals/builders/updates.txt
@@ -1,4 +1,5 @@
 .. _updates-builders:
+.. _kotlin-updates-builders:
 
 ================
 Updates Builders
diff --git a/source/fundamentals/builders/vector-search.txt b/source/fundamentals/builders/vector-search.txt
@@ -0,0 +1,102 @@
+.. _kotlin-atlas-vector-search:
+
+===================
+Atlas Vector Search
+===================
+
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: code example, semantic, nearest
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the :atlas:`Atlas Vector Search
+</atlas-vector-search/vector-search-overview/>` feature
+in the {+driver-short+}. The ``Aggregates``  builders class provides the
+the ``vectorSearch()`` helper method that you can use to
+create a :atlas:`$vectorSearch </atlas-vector-search/vector-search-stage/>`
+pipeline stage. This pipeline stage allows you to perform a **semantic
+search** on your documents. A semantic search is a type of search which
+locates information that is similar in meaning, but not necessarily
+identical, to your provided search term or phrase.
+
+.. important:: Feature Compatibility
+
+   To learn what versions of MongoDB Atlas support this feature, see
+   :atlas:`Limitations </atlas-vector-search/vector-search-stage/#limitations>`
+   in the MongoDB Atlas documentation.
+
+Perform a Vector Search
+-----------------------
+
+To use this feature, you must create a vector search index and index your
+vector embeddings. To learn about how to programmatically create a
+vector search index, see the :ref:`kotlin-search-indexes` section in the
+Indexes guide. To learn more about vector embeddings, see
+:atlas:`How to Index Vector Embeddings for Vector Search
+</atlas-search/field-types/knn-vector/>` in the Atlas documentation.
+
+After you create a vector search index on your vector embeddings, you
+can reference this index in your pipeline stage, as shown in the
+following section.
+
+Vector Search Example
+~~~~~~~~~~~~~~~~~~~~~
+
+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 an exact 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
+- 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
+
+.. tip:: Query Vector Type
+
+   The preceding example creates an instance of ``BinaryVector`` to
+   serve as the query vector, but you can also create a ``List`` of
+   ``Double`` instances. However, we recommend that you use the
+   ``BinaryVector`` type to improve storage efficiency.
+
+.. tip:: {+language+} Vector Search Examples
+    
+   Visit the :atlas:`Atlas documentation </atlas-vector-search/tutorials/>`
+   to find more tutorials on using the {+driver-short+} to perform Atlas
+   Vector Searches.
+
+API Documentation
+-----------------
+
+To learn more about the methods and types mentioned in this
+guide, see the following API documentation:
+
+- `Aggregates.vectorSearch()
+  <{+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,com.mongodb.client.model.search.VectorSearchOptions)>`__
+
+- `FieldSearchPath
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/FieldSearchPath.html>`__
+
+- `VectorSearchOptions
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/VectorSearchOptions.html>`__
+
+- `BinaryVector <{+api+}/apidocs/bson/org/bson/BinaryVector.html>`__
diff --git a/source/fundamentals/crud/write-operations.txt b/source/fundamentals/crud/write-operations.txt
@@ -1,13 +1,15 @@
+.. _kotlin-fundamentals-write-operations:
+
 ================
 Write Operations
 ================
 
-- :doc:`/fundamentals/crud/write-operations/insert`
-- :doc:`/fundamentals/crud/write-operations/delete`
-- :doc:`/fundamentals/crud/write-operations/modify`
-- :doc:`/fundamentals/crud/write-operations/embedded-arrays`
-- :doc:`/fundamentals/crud/write-operations/upsert`
-- :doc:`/fundamentals/crud/write-operations/bulk`
+- :ref:`kotlin-fundamentals-insert`
+- :ref:`kotlin-fundamentals-delete`
+- :ref:`kotlin-fundamentals-change-document`
+- :ref:`kotlin-fundamentals-update-array`
+- :ref:`kotlin-fundamentals-upsert`
+- :ref:`kotlin-fundamentals-bulkwrite`
 
 .. toctree::
    :caption: Write Operations
diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt
diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt
diff --git a/source/fundamentals/crud/write-operations/upsert.txt b/source/fundamentals/crud/write-operations/upsert.txt
diff --git a/source/fundamentals/indexes.txt b/source/fundamentals/indexes.txt
diff --git a/source/fundamentals/transactions.txt b/source/fundamentals/transactions.txt
diff --git a/source/whats-new.txt b/source/whats-new.txt

Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,7 @@ toc_landing_pages = [`
`12`	`12`	`"/fundamentals/builders",`
`13`	`13`	`"/usage-examples",`
`14`	`14`	`"/api-documentation",`
	`15`	`+ "/fundamentals/builders/aggregates",`
`15`	`16`	`]`
`16`	`17`	`sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"`
`17`	`18`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+val opts = ReplaceOptions().sort(Sorts.ascending("_id"))`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+val opts = UpdateOptions().sort(Sorts.ascending("_id"))`