Merge branch 'master' into docsp-43565-vector-index-correction

cbullinger · web-flow · commit ec6e87ed88d7 · 2024-10-07T09:08:52.000-04:00
diff --git a/.github/workflows/check-autobuilder.yml b/.github/workflows/check-autobuilder.yml
diff --git a/config/redirects b/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 master
+define: versions v4.10 v4.11 v5.0 v5.1 v5.2 master
 
 raw: ${prefix}/ -> ${base}/current/
 
diff --git a/examples/build.gradle.kts b/examples/build.gradle.kts
@@ -28,7 +28,7 @@ dependencies {
     implementation("com.github.luben:zstd-jni:1.5.5-4")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.5.0")
-    implementation("org.mongodb:bson-kotlinx:5.1.2")
+    implementation("org.mongodb:bson-kotlinx:$kotlin_mongodb_version")
     implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.0")
 }
 
diff --git a/examples/gradle.properties b/examples/gradle.properties
@@ -1,2 +1,2 @@
 kotlin.code.style=official
-kotlin_mongodb_version=5.1.2
+kotlin_mongodb_version=5.2.0
diff --git a/examples/src/test/kotlin/AggregatesBuilderTest.kt b/examples/src/test/kotlin/AggregatesBuilderTest.kt
@@ -28,7 +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.client.model.search.VectorSearchOptions.exactVectorSearchOptions
 import com.mongodb.kotlin.client.coroutine.MongoClient
 import config.getConfig
 import kotlinx.coroutines.flow.firstOrNull
@@ -981,13 +981,13 @@ class AggregatesBuilderTest {
                     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))
+                    exactVectorSearchOptions().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())
diff --git a/examples/src/test/kotlin/KotlinXSerializationTest.kt b/examples/src/test/kotlin/KotlinXSerializationTest.kt
@@ -204,7 +204,6 @@ internal class KotlinXSerializationTest {
         val department: String,
     ) : Person
     // :snippet-end:
-
     @Test
     fun polymorphicSerializationTest() = runBlocking {
 
@@ -242,5 +241,34 @@ internal class KotlinXSerializationTest {
         collection.drop()
     }
 
+    // :snippet-start: datetime-data-class
+    @Serializable
+    data class Appointment(
+        val name: String,
+        @Contextual val date: LocalDate,
+        val time: LocalTime,
+    )
+    // :snippet-end:
+
+    @Test
+    fun dateTimeSerializationTest() = runBlocking {
+
+        // :snippet-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)
+        // :snippet-end:
+
+        assertEquals(apptDoc.name, "Daria Smith")
+
+        collection.drop()
+    }
+
 }
 
diff --git a/examples/src/test/kotlin/SearchIndexesTest.kt b/examples/src/test/kotlin/SearchIndexesTest.kt
@@ -1,5 +1,6 @@
 
 import com.mongodb.client.model.SearchIndexModel
+import com.mongodb.client.model.SearchIndexType
 import com.mongodb.kotlin.client.coroutine.MongoClient
 import config.getConfig
 import kotlinx.coroutines.flow.toList
diff --git a/snooty.toml b/snooty.toml
@@ -19,19 +19,20 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 driver = "kotlin"
 driver-short = "Kotlin driver"
 driver-long = "MongoDB Kotlin Driver"
-version = "5.1"
-full-version = "{+version+}.2"
+version = "5.2"
+full-version = "{+version+}.0"
 language = "Kotlin"
 mdb-server = "MongoDB server"
 kotlin-docs = "https://kotlinlang.org"
 
 package-name-org = "mongodb-org"
 api = "https://mongodb.github.io/mongo-java-driver/{+version+}"
 stable-api = "Stable API"
-mongocrypt-version = "1.7.3"
+mongocrypt-version = "{+full-version+}"
 nettyVersion = "io.netty:netty-all:4.1.79.Final"
 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"
+kotlinx-dt-version = "0.6.1"
diff --git a/source/examples/generated/AggregatesBuilderTest.snippet.vector-search.kt b/source/examples/generated/AggregatesBuilderTest.snippet.vector-search.kt
@@ -2,7 +2,6 @@ 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))
+    exactVectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))
 )
diff --git a/source/examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt b/source/examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt
@@ -0,0 +1,6 @@
+@Serializable
+data class Appointment(
+    val name: String,
+    @Contextual val date: LocalDate,
+    val time: LocalTime,
+)
diff --git a/source/examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt b/source/examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt
@@ -0,0 +1,9 @@
+val collection = database.getCollection<Appointment>("appointments")
+
+val apptDoc = Appointment(
+    "Daria Smith",
+    LocalDate(2024, 10, 15),
+    LocalTime(hour = 11, minute = 30)
+)
+
+collection.insertOne(apptDoc)
diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt
@@ -932,13 +932,12 @@ The example in this section uses data modeled with the following Kotlin data cla
    :language: kotlin
 
 This example shows how to build an aggregation pipeline that uses the
