DOCSP-42607: v5.2 changes (mongodb#48)

* DOCSP-42607: v5.2 changes

* NR PR fixes 1

* indentation fix

Author: rustagir

.github/workflows/check-autobuilder.yml

@@ -34,3 +34,4 @@ java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
 core-api = "{+java-api+}/apidocs/mongodb-driver-core"
 kotlin-docs = "https://kotlinlang.org"
 serialization-version = "1.5.1"
+kotlinx-dt-version = "0.6.1"

snooty.toml

@@ -297,4 +297,98 @@ deserializes them accordingly.
 
       Retrieving as Document type
       Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}}
-      Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}
+      Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}
+
+.. _kotlin-sync-datetime-serialization:
+
+Serialize Dates and Times
+-------------------------
+
+In this section, you can learn about using {+language+} serialization to
+work with date and time types.
+
+kotlinx-datetime Library
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``kotlinx-datetime`` is a {+language+} library that offers
+a high level of control over how your date and time values
+are serialized. To use the library, add the ``kotlinx-datetime``
+dependency to your project's dependency list.
+
+Select from the following tabs to see how to add the ``kotlinx-datetime``
+dependency to your project by using the :guilabel:`Gradle` and
+:guilabel:`Maven` package managers:
+
+.. tabs::
+
+   .. tab::
+      :tabid: Gradle
+
+      .. code-block:: kotlin
+         :caption: build.gradle.kts
+
+         implementation("org.jetbrains.kotlinx:kotlinx-datetime:{+kotlinx-dt-version+}")
+
+   .. tab::
+      :tabid: Maven
+
+      .. code-block:: kotlin
+         :caption: pom.xml
+
+         <dependency>
+             <groupId>org.jetbrains.kotlinx</groupId>
+             <artifactId>kotlinx-datetime-jvm</artifactId>
+             <version>{+kotlinx-dt-version+}</version>
+         </dependency>
+
+To learn more about this library, see the :github:`kotlinx-datetime repository
+</Kotlin/kotlinx-datetime>` on GitHub.
+
+Example Data Class with Dates and Times
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After you add the library dependency, you can implement serializers from
+the ``kotlinx-datetime`` library that map your data class field values
+to the expected types in BSON.
+
+In this example, the driver serializes the fields of
+the ``Appointment`` data class with the following behavior:
+
+- ``name``: The driver serializes the value as a string.
+
+- ``date``:  The driver uses the ``kotlinx-datetime`` serializer
+  because the field has the ``@Contextual`` annotation. ``LocalDate``
+  values are serialized as BSON dates.
+
+- ``time``: The driver serializes the value as a string because it does
+  not have the ``@Contextual`` annotation. This is the default
+  serialization behavior for ``LocalTime`` values.
+
+.. literalinclude:: /includes/data-formats/serialization.kt
+   :language: kotlin
+   :start-after: start-datetime-data-class
+   :end-before: end-datetime-data-class
+   :dedent:
+
+The following example inserts an instance of the ``Appointment`` data
+class into the ``appointments`` collection:
+
+.. literalinclude:: /includes/data-formats/serialization.kt
+   :language: kotlin
+   :start-after: start-datetime-insertone
+   :end-before: end-datetime-insertone
+   :dedent:
+
+In MongoDB, the ``LocalDate`` value is stored as a BSON date, and the
+``time`` field is stored as a string by default serialization:
+
+.. code-block:: json
+
+   {
+     "_id": ...,
+     "name": "Daria Smith",
+     "date": {
+       "$date": "2024-10-15T00:00:00.000Z"
+     },
+     "time": "11:30",
+   }

source/data-formats/serialization.txt

@@ -74,6 +74,14 @@ data class Teacher(
 ) : Person
 // end-poly-classes
 
+// start-datetime-data-class
+@Serializable
+data class Appointment(
+    val name: String,
+    @Contextual val date: LocalDate,
+    val time: LocalTime,
+)
+// end-datetime-data-class
 
 fun main() {
 
@@ -126,5 +134,17 @@ fun main() {
     }
     // end-poly-operations
 
+    // start-datetime-insertone
+    val collection = database.getCollection<Appointment>("appointments")
+
+    val apptDoc = Appointment(
+        "Daria Smith",
+        LocalDate(2024, 10, 15),
+        LocalTime(hour = 11, minute = 30)
+    )
+
+    collection.insertOne(apptDoc)
+    // end-datetime-insertone
+
 }
 

source/includes/data-formats/serialization.kt

