DOCSP-46446: v5.3 release

config/redirects

@@ -1,6 +1,6 @@
 define: prefix docs/drivers/kotlin/coroutine
 define: base https://www.mongodb.com/${prefix}
-define: versions v4.10 v4.11 v5.0 v5.1 v5.2 master
+define: versions v4.10 v4.11 v5.0 v5.1 v5.2 v5.3 master
 
 raw: ${prefix}/ -> ${base}/current/
 

examples/gradle.properties

@@ -1,2 +1,2 @@
 kotlin.code.style=official
-kotlin_mongodb_version=5.2.0
+kotlin_mongodb_version=5.3.0

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))

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)
     }

snooty.toml

@@ -12,15 +12,16 @@ toc_landing_pages = [
     "/fundamentals/builders",
     "/usage-examples",
     "/api-documentation",
+    "/fundamentals/builders/aggregates",
 ]
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
 [constants]
 driver = "kotlin"
 driver-short = "Kotlin driver"
 driver-long = "MongoDB Kotlin Driver"
-version = "5.2"
-full-version = "{+version+}.1"
+version = "5.3"
+full-version = "{+version+}.0"
 language = "Kotlin"
 mdb-server = "MongoDB server"
 kotlin-docs = "https://kotlinlang.org"
@@ -34,5 +35,5 @@ snappyVersion = "org.xerial.snappy:snappy-java:1.1.8.4"
 zstdVersion = "com.github.luben:zstd-jni:1.5.5-2"
 logbackVersion = "1.2.11"
 log4j2Version = "2.17.1"
-serializationVersion = "1.5.1"
+serializationVersion = "1.6.0"
 kotlinx-dt-version = "0.6.1"

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))

source/examples/generated/ChangeTest.snippet.replace-one-options.kt

@@ -0,0 +1 @@
+val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))

source/examples/generated/ChangeTest.snippet.update-one-options.kt

@@ -0,0 +1 @@
+val opts = UpdateOptions().sort(Sorts.ascending(PaintOrder::color.name))

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>

source/fundamentals/builders/aggregates.txt

@@ -17,6 +17,10 @@ Aggregates Builders
    :depth: 2
    :class: singlecol
 
+.. toctree::
+
+   Atlas Vector Search </fundamentals/builders/vector-search>
+
 Overview
 --------
 
@@ -904,46 +908,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)>`__.

source/fundamentals/builders/updates.txt

@@ -1,3 +1,6 @@
+.. _updates-builders:
+.. _kotlin-updates-builders:
+
 ================
 Updates Builders
 ================
@@ -15,8 +18,6 @@ Updates Builders
    :depth: 2
    :class: singlecol
 
-.. _updates-builders:
-
 Overview
 --------
 

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>`__

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

source/fundamentals/crud/write-operations/bulk.txt

@@ -47,7 +47,7 @@ This data is modeled with the following Kotlin data class:
    :language: kotlin
 
 For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
+see the following API documentation:
 
 - `bulkWrite() <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/bulk-write.html>`__
 - `WriteModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/WriteModel.html>`__
@@ -96,7 +96,7 @@ describing people:
    ``_id`` of ``3``, see the :ref:`Order of Execution <orderOfExecution>` section.
 
 For more information about the methods and classes mentioned in this section,
-see the `InsertOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/InsertOneModel.html>`__ API Documentation. 
+see the `InsertOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/InsertOneModel.html>`__ API documentation. 
 
 Replace Operation
 ~~~~~~~~~~~~~~~~~
@@ -122,10 +122,20 @@ contains the additional ``location`` field:
 .. literalinclude:: /examples/generated/BulkTest.snippet.replace-one.kt
    :language: kotlin
 
+If multiple documents match the query filter specified in
+the ``ReplaceOneModel`` instance, the operation replaces the first
+result. You can specify a sort in a ``ReplaceOptions`` instance to apply
+an order to matched documents before the driver performs the replace
+operation, as shown in the following code:
+
+.. literalinclude:: /examples/generated/ChangeTest.snippet.replace-one-options.kt
+   :language: kotlin
+
 For more information about the methods and classes mentioned in this section,
 see the following resources:
 
-- `ReplaceOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOneModel.html>`__ API Documentation
+- `ReplaceOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOneModel.html>`__ API documentation
+- `ReplaceOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__ API documentation
 - :manual:`Unique indexes </core/index-unique/>` Server Manual Explanation
 
 Update Operation
@@ -155,11 +165,21 @@ field by ``1`` in a document where the ``_id`` is ``2``:
 .. literalinclude:: /examples/generated/BulkTest.snippet.update-one.kt
    :language: java
 
+If multiple documents match the query filter specified in
+the ``UpdateOneModel`` instance, the operation updates the first
+result. You can specify a sort in an ``UpdateOptions`` instance to apply
+an order to matched documents before the driver performs the update
+operation, as shown in the following code:
+
+.. literalinclude:: /examples/generated/ChangeTest.snippet.update-one-options.kt
+   :language: kotlin
+
 For more information about the methods and classes mentioned in this section,
 see the following resources:
 
-- `UpdateOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOneModel.html>`__ API Documentation
-- `UpdateManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateManyModel.html>`__ API Documentation
+- `UpdateOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOneModel.html>`__ API documentation
+- `UpdateManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateManyModel.html>`__ API documentation
+- `UpdateOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__ API documentation
 - :manual:`unique indexes </core/index-unique/>` Server Manual Explanation
 
 Delete Operation
@@ -190,7 +210,7 @@ documents where the ``age`` value is less than ``30``:
    :language: kotlin
 
 For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
+see the following API documentation:
 
 - `DeleteOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/DeleteOneModel.html>`__
 - `DeleteManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/DeleteManyModel.html>`__
@@ -271,7 +291,7 @@ of execution:
       { "_id": 6, "name": "Zaynab Omar", "age": 37 }
 
 For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
+see the following API documentation:
 
 - `BulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html>`__
 - `ordered() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html#ordered(boolean)>`__