-``vectorSearch()`` method to perform a vector search with the following
+``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
-- Considers up to 2 nearest neighbors
 - Returns 1 document
 - Filters for documents in which the ``year`` value is at least ``2016``
 
@@ -947,4 +946,4 @@ specifications:
 
 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)>`__.
+<{+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/data-formats/serialization.txt b/source/fundamentals/data-formats/serialization.txt
@@ -301,3 +301,91 @@ 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}}
+
+.. _kotlin-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:: /examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt
+    :language: kotlin
+
+The following example inserts an instance of the ``Appointment`` data
+class into the ``appointments`` collection:
+
+.. literalinclude:: /examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt
+    :language: kotlin
+
+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",
+   }
diff --git a/source/fundamentals/encrypt-fields.txt b/source/fundamentals/encrypt-fields.txt
@@ -1,3 +1,28 @@
 .. _kotlin-fle:
 
 .. sharedinclude:: dbx/encrypt-fields.rst
+
+   .. replacement:: driver-specific-content
+
+      .. important:: Compatible Encryption Library Version
+
+         The {+driver-short+} uses the `mongodb-crypt
+         <https://mvnrepository.com/artifact/org.mongodb/mongodb-crypt>`__
+         encryption library for in-use encryption. This driver version
+         is compatible with ``mongodb-crypt`` v{+mongocrypt-version+}.
+
+         Select from the following :guilabel:`Maven` and
+         :guilabel:`Gradle` tabs to see how to add the ``mongodb-crypt``
+         dependency to your project by using the specified manager:
+         
+         .. tabs::
+         
+            .. tab:: Maven
+               :tabid: maven-dependency
+         
+               .. include:: /includes/fundamentals/code-snippets/crypt-maven-versioned.rst
+         
+            .. tab:: Gradle
+               :tabid: gradle-dependency
+         
+               .. include:: /includes/fundamentals/code-snippets/crypt-gradle-versioned.rst
diff --git a/source/fundamentals/indexes.txt b/source/fundamentals/indexes.txt
@@ -277,6 +277,11 @@ The following code example shows how to create an Atlas Search index:
 .. literalinclude:: /examples/generated/SearchIndexesTest.snippet.single-search-index-create.kt
    :language: kotlin
 
+To create multiple Search or Vector Search indexes, you must create a
+`SearchIndexModel
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/SearchIndexModel.html>`__
+instance for each index.
+
 The following code example shows how to create Search and
 Vector Search indexes in one call:
 
diff --git a/source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst b/source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst
@@ -0,0 +1,5 @@
+.. code-block:: groovy
+
+   dependencies {
+      implementation("org.mongodb:mongodb-crypt:{+mongocrypt-version+}")
+   }
diff --git a/source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst b/source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst
@@ -0,0 +1,9 @@
+.. code-block:: xml
+
+   <dependencies>
+       <dependency>
+           <groupId>org.mongodb</groupId>
+           <artifactId>mongodb-crypt</artifactId>
+           <version>{+mongocrypt-version+}</version>
+       </dependency>
+   </dependencies>
diff --git a/source/includes/language-compatibility-table-kotlin.rst b/source/includes/language-compatibility-table-kotlin.rst
@@ -7,14 +7,5 @@
    * - Kotlin Driver Version
      - Kotlin 1.8
 
-   * - 5.1
-     - ✓
-
-   * - 5.0
-     - ✓
-
-   * - 4.11
-     - ✓
-
-   * - 4.10
+   * - 4.10 to 5.2
      - ✓
diff --git a/source/includes/mongodb-compatibility-table-kotlin.rst b/source/includes/mongodb-compatibility-table-kotlin.rst
diff --git a/source/usage-examples/facets.toml b/source/usage-examples/facets.toml
diff --git a/source/whats-new.txt b/source/whats-new.txt

Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ dependencies {`
`28`	`28`	`implementation("com.github.luben:zstd-jni:1.5.5-4")`
`29`	`29`	`implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")`
`30`	`30`	`implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.5.0")`
`31`		`- implementation("org.mongodb:bson-kotlinx:5.1.2")`
	`31`	`+ implementation("org.mongodb:bson-kotlinx:$kotlin_mongodb_version")`
`32`	`32`	`implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.0")`
`33`	`33`	`}`
`34`	`34`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`kotlin.code.style=official`
`2`		`-kotlin_mongodb_version=5.1.2`
	`2`	`+kotlin_mongodb_version=5.2.0`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,6 @@ Aggregates.vectorSearch(`
`2`	`2`	`SearchPath.fieldPath(MovieAlt::plotEmbedding.name),`
`3`	`3`	`listOf(-0.0072121937, -0.030757688, -0.012945653),`
`4`	`4`	`"mflix_movies_embedding_index",`
`5`		`- 2.toLong(),`
`6`	`5`	`1.toLong(),`
`7`		`- vectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))`
	`6`	`+ exactVectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))`
`8`	`7`	`)`