diff --git a/snooty.toml b/snooty.toml index 89425e92..60ae09ba 100644 --- a/snooty.toml +++ b/snooty.toml @@ -27,7 +27,7 @@ full-version = "{+version-number+}.2" version = "v{+version-number+}" mdb-server = "MongoDB Server" stable-api = "Stable API" -api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" +api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync" java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}" -core-api = "{+java-api+}/apidocs/mongodb-driver-core/" +core-api = "{+java-api+}/apidocs/mongodb-driver-core" kotlin-docs = "https://kotlinlang.org" diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt index 9c17b6e3..f3c28fe5 100644 --- a/source/connect/stable-api.txt +++ b/source/connect/stable-api.txt @@ -125,11 +125,11 @@ API Documentation For more information about using the {+stable-api+} with {+driver-short+}, see the following API documentation: -- `ServerApi <{+core-api+}com/mongodb/ServerApi.html>`__ -- `ServerApi.Builder <{+core-api+}com/mongodb/ServerApi.Builder.html>`__ -- `ServerApiVersion <{+core-api+}com/mongodb/ServerApiVersion.html>`__ -- `ServerAddress <{+core-api+}com/mongodb/ServerAddress.html>`__ -- `MongoClientSettings <{+core-api+}com/mongodb/MongoClientSettings.html>`__ -- `MongoClientSettings.Builder <{+core-api+}com/mongodb/MongoClientSettings.Builder.html>`__ -- `MongoClient <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ -- `MongoClient.create() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/-factory/create.html>`__ +- `ServerApi <{+core-api+}/com/mongodb/ServerApi.html>`__ +- `ServerApi.Builder <{+core-api+}/com/mongodb/ServerApi.Builder.html>`__ +- `ServerApiVersion <{+core-api+}/com/mongodb/ServerApiVersion.html>`__ +- `ServerAddress <{+core-api+}/com/mongodb/ServerAddress.html>`__ +- `MongoClientSettings <{+core-api+}/com/mongodb/MongoClientSettings.html>`__ +- `MongoClientSettings.Builder <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html>`__ +- `MongoClient <{+api+}/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `MongoClient.create() <{+api+}/com.mongodb.kotlin.client/-mongo-client/-factory/create.html>`__ diff --git a/source/data-formats/time-series.txt b/source/data-formats/time-series.txt index 6f7d754b..e3185279 100644 --- a/source/data-formats/time-series.txt +++ b/source/data-formats/time-series.txt @@ -175,7 +175,7 @@ API Documentation To learn more about the methods mentioned in this guide, see the following API documentation: -- `createCollection() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-database/create-collection.html>`__ -- `listCollections() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-database/list-collections.html>`__ -- `insertOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/insert-one.html>`__ -- `insertMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/insert-many.html>`__ \ No newline at end of file +- `createCollection() <{+api+}/com.mongodb.kotlin.client/-mongo-database/create-collection.html>`__ +- `listCollections() <{+api+}/com.mongodb.kotlin.client/-mongo-database/list-collections.html>`__ +- `insertOne() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/insert-one.html>`__ +- `insertMany() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/insert-many.html>`__ \ No newline at end of file diff --git a/source/includes/write/bulk.kt b/source/includes/write/bulk.kt new file mode 100644 index 00000000..b2f99308 --- /dev/null +++ b/source/includes/write/bulk.kt @@ -0,0 +1,81 @@ +import com.mongodb.client.model.* +import com.mongodb.client.model.Filters.* +import com.mongodb.kotlin.client.MongoClient + +// start-data-class +data class Restaurant( + val name: String, + val borough: String, + val cuisine: String +) +// end-data-class + +fun main() { + val uri = "" + + val mongoClient = MongoClient.create(uri) + val database = mongoClient.getDatabase("sample_restaurants") + val collection = database.getCollection("restaurants") + + // start-bulk-insert-one + val blueMoon = InsertOneModel(Restaurant("Blue Moon Grill", "Brooklyn", "American")) + // end-bulk-insert-one + + // start-bulk-update-one + val updateOneFilter = Filters.eq(Restaurant::name.name, "White Horse Tavern") + val updateOneDoc = Updates.set(Restaurant::borough.name, "Queens") + val tavernUpdate = UpdateOneModel(updateOneFilter, updateOneDoc) + // end-bulk-update-one + + // start-bulk-update-many + val updateManyFilter = Filters.eq(Restaurant::name.name, "Wendy's") + val updateManyDoc = Updates.set(Restaurant::cuisine.name, "Fast food") + val wendysUpdate = UpdateManyModel(updateManyFilter, updateManyDoc) + // end-bulk-update-many + + // start-bulk-replace-one + val replaceFilter = Filters.eq(Restaurant::name.name, "Cooper Town Diner") + val replaceDoc = Restaurant("Smith Town Diner", "Brooklyn", "American") + val replacement = ReplaceOneModel(replaceFilter, replaceDoc) + // end-bulk-replace-one + + // start-bulk-delete-one + val deleteOne = DeleteOneModel(Filters.eq( + Restaurant::name.name, + "Morris Park Bake Shop" + )) + // end-bulk-delete-one + + // start-bulk-delete-many + val deleteMany = DeleteManyModel(Filters.eq( + Restaurant::cuisine.name, + "Experimental" + )) + // end-bulk-delete-many + + // start-bulk-write-mixed + val insertOneMdl = InsertOneModel(Restaurant("Red's Pizza", "Brooklyn", "Pizzeria")) + val updateOneMdl = UpdateOneModel( + Filters.eq(Restaurant::name.name, "Moonlit Tavern"), + Updates.set(Restaurant::borough.name, "Queens") + ) + val deleteManyMdl = DeleteManyModel( + Filters.eq(Restaurant::name.name, "Crepe") + ) + + val bulkResult = collection.bulkWrite( + listOf(insertOneMdl, updateOneMdl, deleteManyMdl) + ) + + println(bulkResult) + // end-bulk-write-mixed + + val bulkOperations = listOf(insertOneMdl, updateOneMdl, deleteManyMdl) + + // start-bulk-write-unordered + val opts = BulkWriteOptions().ordered(false) + collection.bulkWrite(bulkOperations, opts) + // end-bulk-write-unordered + +} + diff --git a/source/indexes/atlas-search-index.txt b/source/indexes/atlas-search-index.txt index 7d9cc53a..e786313b 100644 --- a/source/indexes/atlas-search-index.txt +++ b/source/indexes/atlas-search-index.txt @@ -47,8 +47,8 @@ each of the preceding methods. Create a Search Index --------------------- -You can use the `createSearchIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/create-search-index.html>`__ -and the `createSearchIndexes() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/create-search-indexes.html>`__ +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. The following code example shows how to create a single index: @@ -77,7 +77,7 @@ List Search Indexes ------------------- You can use the -`listSearchIndexes() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/list-search-indexes.html>`__ +`listSearchIndexes() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/list-search-indexes.html>`__ method to return all Atlas Search indexes in a collection. The following code example shows how to print a list of the search indexes in @@ -95,7 +95,7 @@ Update a Search Index --------------------- You can use the -`updateSearchIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/update-search-index.html>`__ +`updateSearchIndex() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/update-search-index.html>`__ method to update an Atlas Search index. The following code shows how to update a search index: @@ -112,7 +112,7 @@ Delete a Search Index --------------------- You can use the -`dropSearchIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/drop-search-index.html>`__ +`dropSearchIndex() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/drop-search-index.html>`__ method to delete an Atlas Search index. The following code shows how to delete a search index from a collection: diff --git a/source/indexes/compound-index.txt b/source/indexes/compound-index.txt index cf3942aa..845c24fb 100644 --- a/source/indexes/compound-index.txt +++ b/source/indexes/compound-index.txt @@ -93,6 +93,6 @@ API Documentation To learn more about any of the methods discussed in this guide, see the following API documentation: -- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ -- `filter() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/filter.html>`__ -- `sort() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/sort.html>`__ \ No newline at end of file +- `find() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ +- `filter() <{+api+}/com.mongodb.kotlin.client/-find-iterable/filter.html>`__ +- `sort() <{+api+}/com.mongodb.kotlin.client/-find-iterable/sort.html>`__ \ No newline at end of file diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt index bcfd719b..8eca6e8f 100644 --- a/source/indexes/single-field-index.txt +++ b/source/indexes/single-field-index.txt @@ -91,6 +91,6 @@ API Documentation To learn more about any of the methods discussed in this guide, see the following API documentation: -- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ -- `filter() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/filter.html>`__ -- `sort() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/sort.html>`__ \ No newline at end of file +- `find() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ +- `filter() <{+api+}/com.mongodb.kotlin.client/-find-iterable/filter.html>`__ +- `sort() <{+api+}/com.mongodb.kotlin.client/-find-iterable/sort.html>`__ \ No newline at end of file diff --git a/source/read/count.txt b/source/read/count.txt index d0952d43..4f8365b1 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -201,5 +201,5 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `countDocuments() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/count-documents.html>`__ -- `estimatedDocumentCount() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/estimated-document-count.html>`__ \ No newline at end of file +- `countDocuments() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/count-documents.html>`__ +- `estimatedDocumentCount() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/estimated-document-count.html>`__ \ No newline at end of file diff --git a/source/read/project.txt b/source/read/project.txt index c77d06cd..40f4abfc 100644 --- a/source/read/project.txt +++ b/source/read/project.txt @@ -123,5 +123,5 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API Documentation: -- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ -- `projection() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/projection.html>`__ \ No newline at end of file +- `find() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ +- `projection() <{+api+}/com.mongodb.kotlin.client/-find-iterable/projection.html>`__ \ No newline at end of file diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index 17f4fff7..3106b079 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -151,7 +151,7 @@ number of documents returned by the query to ``10`` and set a maximum execution :copyable: :dedent: -For a full list of methods that modify the behavior of ``find()``, see the `API documentation <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/index.html>`__ +For a full list of methods that modify the behavior of ``find()``, see the `API documentation <{+api+}/com.mongodb.kotlin.client/-find-iterable/index.html>`__ for the ``FindIterable`` class. Additional Information @@ -168,5 +168,5 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ -- `FindIterable <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/index.html>`__ \ No newline at end of file +- `find() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ +- `FindIterable <{+api+}/com.mongodb.kotlin.client/-find-iterable/index.html>`__ \ No newline at end of file diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt index 7761438f..02464f5d 100644 --- a/source/read/specify-a-query.txt +++ b/source/read/specify-a-query.txt @@ -263,4 +263,4 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ +- `find() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt index 1fd24154..0bed8014 100644 --- a/source/read/specify-documents-to-return.txt +++ b/source/read/specify-documents-to-return.txt @@ -192,7 +192,7 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ -- `limit() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/limit.html>`__ -- `sort() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/sort.html>`__ -- `skip() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/skip.html>`__ +- `find() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ +- `limit() <{+api+}/com.mongodb.kotlin.client/-find-iterable/limit.html>`__ +- `sort() <{+api+}/com.mongodb.kotlin.client/-find-iterable/sort.html>`__ +- `skip() <{+api+}/com.mongodb.kotlin.client/-find-iterable/skip.html>`__ diff --git a/source/work-with-indexes.txt b/source/work-with-indexes.txt index b0f9da79..435119fa 100644 --- a/source/work-with-indexes.txt +++ b/source/work-with-indexes.txt @@ -118,7 +118,7 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `createIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/create-index.html>`__ -- `createIndexes() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/create-indexes.html>`__ -- `dropIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/drop-index.html>`__ -- `dropIndexes() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/drop-indexes.html>`__ +- `createIndex() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/create-index.html>`__ +- `createIndexes() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/create-indexes.html>`__ +- `dropIndex() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/drop-index.html>`__ +- `dropIndexes() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/drop-indexes.html>`__ diff --git a/source/write-operations.txt b/source/write-operations.txt index cabd4012..398f3d03 100644 --- a/source/write-operations.txt +++ b/source/write-operations.txt @@ -25,10 +25,10 @@ Write Data to MongoDB /write/insert /write/update /write/delete + /write/bulk-write .. /write/replace - /write/bulk-write /write/gridfs Overview @@ -183,5 +183,5 @@ single bulk operation: :copyable: :dedent: -.. To learn more about the ``bulk_write()`` method, see the -.. :ref:`Bulk Write ` guide. +To learn more about the ``bulkWrite()`` method, see the +:ref:`Bulk Write ` guide. diff --git a/source/write/bulk-write.txt b/source/write/bulk-write.txt new file mode 100644 index 00000000..6995d233 --- /dev/null +++ b/source/write/bulk-write.txt @@ -0,0 +1,344 @@ +.. _kotlin-sync-bulk-write: + +===================== +Bulk Write Operations +===================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: insert, update, replace, code example, multiple changes + +Overview +-------- + +This guide shows you how to use the {+driver-short+} to perform a bulk +write operation that makes multiple changes to your data in a single +database call. + +Consider a situation that requires you to insert documents, update +documents, and delete documents for the same task. If you use +the individual write methods to perform each type of operation, each write +accesses the database separately. You can use a bulk write operation to +optimize the number of calls your application makes to the server. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``sample_restaurants.restaurants`` collection +from the :atlas:`Atlas sample datasets `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +The documents in this collection are modeled by the following {+language+} data class: + +.. literalinclude:: /includes/write/bulk.kt + :start-after: start-data-class + :end-before: end-data-class + :language: kotlin + :copyable: + :dedent: + +Define the Write Operations +--------------------------- + +For each write operation you want to perform, create a corresponding +instance of one of the following operation classes that inherit from the +generic ``WriteModel`` class: + +- ``InsertOneModel`` +- ``UpdateOneModel`` +- ``UpdateManyModel`` +- ``ReplaceOneModel`` +- ``DeleteOneModel`` +- ``DeleteManyModel`` + +Then, pass a list of these instances to the ``bulkWrite()`` method. + +The following sections show how to create and use instances of the +preceding classes. The :ref:`kotlin-sync-bulkwrite-method` section +demonstrates how to pass a list of models to the ``bulkWrite()`` method +to perform the bulk operation. + +Insert Operations +~~~~~~~~~~~~~~~~~ + +To perform an insert operation, create an ``InsertOneModel`` instance and specify +the document you want to insert. + +The following example creates an instance of ``InsertOneModel``: + +.. literalinclude:: /includes/write/bulk.kt + :start-after: start-bulk-insert-one + :end-before: end-bulk-insert-one + :language: kotlin + :copyable: + :dedent: + +To insert multiple documents, create an instance of ``InsertOneModel`` +for each document. + +.. important:: + + When performing a bulk operation, the ``InsertOneModel`` cannot + insert a document with an ``_id`` that already exists in the + collection. In this situation, the driver throws a + ``MongoBulkWriteException``. + +Update Operations +~~~~~~~~~~~~~~~~~ + +To update a document, create an instance of ``UpdateOneModel`` and pass +the following arguments: + +- A **query filter** that specifies the criteria used to match documents in your collection +- The update operation you want to perform. For more information about update + operations, see the :manual:`Field Update Operators + ` guide in the {+mdb-server+} manual. + +An ``UpdateOneModel`` instance specifies an update for *the first* +document that matches your query filter. + +The following example creates an instance of ``UpdateOneModel``: + +.. literalinclude:: /includes/write/bulk.kt + :start-after: start-bulk-update-one + :end-before: end-bulk-update-one + :language: kotlin + :copyable: + :dedent: + +To update multiple documents, create an instance of ``UpdateManyModel`` and pass +the same arguments as for ``UpdateOneModel``. The ``UpdateManyModel`` +class specifies updates for *all* documents that match your query +filter. + +The following example creates an instance of ``UpdateManyModel``: + +.. literalinclude:: /includes/write/bulk.kt + :start-after: start-bulk-update-many + :end-before: end-bulk-update-many + :language: kotlin + :copyable: + :dedent: + +Replace Operations +~~~~~~~~~~~~~~~~~~ + +A replace operation removes all fields and values of a specified document and +replaces them with new fields and values that you specify. To perform a +replace operation, create an instance of ``ReplaceOneModel`` and pass a +query filter and the fields and values you want to replace the matching +document with. + +The following example creates an instance of ``ReplaceOneModel``: + +.. literalinclude:: /includes/write/bulk.kt + :start-after: start-bulk-replace-one + :end-before: end-bulk-replace-one + :language: kotlin + :copyable: + :dedent: + +To replace multiple documents, you must create an instance of +``ReplaceOneModel`` for each document. + +Delete Operations +~~~~~~~~~~~~~~~~~ + +To delete a document, create an instance of ``DeleteOneModel`` and pass a +query filter specifying the document you want to delete. A +``DeleteOneModel`` instance provides instructions to delete +only *the first* document that matches your query filter. + +The following example creates an instance of ``DeleteOneModel``: + +.. literalinclude:: /includes/write/bulk.kt + :start-after: start-bulk-delete-one + :end-before: end-bulk-delete-one + :language: kotlin + :copyable: + :dedent: + +To delete multiple documents, create an instance of ``DeleteManyModel`` and pass a +query filter specifying the document you want to delete. An instance of +``DeleteManyModel`` provides instructions to remove *all* documents that +match your query filter. + +The following example creates an instance of ``DeleteManyModel``: + +.. literalinclude:: /includes/write/bulk.kt + :start-after: start-bulk-delete-many + :end-before: end-bulk-delete-many + :language: kotlin + :copyable: + :dedent: + +.. _kotlin-sync-bulkwrite-method: + +Perform the Bulk Operation +-------------------------- + +After you define a model instance for each operation you want to perform, +pass a list of these instances to the ``bulkWrite()`` method. +By default, the method runs the operations in the order +specified by the list of models. + +The following example performs multiple write operations by using the +``bulkWrite()`` method: + +.. io-code-block:: + + .. input:: /includes/write/bulk.kt + :start-after: start-bulk-write-mixed + :end-before: end-bulk-write-mixed + :language: kotlin + :dedent: + + .. output:: + + AcknowledgedBulkWriteResult{insertedCount=1, matchedCount=5, removedCount=3, + modifiedCount=2, upserts=[], inserts=[BulkWriteInsert{index=0, + id=BsonObjectId{value=...}}]} + +If any of the write operations fail, {+driver-short+} raises a +``BulkWriteError`` and does not perform any further operations. +``BulkWriteError`` provides a ``details`` item that includes the +operation that failed, and details about the exception. + +.. note:: + + When the driver runs a bulk operation, it uses the write concern of the + target collection. The driver reports all write concern errors after + attempting all operations, regardless of execution order. + +Customize Bulk Write Operation +------------------------------ + +The ``bulkWrite()`` method optionally accepts a parameter which +specifies options you can use to configure the bulk write +operation. If you don't specify any options, the driver performs the +bulk operation with default settings. + +The following table describes the setter methods that you can use to +configure a ``BulkWriteOptions`` instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Property + - Description + + * - ``ordered()`` + - | If ``true``, the driver performs the write operations in the order + provided. If an error occurs, the remaining operations are not + attempted. + | + | If ``false``, the driver performs the operations in an + arbitrary order and attempts to perform all operations. + | Defaults to ``true``. + + * - ``bypassDocumentValidation()`` + - | Specifies whether the update operation bypasses document validation. This lets you + update documents that don't meet the schema validation requirements, if any + exist. For more information about schema validation, see :manual:`Schema + Validation ` in the MongoDB + Server manual. + | Defaults to ``false``. + + * - ``comment()`` + - | Sets a comment to attach to the operation. + + * - ``let()`` + - | Provides a map of parameter names and values to set top-level + variables for the operation. Values must be constant or closed + expressions that don't reference document fields. + +The following code creates options and uses the ``ordered(false)`` option to +specify an unordered bulk write. Then, the example uses the +``bulkWrite()`` method to perform a bulk operation: + +.. literalinclude:: /includes/write/bulk.kt + :start-after: start-bulk-write-unordered + :end-before: end-bulk-write-unordered + :language: kotlin + :copyable: + :dedent: + +If any of the write operations in an unordered bulk write fail, the {+driver-short+} +reports the errors only after attempting all operations. + +.. note:: + + Unordered bulk operations do not guarantee an order of execution. The + order can differ from the way you list them to optimize the runtime. + +Return Value +------------ + +The ``bulkWrite()`` method returns a ``BulkWriteResult`` object. You can +access the following information from a ``BulkWriteResult`` instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Property + - Description + + * - ``wasAcknowledged()`` + - | Indicates if the server acknowledged the write operation. + + * - ``getDeletedCount()`` + - | The number of documents deleted, if any. + + * - ``getInsertedCount()`` + - | The number of documents inserted, if any. + + * - ``getInserts()`` + - | The list of inserted documents, if any. + + * - ``getMatchedCount()`` + - | The number of documents matched for an update, if applicable. + + * - ``getModifiedCount()`` + - | The number of documents modified, if any. + + * - ``getUpserts()`` + - | The list of upserted documents, if any. + +Additional Information +---------------------- + +To learn how to perform individual write operations, see the following guides: + +- :ref:`kotlin-sync-write-insert` +- :ref:`kotlin-sync-write-update` +- :ref:`kotlin-sync-write-delete` + +.. - :ref:`kotlin-sync-write-replace` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API Documentation: + +- `bulkWrite() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/bulk-write.html>`__ +- `InsertOneModel <{+core-api+}/com/mongodb/client/model/InsertOneModel.html>`__ +- `UpdateOneModel <{+core-api+}/com/mongodb/client/model/UpdateOneModel.html>`__ +- `UpdateManyModel <{+core-api+}/com/mongodb/client/model/UpdateManyModel.html>`__ +- `ReplaceOneModel <{+core-api+}/com/mongodb/client/model/ReplaceOneModel.html>`__ +- `DeleteOneModel <{+core-api+}/com/mongodb/client/model/DeleteOneModel.html>`__ +- `DeleteManyModel <{+core-api+}/com/mongodb/client/model/DeleteManyModel.html>`__ +- `BulkWriteOptions <{+core-api+}/com/mongodb/client/model/BulkWriteOptions.html>`__ +- `BulkWriteResult <{+core-api+}/com/mongodb/bulk/BulkWriteResult.html>`__ diff --git a/source/write/delete.txt b/source/write/delete.txt index e474b024..4225f1f7 100644 --- a/source/write/delete.txt +++ b/source/write/delete.txt @@ -190,8 +190,8 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `deleteOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-one.html>`__ -- `deleteMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-many.html>`__ +- `deleteOne() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/delete-one.html>`__ +- `deleteMany() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/delete-many.html>`__ - `DeleteResult <{+core-api+}/com/mongodb/client/result/DeleteResult.html>`__ .. .. _kotlin-sync-delete-instruqt-lab: diff --git a/source/write/insert.txt b/source/write/insert.txt index 9839df0c..d08a9b87 100644 --- a/source/write/insert.txt +++ b/source/write/insert.txt @@ -240,8 +240,8 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `insertOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/insert-one.html>`__ -- `insertMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/insert-many.html>`__ +- `insertOne() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/insert-one.html>`__ +- `insertMany() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/insert-many.html>`__ - `InsertOneOptions <{+core-api+}/com/mongodb/client/model/InsertOneOptions.html>`__ - `InsertManyOptions <{+core-api+}/com/mongodb/client/model/InsertManyOptions.html>`__ - `InsertOneResult <{+core-api+}/com/mongodb/client/result/InsertOneResult.html>`__ diff --git a/source/write/update.txt b/source/write/update.txt index 8d2c32d4..5d53628c 100644 --- a/source/write/update.txt +++ b/source/write/update.txt @@ -218,7 +218,7 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `updateOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/update-one.html>`__ -- `updateMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/update-many.html>`__ +- `updateOne() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/update-one.html>`__ +- `updateMany() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/update-many.html>`__ - `UpdateOptions <{+core-api+}/com/mongodb/client/model/UpdateOptions.html>`__ - `UpdateResult <{+core-api+}/com/mongodb/client/result/UpdateResult.html>`__