DOCSP-46446: v5.3 release (#188)

* DOCSP-46446: v5.3 release

* fix examples for bulk

* small fix

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

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/BulkTest.snippet.replace-model-options.kt

@@ -0,0 +1 @@
+val opts = ReplaceOptions().sort(Sorts.ascending("_id"))

source/examples/generated/BulkTest.snippet.update-model-options.kt

@@ -0,0 +1 @@
+val opts = UpdateOptions().sort(Sorts.ascending("_id"))

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.txt

@@ -94,9 +94,19 @@ Using Builders
 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.

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