diff --git a/config/redirects b/config/redirects index 60527205..9fa68e38 100644 --- 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 v5.2 master +define: versions v4.10 v4.11 v5.0 v5.1 v5.2 v5.3 master raw: ${prefix}/ -> ${base}/current/ diff --git a/examples/gradle.properties b/examples/gradle.properties index 28ecde2d..1998c01e 100644 --- a/examples/gradle.properties +++ b/examples/gradle.properties @@ -1,2 +1,2 @@ kotlin.code.style=official -kotlin_mongodb_version=5.2.0 +kotlin_mongodb_version=5.3.0 diff --git a/examples/src/test/kotlin/AggregatesBuilderTest.kt b/examples/src/test/kotlin/AggregatesBuilderTest.kt index 78a1af20..b07258b2 100644 --- 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 index 6211893a..32be938e 100644 --- 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(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 index 4853f486..ef032633 100644 --- 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 index 0abbf389..3a03a269 100644 --- 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/" @@ -19,8 +20,8 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" 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" diff --git a/source/examples/generated/AggregatesBuilderTest.snippet.vector-search.kt b/source/examples/generated/AggregatesBuilderTest.snippet.vector-search.kt index ee4648f2..c34bc7fe 100644 --- 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 new file mode 100644 index 00000000..c29244f3 --- /dev/null +++ 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 new file mode 100644 index 00000000..4d088548 --- /dev/null +++ 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 new file mode 100644 index 00000000..62007b4c --- /dev/null +++ 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 new file mode 100644 index 00000000..d79d89d6 --- /dev/null +++ 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 index 9ea37b6c..20d6cb62 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -14,7 +14,7 @@ Fundamentals Stable API Databases & Collections Data Formats - CRUD Operations /fundamentals/crud + CRUD Operations Builders Aggregation Aggregation Expressions diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 7bd54273..6568aa95 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -94,9 +94,19 @@ Using Builders Available Builders ------------------ -- :ref:`Aggregates ` for building aggregation pipelines. +- :ref:`Aggregates ` for building aggregation + pipelines. + + - :ref:`kotlin-atlas-vector-search` for using the + ``Aggregates.vectorSearch()`` method to use the Atlas Vector + Search feature. + - :ref:`Filters ` for building query filters. + - :ref:`Indexes ` for creating index keys. -- :ref:`Projections ` for building projections. + +- :ref:`Projections ` for building projections. + - :ref:`Sorts ` for building sort criteria. + - :ref:`Updates ` for building updates. diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt index 1ee12e0e..26af1efa 100644 --- 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 + 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 ` - in the Atlas documentation. - -Use the ``vectorSearch()`` method to create a :atlas:`$vectorSearch ` -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 -` 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 index 5f3e74e7..c23c1d12 100644 --- a/source/fundamentals/builders/updates.txt +++ b/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 -------- diff --git a/source/fundamentals/builders/vector-search.txt b/source/fundamentals/builders/vector-search.txt new file mode 100644 index 00000000..f5ff4c7e --- /dev/null +++ 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 +` feature +in the {+driver-short+}. The ``Aggregates`` builders class provides the +the ``vectorSearch()`` helper method that you can use to +create a :atlas:`$vectorSearch ` +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 ` + 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 +` 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 ` + 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 index 98581e1b..24b341f1 100644 --- 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 index 1a591bdb..7a5fed59 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/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 ` 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/BulkTest.snippet.replace-model-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 ` 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/BulkTest.snippet.update-model-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 ` 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)>`__ diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt index caabd57f..4af9cec1 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/fundamentals/crud/write-operations/modify.txt @@ -4,6 +4,13 @@ Modify Documents ================ +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: change data, code example, filter + .. contents:: On this page :local: :backlinks: none @@ -35,13 +42,12 @@ current inventory: { "_id": 4, "color": "green", "qty": 6 } { "_id": 5, "color": "pink", "qty": 0 } -This data is modeled with the following Kotlin data class: +This data is modeled with the following {+language+} data class: .. literalinclude:: /examples/generated/ChangeTest.snippet.data-model.kt :language: kotlin .. _update-operation: - .. _kotlin-fundamentals-update: Update @@ -61,9 +67,8 @@ You can call the ``updateOne()`` and ``updateMany()`` methods on a .. code-block:: kotlin - collection.updateOne(query, updateDocument) - - collection.updateMany(query, updateDocument) + collection.updateOne(, ) + collection.updateMany(, ) Update Operation Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -72,20 +77,28 @@ The ``updateOne()`` and ``updateMany()`` methods both have the following parameters: - ``query`` specifies a query filter with the criteria to match documents to update in your collection -- ``updateDocument`` specifies the fields and values to modify in the matching document or documents. For this example, we use the :doc:`Updates builder ` to create the update document. +- ``updateDocument`` specifies the fields and values to modify in the + matching document or documents. This example uses the :ref:`Updates + ` builder methods to create the update + document. +- *(Optional)* ``updateOptions`` specifies options that you can set to + customize how the driver performs the update operation. To learn more + about this type, see the API documentation for `UpdateOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__. You can create the ``updateDocument`` using an ``Updates`` builder as follows: .. code-block:: kotlin - val updateDocument = Updates.operator(field, value) + val updateDocument = Updates.operator(, ) -See the MongoDB API documentation for a `complete list of -Updates builders and their usage <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__. +To view a complete list of ``Updates`` builders and their usage, see `Updates +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__ +in the API documentation. -Example -``````` +Update One Example +~~~~~~~~~~~~~~~~~~ The paint store needs to update their inventory after a customer returns a can of yellow paint. @@ -93,8 +106,9 @@ can of yellow paint. To update the single can of paint, call the ``updateOne()`` method specifying the following: -- A query filter that matches the yellow color -- An update document that contains instructions to increment the ``qty`` field by "1" +- Query filter that matches the yellow color +- Update document that contains instructions to increment the ``qty`` + field by ``1`` .. io-code-block:: @@ -107,14 +121,27 @@ the following: Matched document count: 1 Modified document count: 1 +If multiple documents match the query filter specified in +the ``updateOne()`` method, it 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 + +Update Many Example +~~~~~~~~~~~~~~~~~~~ + The paint store then receives a fresh shipment and needs to update their inventory again. The shipment contains 20 cans of each paint color. To update the inventory, call the ``updateMany()`` method specifying the following: -- A query filter that matches all the colors -- An update document that contains instructions to increment the ``qty`` field by "20" +- Query filter that matches all the colors +- Update document that contains instructions to increment the ``qty`` + field by ``20`` .. io-code-block:: @@ -140,9 +167,9 @@ The following shows the updated documents in the ``paint_inventory`` collection: If zero documents match the query filter in the update operation, ``updateMany()`` makes no changes to documents in the collection. See -our :doc:`upsert guide ` to +the :ref:`Upsert ` guide to learn how to insert a new document instead of updating one if no -documents match. +documents match. .. important:: @@ -170,7 +197,7 @@ instance as follows: .. code-block:: kotlin - collection.replaceOne(query, replacementDocument) + collection.replaceOne(, ) Replace Operation Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -179,9 +206,13 @@ The ``replaceOne()`` method has the following parameters: - ``query`` specifies a query filter with the criteria to match a document to replace in your collection - ``replacementDocument`` specifies fields and values of a new ``Document`` object to replace in the matched document +- *(Optional)* ``replaceOptions`` specifies options that you can set to + customize how the driver performs the replace operation. To learn more + about this type, see the API documentation for `ReplaceOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__. -Example -``````` +Replace One Example +~~~~~~~~~~~~~~~~~~~ The paint store realizes they need to update their inventory again. What they thought was 20 cans of pink paint is actually 25 cans of orange paint. @@ -189,8 +220,8 @@ thought was 20 cans of pink paint is actually 25 cans of orange paint. To update the inventory, call the ``replaceOne()`` method specifying the following: -- A query filter that matches documents where the ``color`` is "pink" -- A replacement document where the ``color`` is "orange" and the ``qty`` is "25" +- Query filter that matches documents where the ``color`` is "pink" +- Replacement document where the ``color`` is "orange" and the ``qty`` is "25" .. io-code-block:: @@ -210,14 +241,20 @@ The following shows the updated document: { "_id": 5, "color": "orange", "qty": 25 } +If multiple documents match the query filter specified in +the ``replaceOne()`` method, it 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 + If zero documents match the query filter in the replace operation, ``replaceOne()`` makes no changes to documents in the collection. See -our :doc:`upsert guide ` to +the :ref:`Upsert ` guide to learn how to insert a new document instead of replacing one if no -documents match. - -If multiple documents match the query filter specified in -the ``replaceOne()`` method, it replaces the first result. +documents match. .. important:: diff --git a/source/fundamentals/crud/write-operations/upsert.txt b/source/fundamentals/crud/write-operations/upsert.txt index 7b16c453..c6287a2c 100644 --- a/source/fundamentals/crud/write-operations/upsert.txt +++ b/source/fundamentals/crud/write-operations/upsert.txt @@ -1,3 +1,5 @@ +.. _kotlin-fundamentals-upsert: + ====================================== Insert or Update in a Single Operation ====================================== diff --git a/source/fundamentals/indexes.txt b/source/fundamentals/indexes.txt index c095a6dc..cd7084c4 100644 --- a/source/fundamentals/indexes.txt +++ b/source/fundamentals/indexes.txt @@ -236,7 +236,7 @@ Search, see the :atlas:`Atlas Search Indexes Atlas Vector Search enables you to perform semantic searches on vector embeddings stored in MongoDB Atlas. To learn more about Atlas Vector Search, see the -:ref:`kotlin-atlas-vector-search` section in the Aggregates Builder guide. +:ref:`kotlin-atlas-vector-search` guide. You can call the following methods on a collection to manage your Atlas Search and Vector Search indexes: diff --git a/source/includes/language-compatibility-table-kotlin.rst b/source/includes/language-compatibility-table-kotlin.rst index 8b56e985..02d3f294 100644 --- a/source/includes/language-compatibility-table-kotlin.rst +++ b/source/includes/language-compatibility-table-kotlin.rst @@ -7,5 +7,5 @@ * - Kotlin Driver Version - Kotlin 1.8 - * - 4.10 to 5.2 + * - 4.10 to 5.3 - ✓ diff --git a/source/includes/mongodb-compatibility-table-kotlin.rst b/source/includes/mongodb-compatibility-table-kotlin.rst index dbd5fd4e..d77a7077 100644 --- a/source/includes/mongodb-compatibility-table-kotlin.rst +++ b/source/includes/mongodb-compatibility-table-kotlin.rst @@ -13,7 +13,7 @@ - MongoDB 4.0 - MongoDB 3.6 - * - 5.2 + * - 5.2 to 5.3 - ✓ - ✓ - ✓ diff --git a/source/whats-new.txt b/source/whats-new.txt index 7dc7c43d..64711559 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -12,6 +12,7 @@ What's New Learn what's new in: +* :ref:`Version 5.3 ` * :ref:`Version 5.2 ` * :ref:`Version 5.1.3 ` * :ref:`Version 5.1.2 ` @@ -21,6 +22,27 @@ Learn what's new in: * :ref:`Version 4.11 ` * :ref:`Version 4.10 ` +.. _kotlin-coroutine-version-5.3: + +What's New in 5.3 +----------------- + +The 5.3 driver release includes the following new features, +improvements, and fixes: + +.. sharedinclude:: dbx/jvm/v5.3-wn-items.rst + + .. replacement:: vector-type-example-link + + To learn about how to use this type when using the Atlas + Vector Search feature, see the :ref:`kotlin-atlas-vector-search` + guide. + + .. replacement:: update-replace-example-link + + the :ref:`kotlin-fundamentals-change-document` and :ref:`kotlin-fundamentals-bulkwrite` + guides + .. _kotlin-coroutine-version-5.2: What's New in 5.2