@@ -74,13 +74,35 @@ fun main() {
 
     // start-create-search-index
     val index = Document("mappings", Document("dynamic", true))
-    collection.createSearchIndex("<index name>", index)
+    collection.createSearchIndex("mySearchIdx", index)
     // end-create-search-index
 
     // start-create-search-indexes
-    val indexOne = SearchIndexModel("<first index name>", Document("mappings", Document("dynamic", true)))
-    val indexTwo = SearchIndexModel("<second index name>", Document("mappings", Document("dynamic", true)))
-    collection.createSearchIndexes(listOf(indexOne, indexTwo))
+    val searchIdxMdl = SearchIndexModel(
+        "searchIdx",
+        Document("analyzer", "lucene.standard").append(
+            "mappings", Document("dynamic", true)
+        ),
+        SearchIndexType.search()
+    )
+    
+    val vectorSearchIdxMdl = SearchIndexModel(
+        "vsIdx",
+        Document(
+            "fields",
+            listOf(
+                Document("type", "vector")
+                    .append("path", "embeddings")
+                    .append("numDimensions", 1536)
+                    .append("similarity", "dotProduct")
+            )
+        ),
+        SearchIndexType.vectorSearch()
+    )
+    
+    collection.createSearchIndexes(
+        listOf(searchIdxMdl, vectorSearchIdxMdl)
+    )
     // end-create-search-indexes
 
     // start-list-search-indexes

source/includes/indexes/indexes.kt

@@ -1,8 +1,9 @@
 .. _kotlin-sync-atlas-search-index:
+.. _kotlin-sync-search-avs-indexes:
 
-====================
-Atlas Search Indexes
-====================
+======================================
+Atlas Search and Vector Search Indexes
+======================================
 
 .. contents:: On this page
    :local:
@@ -20,12 +21,23 @@ Atlas Search Indexes
 Overview
 --------
 
-:atlas:`Atlas Search </atlas-search>` enables you to perform full-text searches on
+You can programmatically manage your :atlas:`Atlas Search
+</atlas-search>` and :atlas:`Atlas Vector Search
+</atlas-vector-search/vector-search-overview/>` indexes by using the
+{+driver-short+}.
+
+Atlas Search enables you to perform full-text searches on
 collections hosted on MongoDB Atlas. Atlas Search indexes specify the behavior of
 the search and which fields to index.
 
-You can call the following methods on a collection to manage your Atlas Search
-indexes:
+Atlas Vector Search enables you to perform semantic searches on vector
+embeddings stored in MongoDB Atlas. Vector Search indexes define the
+indexes for the vector embeddings that you want to query and the boolean,
+date, objectId, numeric, string, or UUID values that you want to use to
+pre-filter your data.
+
+You can call the following methods on a collection to manage your Atlas
+Search and Vector Search indexes:
 
 - ``createSearchIndex()``
 - ``createSearchIndexes()``
@@ -35,9 +47,11 @@ indexes:
 
 .. note::
 
-   The Atlas Search index management methods run asynchronously and might return before
-   confirming that they ran successfully. To determine the current status of the indexes,
-   call the ``listSearchIndexes()`` method.
+   The Atlas Search and Vector Search index management methods run
+   asynchronously and might return before confirming that they ran
+   successfully. To determine the current status of the indexes, call
+   the ``listSearchIndexes()`` method or view the indexes list in the
+   :atlas:`Atlas UI </atlas-ui/indexes/>`.
 
 The following sections provide code examples that demonstrate how to use
 each of the preceding methods.
@@ -50,13 +64,7 @@ Create a Search Index
 You can use the `createSearchIndex()
 <{+api+}/com.mongodb.kotlin.client/-mongo-collection/create-search-index.html>`__
 and the `createSearchIndexes() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/create-search-indexes.html>`__
-methods to create one or more Atlas Search indexes.
-
-You can also use these methods to create Atlas Vector Search Indexes.
-Atlas Vector Search enables you to perform semantic searches on vector
-embeddings stored in MongoDB Atlas. To learn more about this feature,
-see the :atlas:`Atlas Vector Search Overview
-</atlas-vector-search/vector-search-overview/>`.
+methods to create one or more Atlas Search or Vector Search indexes.
 
 The following code example shows how to create an Atlas Search index:
 
@@ -66,7 +74,8 @@ The following code example shows how to create an Atlas Search index:
    :end-before: end-create-search-index
    :dedent:
 
-The following code example shows how to create multiple indexes:
+The following code example shows how to create Atlas Search and
+Vector Search indexes in one call:
 
 .. literalinclude:: /includes/indexes/indexes.kt
    :language: kotlin
@@ -76,7 +85,7 @@ The following code example shows how to create multiple indexes:
 
 To learn more about the syntax used to define Atlas Search indexes, see the
 :atlas:`Review Atlas Search Index Syntax </atlas-search/index-definitions>` guide
-in the Atlas manual.
+in the Atlas documentation.
 
 .. _kotlin-sync-atlas-search-index-list:
 

source/indexes/atlas-search-index.txt

@@ -12,12 +12,39 @@ What's New
 
 Learn what's new in:
 
+* :ref:`Version 5.2 <kotlin-sync-version-5.2>`
 * :ref:`Version 5.1.3 <kotlin-sync-version-5.1.3>`
 * :ref:`Version 5.1.2 <kotlin-sync-version-5.1.2>`
 * :ref:`Version 5.1.1 <kotlin-sync-version-5.1.1>`
 * :ref:`Version 5.1 <kotlin-sync-version-5.1>`
 * :ref:`Version 5.0 <kotlin-sync-version-5.0>`
 
+.. _kotlin-sync-version-5.2:
+
+What's New in 5.2
+-----------------
+
+The 5.2 driver release includes the following new features,
+improvements, and fixes:
+
+.. sharedinclude:: dbx/jvm/v5.2-wn-items.rst
+
+   .. replacement:: avs-index-link
+
+      the :ref:`kotlin-sync-search-avs-indexes` guide
+
+- Adds support for serializers from the ``kotlinx-datetime`` library
+  that let you map {+language+} date and time types to BSON as the
+  expected types instead of as strings. To learn more, see the
+  :ref:`kotlin-sync-datetime-serialization` section of the {+language+}
+  Serialization guide.
+
+- Supports serialization of `JsonElement
+  <{+kotlin-docs+}/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/>`__
+  values. To work with the ``JsonElement`` type, you must add the
+  ``kotlinx-serialization-json`` library as a dependency in your
+  application.
+
 .. _kotlin-sync-version-5.1.3:
 
 What's New in 5.1.3