From dc573ed5b9b3904b36b2707ececaf90797d3520f Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 11 Mar 2025 17:17:30 -0400 Subject: [PATCH 01/16] DOCSP-46818: Client bulk write --- .../crud/write-operations/bulk.txt | 151 +++++++++++++++--- .../code-snippets/CRUD/bulkOps.go | 27 +++- 2 files changed, 148 insertions(+), 30 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 70e11673..6bb4a1b1 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -15,26 +15,48 @@ Bulk Operations Overview -------- -In this guide, you can learn how to use **bulk operations**. +In this guide, you can learn how to use {+driver-short+} to +perform **bulk operations**. Bulk operations reduce the number +of calls to the server by performing multiple write operations +in a single method. -Bulk operations perform a large number of write operations. Instead of -making a call for each operation to the database, bulk operations -perform multiple operations with one call to the database. +The ``Collection`` and ``Client`` classes both provide a ``BulkWrite()`` +method. When calling ``BulkWrite()`` on a ``Collection`` instance, you can +perform multiple write operations on a single collection. When calling +``BulkWrite()`` on a ``Client`` instance, you can perform bulk writes across +multiple namespaces. In MongoDB, a namespace consists of the database name and the collection +name in the format ``.``. + +.. important:: + + To perform bulk operations on a ``Client`` instance, + ensure that your application meets the following + requirements: + + - Uses {+driver-short+} v2.1 or later + - Connects to {+mdb-server+} v8.0 or later Sample Data ~~~~~~~~~~~ -The examples in this guide use the following ``Book`` struct as a model for documents -in the ``books`` collection: +The examples in this guide use the following structs: + +- ``Book`` struct, which models documents in the ``db.books`` collection. + Each document contains a description of a book that includes the title, + author, and page length. + +- ``Poem`` struct, which models documents in the ``db.poems`` collection. + Each document contains a description of a poem that includes the title, + author, and publication year. .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go - :start-after: start-book-struct - :end-before: end-book-struct + :start-after: start-structs + :end-before: end-structs :language: go :dedent: To run the examples in this guide, load the sample data into the -``db.books`` collection with the following snippet: +``books`` and ``poems`` collection by using the following snippet: .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go :language: go @@ -42,10 +64,6 @@ To run the examples in this guide, load the sample data into the :start-after: begin insertDocs :end-before: end insertDocs -Each document contains a description of a book that -includes the title, author, and page length corresponding to -the ``title``, ``author``, and ``length`` fields in each document. - .. include:: /includes/fundamentals/automatic-db-coll-creation.rst Bulk Write @@ -57,12 +75,13 @@ To perform a bulk operation, pass an array of :ref:`WriteModel Modify Behavior ~~~~~~~~~~~~~~~ -The ``BulkWrite()`` method optionally takes a ``BulkWriteOptions`` -type, which represents options you can use to modify its behavior. If -you don't specify a ``BulkWriteOptions``, the driver uses the default -values for each option. +To modify the behavior of your collection-level or client-level +bulk operation, use the following types: -The ``BulkWriteOptions`` type allows you to configure options with the +- Pass a ``BulkWriteOptions`` type to the ``Collection.BulkWrite()`` method +- Pass a ``ClientBulkWriteOptions`` type to the ``Client.BulkWrite()`` method + +The ``BulkWriteOptions`` type allows you to configure options by using the following methods: .. list-table:: @@ -73,19 +92,62 @@ following methods: - Description * - ``SetBypassDocumentValidation()`` - - | Whether to allow the write to opt-out of document level validation. + - | Specifies whether the operation can opt-out of document level validation. | Default: ``false`` * - ``SetOrdered()`` - - | Whether to stop performing write operations after an error occurs. + - | Specifies whether the driver stops performing write operations after an error occurs. | Default: ``true`` +The ``ClientBulkWriteOptions`` type allows you to configure options by using the +following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetBypassDocumentValidation()`` + - | Specifies whether the operation can opt-out of document level validation. + | Default: ``false`` + + * - ``SetOrdered()`` + - | Specifies whether the driver stops performing write operations after an error occurs. + | Default: ``true`` + + * - ``SetComment()`` + - | Specifies a comment to attach to the operation. + | Default: ``nil`` + + * - ``SetLet()`` + - | Specifies parameters for update and delete operations, which improves command + readability by separating the variables from the query text. + | Default: none + + * - ``SetWriteConcern()`` + - | Specifies the write concern for the operations. + | Default: ``nil`` + + * - ``SetVerboseResults()`` + - | Specifies whether detailed information about each successful operation is + included in the result. + | Default: ``false`` + Return Values ~~~~~~~~~~~~~ -The ``BulkWrite()`` method returns a ``BulkWriteResult`` type, which -contains information about the bulk operation if it's successful. The -``BulkWriteResult`` type contains the following properties: +The ``BulkWrite()`` method can return the following types, +which include information about the bulk operation: + +- ``BulkWriteResult`` type, if you run the bulk write + on a ``Collection`` + +- ``ClientBulkWriteResult`` type, if you run the bulk write + on a ``Client`` + +The ``BulkWriteResult`` type contains the following properties: .. list-table:: :widths: 30 70 @@ -112,12 +174,53 @@ contains information about the bulk operation if it's successful. The * - ``UpsertedIDs`` - A map of an operation index to the ``_id`` of each :ref:`upserted ` document. +The ``ClientBulkWriteResult`` type contains the following properties: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Property + - Description + + * - ``InsertedCount`` + - The number of documents inserted. + + * - ``MatchedCount`` + - The number of documents matched by the :ref:`query filter ` in update and replace operations. + + * - ``ModifiedCount`` + - The number of documents modified by update and replace operations. + + * - ``DeletedCount`` + - The number of documents deleted. + + * - ``UpsertedCount`` + - The number of documents :ref:`upserted ` by update and replace operations. + + * - ``InsertResults`` + - A map of an operation index to the ``_id`` value of each inserted document. + + * - ``UpdateResults`` + - A map of an operation index to the ``_id`` value of each updated document. + + * - ``DeleteResults`` + - A map of an operation index to the ``_id`` value of each deleted document. + + * - ``Acknowledged`` + - A boolean value that indicates whether the write operation was acknowledged. + + * - ``HasVerboseResults`` + - A boolean value that indicates whether the result contains detailed results. + .. _golang-write-model: Operations ---------- -A ``WriteModel`` represents an insert, replace, update, or delete operation. +To define the write operations to include in your bulk operation, +create a ``WriteModel`` or ``ClientWriteModel`` for each insert, +replace, update, or delete. Insert ~~~~~~ diff --git a/source/includes/fundamentals/code-snippets/CRUD/bulkOps.go b/source/includes/fundamentals/code-snippets/CRUD/bulkOps.go index f2d781ea..9c9240bb 100644 --- a/source/includes/fundamentals/code-snippets/CRUD/bulkOps.go +++ b/source/includes/fundamentals/code-snippets/CRUD/bulkOps.go @@ -12,14 +12,20 @@ import ( "go.mongodb.org/mongo-driver/v2/mongo/options" ) -// start-book-struct +// start-structs type Book struct { Title string Author string Length int32 } -// end-book-struct +type Poem struct { + Title string + Author string + Year int32 +} + +// end-structs func main() { var uri string @@ -38,18 +44,27 @@ func main() { }() // begin insertDocs - coll := client.Database("db").Collection("books") - docs := []interface{}{ + bookColl := client.Database("db").Collection("books") + poemColl := client.Database("db").Collection("poems") + + books := []interface{}{ Book{Title: "My Brilliant Friend", Author: "Elena Ferrante", Length: 331}, Book{Title: "Lucy", Author: "Jamaica Kincaid", Length: 103}, } - result, err := coll.InsertMany(context.TODO(), docs) + poems := []interface{}{ + Poem{Title: "Song of Myself", Author: "Walt Whitman", Year: 1855}, + Poem{Title: "The Raincoat", Author: "Ada Limón", Year: 2018}, + } + + bookInsert, err := bookColl.InsertMany(context.TODO(), books) + poemInsert, err := poemColl.InsertMany(context.TODO(), poems) //end insertDocs if err != nil { panic(err) } - fmt.Printf("Number of documents inserted: %d\n", len(result.InsertedIDs)) + fmt.Printf("Number of book documents inserted: %d\n", len(bookInsert.InsertedIDs)) + fmt.Printf("Number of poem documents inserted: %d\n", len(poemInsert.InsertedIDs)) fmt.Println("\nInsertOneModel:\n") { From 3ab04ccbcff5613b99dd823202571aab3205276e Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 12 Mar 2025 17:17:06 -0400 Subject: [PATCH 02/16] rest of page --- .../crud/write-operations/bulk.txt | 288 +++++++++++++----- .../code-snippets/CRUD/bulkOps.go | 135 ++++++-- 2 files changed, 321 insertions(+), 102 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 6bb4a1b1..19b2e197 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -225,12 +225,18 @@ replace, update, or delete. Insert ~~~~~~ -To perform an insert operation, create an ``InsertOneModel`` specifying -the document you want to insert. To insert multiple documents, create an -``InsertOneModel`` for each document you want to insert. +To define an insert operation for a bulk write on a single +collection, create an ``InsertOneModel`` specifying the document you want to insert. To +insert multiple documents, create an ``InsertOneModel`` for each +document you want to insert. -The ``InsertOneModel`` allows you to specify its behavior with the -following method: +To define an insert operation for a bulk write on multiple collections, +create a ``ClientInsertOneModel`` specifying the document you want to +insert. To insert multiple documents, create a ``ClientInsertOneModel`` for each +document you want to insert. + +You can specify the behavior of the ``InsertOneModel`` and ``ClientInsertOneModel`` +by using the following method: .. list-table:: :widths: 30 70 @@ -242,28 +248,48 @@ following method: * - ``SetDocument()`` - | The document to insert. -Example -``````` +InsertOneModel Example +`````````````````````` This following example creates two ``InsertOneModel`` instances to -insert two documents: +insert two documents into the ``books`` collection: + +.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :language: go + :dedent: + :start-after: begin bulk insert model collection + :end-before: end bulk insert model collection + +ClientInsertOneModel Example +```````````````````````````` + +This following example creates two ``ClientInsertOneModel`` instances to +insert one document into the ``books`` collection and one document into the +``poems`` collection: .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go :language: go :dedent: - :start-after: begin bulk insert model - :end-before: end bulk insert model + :start-after: begin bulk insert model client + :end-before: end bulk insert model client Replace ~~~~~~~ -To perform a replace operation, create a ``ReplaceOneModel`` specifying -the document you want to replace and a :ref:`replacement document -`. To replace multiple documents, create a -``ReplaceOneModel`` for each document you want to replace. +To define a replace operation for a bulk write on a single +collection, create a ``ReplaceOneModel`` specifying the document +you want to replace and a :ref:`replacement document `. +To replace multiple documents, create a ``ReplaceOneModel`` for +each document you want to replace. -The ``ReplaceOneModel`` allows you to specify its behavior with the -following methods: +To define a replace operation for a bulk write on multiple +collections, create a ``ClientReplaceOneModel`` specifying the document +you want to replace and a replacement document. To replace +multiple documents, create a ``ClientReplaceOneModel`` for +each document you want to replace. + +You can specify the behavior of the ``ReplaceOneModel`` and ``ClientReplaceOneModel`` +by using the following methods: .. list-table:: :widths: 30 70 @@ -284,31 +310,59 @@ following methods: * - ``SetReplacement()`` - | The document to replace the matched document with. + * - ``SetSort()`` + - | The sort order for matching documents. The replace operation + replaces only the first document according to the sort criteria. + * - ``SetUpsert()`` - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. -Example -``````` +ReplaceOneModel Example +``````````````````````` The following example creates a ``ReplaceOneModel`` to replace a -document where the ``title`` is "Lucy" with a new document: +document in the ``books`` collection in which the ``title`` value is ``"Lucy"``: + +.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :language: go + :dedent: + :start-after: begin bulk replace model collection + :end-before: end bulk replace model collection + +ClientReplaceOneModel Example +````````````````````````````` + +This example creates ``ClientReplaceOneModel`` instances to define +the following operations: + +- Replace operation on the ``books`` collection to replace a + document in which the ``title`` value is ``"Lucy"`` + +- Replace operation on the ``poems`` collection to replace a + document in which the ``title`` value is ``"Song of Myself"`` .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go :language: go :dedent: - :start-after: begin bulk replace model - :end-before: end bulk replace model + :start-after: begin bulk replace model client + :end-before: end bulk replace model client Update ~~~~~~ -To perform an update operation, create an ``UpdateOneModel`` specifying +To define an update operation for a bulk write on a single +collection, create an ``UpdateOneModel`` specifying the document you want to update and an :ref:`update document -`. To update multiple documents, use the +`. To update multiple documents, use an ``UpdateManyModel``. -The ``UpdateOneModel`` and ``UpdateManyModel`` allow you to specify -their behavior with the following methods: +To define an update operation for a bulk write on multiple +collections, create a ``ClientUpdateOneModel`` specifying +the document you want to update and an update document. +To update multiple documents, use a ``ClientUpdateManyModel``. + +You can specify the behavior of each of the update models +by using the following methods: .. list-table:: :widths: 30 70 @@ -329,33 +383,63 @@ their behavior with the following methods: * - ``SetHint()`` - | The index to use to scan for documents. + * - ``SetSort()`` + - | The criteria to use when ordering matching documents. + This method is available for only the ``UpdateOneModel`` and + ``ClientUpdateOneModel`` classes. + * - ``SetUpdate()`` - | The modifications to apply on the matched documents. * - ``SetUpsert()`` - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. -Example -``````` +UpdateOneModel Example +`````````````````````` -The following example creates an ``UpdateOneModel`` to decrement a -document's ``length`` by ``15`` if the ``author`` is "Elena Ferrante": +The following example creates an ``UpdateOneModel`` to update +a document in the ``books`` collection, decrementing a +document's ``length`` by ``15`` if the ``author`` is ``"Elena Ferrante"``: .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go :language: go :dedent: - :start-after: begin bulk update model - :end-before: end bulk update model + :start-after: begin bulk update model collection + :end-before: end bulk update model collection + +ClientUpdateOneModel Example +```````````````````````````` + +This example creates ``ClientUpdateOneModel`` instances to define +the following operations: + +- Update operation on the ``books`` collection to update a + document in which the ``author`` value is ``"Elena Ferrante"`` + +- Update operation on the ``poems`` collection to update a + document in which the ``author`` value is ``"Ada Limon"`` + +.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :language: go + :dedent: + :start-after: begin bulk update model client + :end-before: end bulk update model client Delete ~~~~~~ -To perform a delete operation, create a ``DeleteOneModel`` specifying +To define a delete operation for a bulk write on a single +collection, create a ``DeleteOneModel`` specifying the document you want to delete. To delete multiple documents, use the ``DeleteManyModel``. -The ``DeleteOneModel`` and ``DeleteManyModel`` allow you to specify -their behavior with the following methods: +To define a delete operation for a bulk write on multiple +collections, create a ``ClientDeleteOneModel`` specifying +the document you want to delete. To delete multiple documents, use the +``ClientDeleteManyModel``. + +You can specify the behavior of each of the delete models +by using the following methods: .. list-table:: :widths: 30 70 @@ -373,24 +457,48 @@ their behavior with the following methods: * - ``SetHint()`` - | The index to use to scan for documents. -Example -``````` +DeleteManyModel Example +``````````````````````` The following example creates a ``DeleteManyModel`` to delete -documents where the ``length`` is greater than ``300``: +documents in the ``books`` collection in which the ``length`` is +greater than ``300``: .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go :language: go :dedent: - :start-after: begin bulk delete model - :end-before: end bulk delete model + :start-after: begin bulk delete model collection + :end-before: end bulk delete model collection + +ClientDeleteOneModel Example +```````````````````````````` + +This example creates ``ClientDeleteOneModel`` instances to define +the following operations: + +- Delete operation on the ``books`` collection to delete a + document in which the ``length`` value is ``103`` + +- Delete operation on the ``poems`` collection to delete a + document in which the ``year`` value is ``1855`` + +.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :language: go + :dedent: + :start-after: begin bulk delete model client + :end-before: end bulk delete model client Execution Order --------------- -The ``BulkWrite()`` method allows you to specify if you want to -execute the bulk operations as ordered or unordered in its -``BulkWriteOptions``. +To specify whether the bulk write performs the operations +in order or unordered, you can set the ``Ordered`` option +to a boolean value. + +To set this option for a collection-level bulk operation, +specify the ``Ordered`` field of a ``BulkWriteOptions`` instance. +For a client-level bulk operation, specify the ``Ordered`` field +of a ``ClientBulkWriteOptions`` instance. Ordered ~~~~~~~ @@ -404,52 +512,39 @@ order you added them and stops if an error occurs. method: .. code-block:: go - + + // Specifies collection-level options opts := options.BulkWrite().SetOrdered(true) + // Specifies client-level options + opts := options.ClientBulkWrite().SetOrdered(true) + Unordered ~~~~~~~~~ -To execute bulk write operations in any order and continue if an error -occurs, specify ``false`` to the ``SetOrdered()`` method. The method -reports the errors afterward. +To run bulk write operations in any order and continue if an error +occurs, pass a value of ``false`` to the ``SetOrdered()`` method. The method +reports errors after the operation completes. -Example -``````` +Collection-Level Example +```````````````````````` The following example performs the following actions in any order: -- Inserts two documents. -- Replaces a document where the ``title`` is "My Brilliant Friend" with a new document. +- Inserts two documents +- Replaces a document where the ``title`` is "My Brilliant Friend" with a new document - Increments every document's ``length`` by ``10`` if the current - ``length`` value is less than ``200``. -- Deletes all documents where the ``author`` field value includes "Jam". + ``length`` value is less than ``200`` +- Deletes all documents where the ``author`` field value includes ``"Jam"`` .. io-code-block:: :copyable: true - .. input:: + .. input:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :start-after: begin unordered collection + :end-before: end unordered collection :language: go - - models := []mongo.WriteModel{ - mongo.NewInsertOneModel().SetDocument(Book{Title: "Middlemarch", Author: "George Eliot", Length: 904}), - mongo.NewInsertOneModel().SetDocument(Book{Title: "Pale Fire", Author: "Vladimir Nabokov", Length: 246}), - mongo.NewReplaceOneModel().SetFilter(bson.D{{"title", "My Brilliant Friend"}}). - SetReplacement(Book{Title: "Atonement", Author: "Ian McEwan", Length: 351}), - mongo.NewUpdateManyModel().SetFilter(bson.D{{"length", bson.D{{"$lt", 200}}}}). - SetUpdate(bson.D{{"$inc", bson.D{{"length", 10}}}}), - mongo.NewDeleteManyModel().SetFilter(bson.D{{"author", bson.D{{"$regex", "Jam"}}}}), - } - opts := options.BulkWrite().SetOrdered(false) - - results, err := coll.BulkWrite(context.TODO(), models, opts) - if err != nil { - panic(err) - } - - fmt.Printf("Number of documents inserted: %d\n", results.InsertedCount) - fmt.Printf("Number of documents replaced or updated: %d\n", results.ModifiedCount) - fmt.Printf("Number of documents deleted: %d\n", results.DeletedCount) + :dedent: .. output:: :language: none @@ -469,6 +564,33 @@ the bulk operation: {"title":"Middlemarch","author":"George Eliot","length":904} {"title":"Pale Fire","author":"Vladimir Nabokov","length":246} +Client-Level Example +```````````````````` + +The following example performs the following actions in any order: + +- Inserts a new document into the ``books`` and ``poems`` collections +- Updates a document in the ``poems`` collection that has a ``title`` + value of ``"The Raincoat"`` +- Replaces a document in the ``books`` collection that has a ``title`` + value of ``"My Brilliant Friend"`` + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :start-after: begin unordered client + :end-before: end unordered client + :language: go + :dedent: + + .. output:: + :language: none + :visible: false + + Number of documents inserted: 2 + Number of documents replaced or updated: 2 + Additional Information ---------------------- @@ -493,13 +615,21 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API Documentation: -- `BulkWrite() <{+api+}/mongo#Collection.BulkWrite>`__ +- `Collection.BulkWrite() <{+api+}/mongo#Collection.BulkWrite>`__ +- `Client.BulkWrite() <{+api+}/mongo#Client.BulkWrite>`__ - `BulkWriteOptions <{+api+}/mongo/options#BulkWriteOptions>`__ +- `ClientBulkWriteOptions <{+api+}/mongo/options#ClientBulkWriteOptions>`__ - `BulkWriteResult <{+api+}/mongo#BulkWriteResult>`__ -- `NewInsertOneModel() <{+api+}/mongo#NewUpdateOneModel>`__ -- `NewReplaceOneModel() <{+api+}/mongo#NewReplaceOneModel>`__ +- `ClientBulkWriteResult <{+api+}/mongo#ClientBulkWriteResult>`__ +- `NewInsertOneModel() <{+api+}/mongo#NewInsertOneModel>`__ +- `NewClientInsertOneModel() <{+api+}/mongo#NewClientInsertOneModel>`__ - `NewReplaceOneModel() <{+api+}/mongo#NewReplaceOneModel>`__ +- `NewClientReplaceOneModel() <{+api+}/mongo#NewClientReplaceOneModel>`__ - `NewUpdateOneModel() <{+api+}/mongo#NewUpdateOneModel>`__ -- `NewUpdateManyModel() <{+api+}/mongo#NewReplaceOneModel>`__ -- `NewDeleteOneModel() <{+api+}/mongo#NewReplaceOneModel>`__ -- `NewDeleteManyModel() <{+api+}/mongo#NewReplaceOneModel>`__ +- `NewClientUpdateOneModel() <{+api+}/mongo#NewClientUpdateOneModel>`__ +- `NewUpdateManyModel() <{+api+}/mongo#NewUpdateManyModel>`__ +- `NewClientUpdateManyModel() <{+api+}/mongo#NewClientUpdateManyModel>`__ +- `NewDeleteOneModel() <{+api+}/mongo#NewDeleteOneModel>`__ +- `NewClientDeleteOneModel() <{+api+}/mongo#NewClientDeleteOneModel>`__ +- `NewDeleteManyModel() <{+api+}/mongo#NewDeleteManyModel>`__ +- `NewClientDeleteManyModel() <{+api+}/mongo#NewClientDeleteManyModel>`__ diff --git a/source/includes/fundamentals/code-snippets/CRUD/bulkOps.go b/source/includes/fundamentals/code-snippets/CRUD/bulkOps.go index 9c9240bb..ceef9cd2 100644 --- a/source/includes/fundamentals/code-snippets/CRUD/bulkOps.go +++ b/source/includes/fundamentals/code-snippets/CRUD/bulkOps.go @@ -54,7 +54,7 @@ func main() { poems := []interface{}{ Poem{Title: "Song of Myself", Author: "Walt Whitman", Year: 1855}, - Poem{Title: "The Raincoat", Author: "Ada Limón", Year: 2018}, + Poem{Title: "The Raincoat", Author: "Ada Limon", Year: 2018}, } bookInsert, err := bookColl.InsertMany(context.TODO(), books) @@ -69,26 +69,41 @@ func main() { fmt.Println("\nInsertOneModel:\n") { // Creates instructions to insert documents describing books - // begin bulk insert model + // begin bulk insert model collection models := []mongo.WriteModel{ mongo.NewInsertOneModel().SetDocument(Book{Title: "Beloved", Author: "Toni Morrison", Length: 324}), mongo.NewInsertOneModel().SetDocument(Book{Title: "Outline", Author: "Rachel Cusk", Length: 258}), } - // end bulk insert model + // end bulk insert model collection + + // begin bulk insert model client + bookInsertDoc := Book{Title: "Parable of the Sower", Author: "Octavia E. Butler", Length: 320} + poemInsertDoc := Poem{Title: "Fame is a fickle food", Author: "Emily Dickinson", Year: 1659} + + writes := []mongo.ClientBulkWrite{ + {"db", "books", mongo.NewClientInsertOneModel().SetDocument(bookInsertDoc)}, + {"db", "poems", mongo.NewClientInsertOneModel().SetDocument(poemInsertDoc)}, + } + // end bulk insert model client // Runs the bulk write operation and prints the number of // inserted documents - results, err := coll.BulkWrite(context.TODO(), models) + results, err := bookColl.BulkWrite(context.TODO(), models) if err != nil { panic(err) } fmt.Printf("Number of documents inserted: %d\n", results.InsertedCount) + + _, err = client.BulkWrite(context.TODO(), writes) + if err != nil { + panic(err) + } } fmt.Println("\nDocuments After Insert:\n") { - cursor, err := coll.Find(context.TODO(), bson.D{}) + cursor, err := bookColl.Find(context.TODO(), bson.D{}) if err != nil { panic(err) } @@ -107,26 +122,42 @@ func main() { fmt.Println("\nReplaceOneModel:\n") { // Creates instructions to replace the first matching document - // begin bulk replace model + // begin bulk replace model collection models := []mongo.WriteModel{ mongo.NewReplaceOneModel().SetFilter(bson.D{{"title", "Lucy"}}). SetReplacement(Book{Title: "On Beauty", Author: "Zadie Smith", Length: 473}), } - // end bulk replace model + // end bulk replace model collection + + // begin bulk replace model client + writes := []mongo.ClientBulkWrite{ + {"db", "books", mongo.NewClientReplaceOneModel(). + SetFilter(bson.D{{"title", "Lucy"}}). + SetReplacement(Book{Title: "On Beauty", Author: "Zadie Smith", Length: 473})}, + {"db", "poems", mongo.NewClientReplaceOneModel(). + SetFilter(bson.D{{"title", "Song of Myself"}}). + SetReplacement(Poem{Title: "America", Author: "Walt Whitman", Year: 1888})}, + } + // end bulk replace model client // Runs the bulk write operation and prints the number of // replaced documents - results, err := coll.BulkWrite(context.TODO(), models) + results, err := bookColl.BulkWrite(context.TODO(), models) if err != nil { panic(err) } fmt.Printf("Number of documents replaced: %d\n", results.ModifiedCount) + + _, err = client.BulkWrite(context.TODO(), writes) + if err != nil { + panic(err) + } } fmt.Println("\nDocuments After Replace:\n") { - cursor, err := coll.Find(context.TODO(), bson.D{}) + cursor, err := bookColl.Find(context.TODO(), bson.D{}) if err != nil { panic(err) } @@ -145,26 +176,42 @@ func main() { fmt.Println("\nUpdateOneModel:\n") { // Creates instructions to update the first matching document - // begin bulk update model + // begin bulk update model collection models := []mongo.WriteModel{ mongo.NewUpdateOneModel().SetFilter(bson.D{{"author", "Elena Ferrante"}}). SetUpdate(bson.D{{"$inc", bson.D{{"length", -15}}}}), } - // end bulk update model + // end bulk update model collection + + // begin bulk update model client + writes := []mongo.ClientBulkWrite{ + {"db", "books", mongo.NewClientUpdateOneModel(). + SetFilter(bson.D{{"author", "Elena Ferrante"}}). + SetUpdate(bson.D{{"$inc", bson.D{{"length", -15}}}})}, + {"db", "poems", mongo.NewClientUpdateOneModel(). + SetFilter(bson.D{{"author", "Ada Limon"}}). + SetUpdate(bson.D{{"author", "Ada Limón"}})}, + } + // end bulk update model client // Runs the bulk write operation and prints the number of // updated documents - results, err := coll.BulkWrite(context.TODO(), models) + results, err := bookColl.BulkWrite(context.TODO(), models) if err != nil { panic(err) } fmt.Printf("Number of documents updated: %d\n", results.ModifiedCount) + + _, err = client.BulkWrite(context.TODO(), writes) + if err != nil { + panic(err) + } } fmt.Println("\nDocuments After Update:\n") { - cursor, err := coll.Find(context.TODO(), bson.D{}) + cursor, err := bookColl.Find(context.TODO(), bson.D{}) if err != nil { panic(err) } @@ -183,25 +230,39 @@ func main() { fmt.Println("\nDeleteManyModel:\n") { // Creates instructions to delete all documents that match the filter - // begin bulk delete model + // begin bulk delete model collection models := []mongo.WriteModel{ mongo.NewDeleteManyModel().SetFilter(bson.D{{"length", bson.D{{"$gt", 300}}}}), } - // end bulk delete model + // end bulk delete model collection + + // begin bulk delete model client + writes := []mongo.ClientBulkWrite{ + {"db", "books", mongo.NewClientDeleteOneModel(). + SetFilter(bson.D{{"length", 103}})}, + {"db", "poems", mongo.NewClientDeleteOneModel(). + SetFilter(bson.D{{"year", 1855}})}, + } + // end bulk delete model client // Runs the bulk write operation and prints the number of // deleted documents - results, err := coll.BulkWrite(context.TODO(), models) + results, err := bookColl.BulkWrite(context.TODO(), models) if err != nil { panic(err) } fmt.Printf("Number of documents deleted: %d\n", results.DeletedCount) + + _, err = client.BulkWrite(context.TODO(), writes) + if err != nil { + panic(err) + } } fmt.Println("\nDocuments After Delete:\n") { - cursor, err := coll.Find(context.TODO(), bson.D{}) + cursor, err := bookColl.Find(context.TODO(), bson.D{}) if err != nil { panic(err) } @@ -220,13 +281,13 @@ func main() { { client.Database("db").Collection("books").Drop(context.TODO()) - coll := client.Database("db").Collection("books") + bookColl := client.Database("db").Collection("books") docs := []interface{}{ Book{Title: "My Brilliant Friend", Author: "Elena Ferrante", Length: 331}, Book{Title: "Lucy", Author: "Jamaica Kincaid", Length: 103}, } - result, err := coll.InsertMany(context.TODO(), docs) + result, err := bookColl.InsertMany(context.TODO(), docs) if err != nil { panic(err) @@ -238,7 +299,7 @@ func main() { { // Creates instructions to make changes to documents describing // books - // begin unordered + // begin unordered collection models := []mongo.WriteModel{ mongo.NewInsertOneModel().SetDocument(Book{Title: "Middlemarch", Author: "George Eliot", Length: 904}), mongo.NewInsertOneModel().SetDocument(Book{Title: "Pale Fire", Author: "Vladimir Nabokov", Length: 246}), @@ -254,7 +315,7 @@ func main() { // Runs the bulk write operation and prints a summary of the // data changes - results, err := coll.BulkWrite(context.TODO(), models, opts) + results, err := bookColl.BulkWrite(context.TODO(), models, opts) if err != nil { panic(err) } @@ -262,12 +323,12 @@ func main() { fmt.Printf("Number of documents inserted: %d\n", results.InsertedCount) fmt.Printf("Number of documents replaced or updated: %d\n", results.ModifiedCount) fmt.Printf("Number of documents deleted: %d\n", results.DeletedCount) - // end unordered + // end unordered collection } fmt.Println("\nDocuments After Bulk Operation:\n") { - cursor, err := coll.Find(context.TODO(), bson.D{}) + cursor, err := bookColl.Find(context.TODO(), bson.D{}) if err != nil { panic(err) } @@ -282,4 +343,32 @@ func main() { fmt.Println(string(res)) } } + fmt.Println("\nClient BulkOperation Example:\n") + { + // Creates instructions to make changes to documents describing + // books + // begin unordered client + writes := []mongo.ClientBulkWrite{ + {"db", "books", mongo.NewClientInsertOneModel(). + SetDocument(Book{Title: "Middlemarch", Author: "George Eliot", Length: 904})}, + {"db", "poems", mongo.NewClientInsertOneModel(). + SetDocument(Poem{Title: "Mad Girl's Love Song", Author: "Sylvia Plath", Year: 1953})}, + {"db", "poems", mongo.NewClientUpdateOneModel(). + SetFilter(bson.D{{"title", "The Raincoat"}}). + SetUpdate(bson.D{{"title", "The Conditional"}})}, + {"db", "books", mongo.NewClientReplaceOneModel(). + SetFilter(bson.D{{"title", "My Brilliant Friend"}}). + SetReplacement(Book{Title: "The Story of a New Name", Author: "Elena Ferrante", Length: 480})}, + } + opts := options.ClientBulkWrite().SetOrdered(false) + + results, err := client.BulkWrite(context.TODO(), writes, opts) + if err != nil { + panic(err) + } + + fmt.Printf("Number of documents inserted: %d\n", results.InsertedCount) + fmt.Printf("Number of documents replaced or updated: %d\n", results.ModifiedCount) + // end unordered client + } } From 8356d3104a43ac4c5efc561e487d18a3cd9cfd99 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 12 Mar 2025 17:27:22 -0400 Subject: [PATCH 03/16] edits --- source/fundamentals/crud/write-operations/bulk.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 19b2e197..08c2405b 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -230,7 +230,7 @@ collection, create an ``InsertOneModel`` specifying the document you want to ins insert multiple documents, create an ``InsertOneModel`` for each document you want to insert. -To define an insert operation for a bulk write on multiple collections, +To define an insert operation for a bulk write on multiple namespaces, create a ``ClientInsertOneModel`` specifying the document you want to insert. To insert multiple documents, create a ``ClientInsertOneModel`` for each document you want to insert. @@ -283,7 +283,7 @@ To replace multiple documents, create a ``ReplaceOneModel`` for each document you want to replace. To define a replace operation for a bulk write on multiple -collections, create a ``ClientReplaceOneModel`` specifying the document +namespaces, create a ``ClientReplaceOneModel`` specifying the document you want to replace and a replacement document. To replace multiple documents, create a ``ClientReplaceOneModel`` for each document you want to replace. @@ -357,7 +357,7 @@ the document you want to update and an :ref:`update document ``UpdateManyModel``. To define an update operation for a bulk write on multiple -collections, create a ``ClientUpdateOneModel`` specifying +namespaces, create a ``ClientUpdateOneModel`` specifying the document you want to update and an update document. To update multiple documents, use a ``ClientUpdateManyModel``. @@ -434,7 +434,7 @@ the document you want to delete. To delete multiple documents, use the ``DeleteManyModel``. To define a delete operation for a bulk write on multiple -collections, create a ``ClientDeleteOneModel`` specifying +namespaces, create a ``ClientDeleteOneModel`` specifying the document you want to delete. To delete multiple documents, use the ``ClientDeleteManyModel``. From 0166114646fa9df088190856a3e1f9d9a4635007 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 13 Mar 2025 15:29:21 -0400 Subject: [PATCH 04/16] RR feedback --- .../crud/write-operations/bulk.txt | 483 ++++++++++++------ 1 file changed, 314 insertions(+), 169 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 08c2405b..053a6d35 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -66,20 +66,18 @@ To run the examples in this guide, load the sample data into the .. include:: /includes/fundamentals/automatic-db-coll-creation.rst -Bulk Write ----------- - -To perform a bulk operation, pass an array of :ref:`WriteModel -` documents to the ``BulkWrite()`` method. +Write to One Namespace +---------------------- -Modify Behavior -~~~~~~~~~~~~~~~ +To perform a bulk operation on a single namespace, call the ``BulkWrite()`` +method on a collection and pass an array of :ref:`WriteModel ` +documents as a parameter. -To modify the behavior of your collection-level or client-level -bulk operation, use the following types: +Modify Collection.BulkWrite() Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Pass a ``BulkWriteOptions`` type to the ``Collection.BulkWrite()`` method -- Pass a ``ClientBulkWriteOptions`` type to the ``Client.BulkWrite()`` method +To modify the behavior of your bulk write operation, pass a ``BulkWriteOptions`` +instance to the ``BulkWrite()`` method. The ``BulkWriteOptions`` type allows you to configure options by using the following methods: @@ -99,6 +97,52 @@ following methods: - | Specifies whether the driver stops performing write operations after an error occurs. | Default: ``true`` +Collection.BulkWrite() Return Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``BulkWrite()`` method returns a ``BulkWriteResult`` type, which +includes information about the bulk operation. + +The ``BulkWriteResult`` type contains the following properties: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Property + - Description + + * - ``InsertedCount`` + - The number of documents inserted. + + * - ``MatchedCount`` + - The number of documents matched by the :ref:`query filter ` in update and replace operations. + + * - ``ModifiedCount`` + - The number of documents modified by update and replace operations. + + * - ``DeletedCount`` + - The number of documents deleted. + + * - ``UpsertedCount`` + - The number of documents :ref:`upserted ` by update and replace operations. + + * - ``UpsertedIDs`` + - A map of an operation index to the ``_id`` of each :ref:`upserted ` document. + +Write to Multiple Namespaces +---------------------------- + +To perform a bulk operation across multiple namespaces, call the +``BulkWrite()`` method on your client and pass an array of +:ref:`ClientWriteModel ` documents as a parameter. + +Modify Client.BulkWrite() Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To modify the behavior of your bulk write operation, pass a ``ClientBulkWriteOptions`` +instance to the ``BulkWrite()`` method. + The ``ClientBulkWriteOptions`` type allows you to configure options by using the following methods: @@ -135,44 +179,11 @@ following methods: included in the result. | Default: ``false`` -Return Values -~~~~~~~~~~~~~ - -The ``BulkWrite()`` method can return the following types, -which include information about the bulk operation: - -- ``BulkWriteResult`` type, if you run the bulk write - on a ``Collection`` - -- ``ClientBulkWriteResult`` type, if you run the bulk write - on a ``Client`` - -The ``BulkWriteResult`` type contains the following properties: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Property - - Description - - * - ``InsertedCount`` - - The number of documents inserted. - - * - ``MatchedCount`` - - The number of documents matched by the :ref:`query filter ` in update and replace operations. +Client.BulkWrite() Return Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - * - ``ModifiedCount`` - - The number of documents modified by update and replace operations. - - * - ``DeletedCount`` - - The number of documents deleted. - - * - ``UpsertedCount`` - - The number of documents :ref:`upserted ` by update and replace operations. - - * - ``UpsertedIDs`` - - A map of an operation index to the ``_id`` of each :ref:`upserted ` document. +The ``BulkWrite()`` method returns a ``ClientBulkWriteResult`` type, which +includes information about the bulk operation. The ``ClientBulkWriteResult`` type contains the following properties: @@ -213,30 +224,25 @@ The ``ClientBulkWriteResult`` type contains the following properties: * - ``HasVerboseResults`` - A boolean value that indicates whether the result contains detailed results. -.. _golang-write-model: +.. _golang-write-model-collection: -Operations ----------- +Define Collection-Level Operations +---------------------------------- -To define the write operations to include in your bulk operation, -create a ``WriteModel`` or ``ClientWriteModel`` for each insert, -replace, update, or delete. +To define the write operations for your bulk operation on one +namespace, create a ``WriteModel`` for each insert, replace, +update, or delete. -Insert -~~~~~~ +InsertOneModel +~~~~~~~~~~~~~~ -To define an insert operation for a bulk write on a single -collection, create an ``InsertOneModel`` specifying the document you want to insert. To +To define an insert operation for a bulk write, create an +``InsertOneModel`` specifying the document you want to insert. To insert multiple documents, create an ``InsertOneModel`` for each document you want to insert. -To define an insert operation for a bulk write on multiple namespaces, -create a ``ClientInsertOneModel`` specifying the document you want to -insert. To insert multiple documents, create a ``ClientInsertOneModel`` for each -document you want to insert. - -You can specify the behavior of the ``InsertOneModel`` and ``ClientInsertOneModel`` -by using the following method: +You can specify the behavior of the ``InsertOneModel`` by +using the following method: .. list-table:: :widths: 30 70 @@ -248,8 +254,8 @@ by using the following method: * - ``SetDocument()`` - | The document to insert. -InsertOneModel Example -`````````````````````` +Example +``````` This following example creates two ``InsertOneModel`` instances to insert two documents into the ``books`` collection: @@ -260,8 +266,180 @@ insert two documents into the ``books`` collection: :start-after: begin bulk insert model collection :end-before: end bulk insert model collection -ClientInsertOneModel Example -```````````````````````````` +ReplaceOneModel +~~~~~~~~~~~~~~~ + +To define a replace operation for a bulk write, create +a ``ReplaceOneModel`` specifying the document you want +replace and a replacement document. To replace multiple +documents, create a ``ReplaceOneModel`` for each document +you want to replace. + +You can specify the behavior of the ``ReplaceOneModel`` by +using the following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetCollation()`` + - | The type of language collation to use when sorting results. + + * - ``SetFilter()`` + - | The :ref:`query filter ` specifying which document to replace. + + * - ``SetHint()`` + - | The index to use to scan for documents. + + * - ``SetReplacement()`` + - | The document to replace the matched document with. + + * - ``SetSort()`` + - | The sort order for matching documents. The replace operation + replaces only the first document according to the sort criteria. + + * - ``SetUpsert()`` + - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. + +Example +``````` + +The following example creates a ``ReplaceOneModel`` to replace a +document in the ``books`` collection in which the ``title`` value is ``"Lucy"``: + +.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :language: go + :dedent: + :start-after: begin bulk replace model collection + :end-before: end bulk replace model collection + +UpdateOneModel +~~~~~~~~~~~~~~ + +To define an update operation for a bulk write, create +an ``UpdateOneModel`` specifying the document you want to update +and an :ref:`update document `. To update +multiple documents, use an ``UpdateManyModel``. + +You can specify the behavior of each of the update models +by using the following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetArrayFilters()`` + - | The array elements the update applies to. + + * - ``SetCollation()`` + - | The type of language collation to use when sorting results. + + * - ``SetFilter()`` + - | The :ref:`query filter ` specifying which document to update. + + * - ``SetHint()`` + - | The index to use to scan for documents. + + * - ``SetSort()`` + - | The criteria to use when ordering matching documents. + This method is not available for the ``UpdateMnyModel`` + class. + + * - ``SetUpdate()`` + - | The modifications to apply on the matched documents. + + * - ``SetUpsert()`` + - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. + +Example +``````` + +The following example creates an ``UpdateOneModel`` to update +a document in the ``books`` collection, decrementing a +document's ``length`` by ``15`` if the ``author`` is ``"Elena Ferrante"``: + +.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :language: go + :dedent: + :start-after: begin bulk update model collection + :end-before: end bulk update model collection + +DeleteOneModel +~~~~~~~~~~~~~~ + +To define a delete operation for a bulk write, create a +``DeleteOneModel`` specifying the document you want to delete. +To delete multiple documents, use the ``DeleteManyModel``. + +You can specify the behavior of each of the delete models +by using the following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetCollation()`` + - | The type of language collation to use when sorting results. + + * - ``SetFilter()`` + - | The :ref:`query filter ` specifying which document to delete. + + * - ``SetHint()`` + - | The index to use to scan for documents. + +Example +``````` + +The following example creates a ``DeleteManyModel`` to delete +documents in the ``books`` collection in which the ``length`` is +greater than ``300``: + +.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :language: go + :dedent: + :start-after: begin bulk delete model collection + :end-before: end bulk delete model collection + +.. _golang-write-model-client: + +Define Client-Level Operation Models +------------------------------------ + +To specify the write operations for your bulk operation on multiple +namespaces, create a ``ClientWriteModel`` for each insert, +replace, update, or delete. + +ClientInsertOneModel +~~~~~~~~~~~~~~~~~~~~ + +To define an insert operation for a bulk write, create a ``ClientInsertOneModel`` +specifying the document you want to insert. To insert multiple documents, create +a ``ClientInsertOneModel`` for each document you want to insert. + +You can specify the behavior of the ``ClientInsertOneModel`` +by using the following method: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetDocument()`` + - | The document to insert. + +Example +``````` This following example creates two ``ClientInsertOneModel`` instances to insert one document into the ``books`` collection and one document into the @@ -273,23 +451,17 @@ insert one document into the ``books`` collection and one document into the :start-after: begin bulk insert model client :end-before: end bulk insert model client -Replace -~~~~~~~ +ClientReplaceOneModel +~~~~~~~~~~~~~~~~~~~~~ -To define a replace operation for a bulk write on a single -collection, create a ``ReplaceOneModel`` specifying the document +To define a replace operation for a bulk write, create +a ``ClientReplaceOneModel`` specifying the document you want to replace and a :ref:`replacement document `. -To replace multiple documents, create a ``ReplaceOneModel`` for +To replace multiple documents, create a ``ClientReplaceOneModel`` for each document you want to replace. -To define a replace operation for a bulk write on multiple -namespaces, create a ``ClientReplaceOneModel`` specifying the document -you want to replace and a replacement document. To replace -multiple documents, create a ``ClientReplaceOneModel`` for -each document you want to replace. - -You can specify the behavior of the ``ReplaceOneModel`` and ``ClientReplaceOneModel`` -by using the following methods: +You can specify the behavior of the ``ClientReplaceOneModel`` by +using the following methods: .. list-table:: :widths: 30 70 @@ -317,20 +489,8 @@ by using the following methods: * - ``SetUpsert()`` - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. -ReplaceOneModel Example -``````````````````````` - -The following example creates a ``ReplaceOneModel`` to replace a -document in the ``books`` collection in which the ``title`` value is ``"Lucy"``: - -.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go - :language: go - :dedent: - :start-after: begin bulk replace model collection - :end-before: end bulk replace model collection - -ClientReplaceOneModel Example -````````````````````````````` +Example +``````` This example creates ``ClientReplaceOneModel`` instances to define the following operations: @@ -347,18 +507,12 @@ the following operations: :start-after: begin bulk replace model client :end-before: end bulk replace model client -Update -~~~~~~ +ClientUpdateOneModel +~~~~~~~~~~~~~~~~~~~~ -To define an update operation for a bulk write on a single -collection, create an ``UpdateOneModel`` specifying -the document you want to update and an :ref:`update document -`. To update multiple documents, use an -``UpdateManyModel``. - -To define an update operation for a bulk write on multiple -namespaces, create a ``ClientUpdateOneModel`` specifying -the document you want to update and an update document. +To define an update operation for a bulk write, create +a ``ClientUpdateOneModel`` specifying the document you +want to update and an :ref:`update document `. To update multiple documents, use a ``ClientUpdateManyModel``. You can specify the behavior of each of the update models @@ -385,30 +539,17 @@ by using the following methods: * - ``SetSort()`` - | The criteria to use when ordering matching documents. - This method is available for only the ``UpdateOneModel`` and - ``ClientUpdateOneModel`` classes. + This method is not available for the ``ClientUpdateManyModel`` class. * - ``SetUpdate()`` - | The modifications to apply on the matched documents. * - ``SetUpsert()`` - - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. + - | Whether to insert a new document if the :ref:`query filter ` + doesn't match any documents. -UpdateOneModel Example -`````````````````````` - -The following example creates an ``UpdateOneModel`` to update -a document in the ``books`` collection, decrementing a -document's ``length`` by ``15`` if the ``author`` is ``"Elena Ferrante"``: - -.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go - :language: go - :dedent: - :start-after: begin bulk update model collection - :end-before: end bulk update model collection - -ClientUpdateOneModel Example -```````````````````````````` +Example +``````` This example creates ``ClientUpdateOneModel`` instances to define the following operations: @@ -425,17 +566,12 @@ the following operations: :start-after: begin bulk update model client :end-before: end bulk update model client -Delete -~~~~~~ +ClientDeleteOneModel +~~~~~~~~~~~~~~~~~~~~ -To define a delete operation for a bulk write on a single -collection, create a ``DeleteOneModel`` specifying -the document you want to delete. To delete multiple documents, use the -``DeleteManyModel``. - -To define a delete operation for a bulk write on multiple -namespaces, create a ``ClientDeleteOneModel`` specifying -the document you want to delete. To delete multiple documents, use the +To define a delete operation for a bulk write, create +a ``ClientDeleteOneModel`` specifying the document you want +to delete. To delete multiple documents, use the ``ClientDeleteManyModel``. You can specify the behavior of each of the delete models @@ -457,21 +593,8 @@ by using the following methods: * - ``SetHint()`` - | The index to use to scan for documents. -DeleteManyModel Example -``````````````````````` - -The following example creates a ``DeleteManyModel`` to delete -documents in the ``books`` collection in which the ``length`` is -greater than ``300``: - -.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go - :language: go - :dedent: - :start-after: begin bulk delete model collection - :end-before: end bulk delete model collection - -ClientDeleteOneModel Example -```````````````````````````` +Example +``````` This example creates ``ClientDeleteOneModel`` instances to define the following operations: @@ -488,37 +611,29 @@ the following operations: :start-after: begin bulk delete model client :end-before: end bulk delete model client -Execution Order ---------------- +Collection-Level Execution Order +-------------------------------- To specify whether the bulk write performs the operations in order or unordered, you can set the ``Ordered`` option -to a boolean value. - -To set this option for a collection-level bulk operation, -specify the ``Ordered`` field of a ``BulkWriteOptions`` instance. -For a client-level bulk operation, specify the ``Ordered`` field -of a ``ClientBulkWriteOptions`` instance. +to a boolean value. To set this option, specify the ``Ordered`` +field of a ``BulkWriteOptions`` instance. Ordered ~~~~~~~ -By default, the ``BulkWrite()`` method executes bulk operations in +By default, the ``BulkWrite()`` method runs bulk operations in order you added them and stops if an error occurs. .. tip:: - This is equivalent to specifying ``true`` in the ``SetOrdered()`` - method: + This is equivalent to passing a value of ``true`` to the ``SetOrdered()`` + method, as shown in the following code: .. code-block:: go - // Specifies collection-level options opts := options.BulkWrite().SetOrdered(true) - // Specifies client-level options - opts := options.ClientBulkWrite().SetOrdered(true) - Unordered ~~~~~~~~~ @@ -526,8 +641,8 @@ To run bulk write operations in any order and continue if an error occurs, pass a value of ``false`` to the ``SetOrdered()`` method. The method reports errors after the operation completes. -Collection-Level Example -```````````````````````` +Example +``````` The following example performs the following actions in any order: @@ -564,8 +679,38 @@ the bulk operation: {"title":"Middlemarch","author":"George Eliot","length":904} {"title":"Pale Fire","author":"Vladimir Nabokov","length":246} -Client-Level Example -```````````````````` +Client-Level Execution Order +---------------------------- + +To specify whether the bulk write performs the operations +in order or unordered, you can set the ``Ordered`` option +to a boolean value. To set this option, specify the ``Ordered`` +field of a ``ClientBulkWriteOptions`` instance. + +Ordered +~~~~~~~ + +By default, the ``BulkWrite()`` method executes bulk operations in +order you added them and stops if an error occurs. + +.. tip:: + + This is equivalent to passing a value of ``true`` to the ``SetOrdered()`` + method, as shown in the following code: + + .. code-block:: go + + opts := options.ClientBulkWrite().SetOrdered(true) + +Unordered +~~~~~~~~~ + +To run bulk write operations in any order and continue if an error +occurs, pass a value of ``false`` to the ``SetOrdered()`` method. The method +reports errors after the operation completes. + +Example +``````` The following example performs the following actions in any order: From e9583f6d12dea5342f34e75b09a0d4157271b787 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 13 Mar 2025 15:37:54 -0400 Subject: [PATCH 05/16] edit --- source/fundamentals/crud/write-operations/bulk.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 053a6d35..4524884d 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -27,7 +27,7 @@ perform multiple write operations on a single collection. When calling multiple namespaces. In MongoDB, a namespace consists of the database name and the collection name in the format ``.``. -.. important:: +.. important:: Client Bulk Write Requirements To perform bulk operations on a ``Client`` instance, ensure that your application meets the following From 5dd570e5767f63dbbc3877f3ba362087d95279ae Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 13 Mar 2025 15:43:53 -0400 Subject: [PATCH 06/16] fix --- .../crud/write-operations/bulk.txt | 330 +++++++++--------- 1 file changed, 165 insertions(+), 165 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 4524884d..1dd745d6 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -130,104 +130,10 @@ The ``BulkWriteResult`` type contains the following properties: * - ``UpsertedIDs`` - A map of an operation index to the ``_id`` of each :ref:`upserted ` document. -Write to Multiple Namespaces ----------------------------- - -To perform a bulk operation across multiple namespaces, call the -``BulkWrite()`` method on your client and pass an array of -:ref:`ClientWriteModel ` documents as a parameter. - -Modify Client.BulkWrite() Behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To modify the behavior of your bulk write operation, pass a ``ClientBulkWriteOptions`` -instance to the ``BulkWrite()`` method. - -The ``ClientBulkWriteOptions`` type allows you to configure options by using the -following methods: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Method - - Description - - * - ``SetBypassDocumentValidation()`` - - | Specifies whether the operation can opt-out of document level validation. - | Default: ``false`` - - * - ``SetOrdered()`` - - | Specifies whether the driver stops performing write operations after an error occurs. - | Default: ``true`` - - * - ``SetComment()`` - - | Specifies a comment to attach to the operation. - | Default: ``nil`` - - * - ``SetLet()`` - - | Specifies parameters for update and delete operations, which improves command - readability by separating the variables from the query text. - | Default: none - - * - ``SetWriteConcern()`` - - | Specifies the write concern for the operations. - | Default: ``nil`` - - * - ``SetVerboseResults()`` - - | Specifies whether detailed information about each successful operation is - included in the result. - | Default: ``false`` - -Client.BulkWrite() Return Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``BulkWrite()`` method returns a ``ClientBulkWriteResult`` type, which -includes information about the bulk operation. - -The ``ClientBulkWriteResult`` type contains the following properties: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Property - - Description - - * - ``InsertedCount`` - - The number of documents inserted. - - * - ``MatchedCount`` - - The number of documents matched by the :ref:`query filter ` in update and replace operations. - - * - ``ModifiedCount`` - - The number of documents modified by update and replace operations. - - * - ``DeletedCount`` - - The number of documents deleted. - - * - ``UpsertedCount`` - - The number of documents :ref:`upserted ` by update and replace operations. - - * - ``InsertResults`` - - A map of an operation index to the ``_id`` value of each inserted document. - - * - ``UpdateResults`` - - A map of an operation index to the ``_id`` value of each updated document. - - * - ``DeleteResults`` - - A map of an operation index to the ``_id`` value of each deleted document. - - * - ``Acknowledged`` - - A boolean value that indicates whether the write operation was acknowledged. - - * - ``HasVerboseResults`` - - A boolean value that indicates whether the result contains detailed results. - .. _golang-write-model-collection: -Define Collection-Level Operations ----------------------------------- +Define Collection-Level Operation Models +---------------------------------------- To define the write operations for your bulk operation on one namespace, create a ``WriteModel`` for each insert, replace, @@ -409,6 +315,168 @@ greater than ``300``: :start-after: begin bulk delete model collection :end-before: end bulk delete model collection +Collection-Level Execution Order +-------------------------------- + +To specify whether the bulk write performs the operations +in order, you can set the ``Ordered`` option +to a boolean value. To set this option, specify the ``Ordered`` +field of a ``BulkWriteOptions`` instance. + +Ordered +~~~~~~~ + +By default, the ``BulkWrite()`` method runs bulk operations in +order you added them and stops if an error occurs. + +.. tip:: + + This is equivalent to passing a value of ``true`` to the ``SetOrdered()`` + method, as shown in the following code: + + .. code-block:: go + + opts := options.BulkWrite().SetOrdered(true) + +Unordered +~~~~~~~~~ + +To run bulk write operations in any order and continue if an error +occurs, pass a value of ``false`` to the ``SetOrdered()`` method. The method +reports errors after the operation completes. + +Example +``````` + +The following example performs the following actions in any order: + +- Inserts two documents +- Replaces a document where the ``title`` is "My Brilliant Friend" with a new document +- Increments every document's ``length`` by ``10`` if the current + ``length`` value is less than ``200`` +- Deletes all documents where the ``author`` field value includes ``"Jam"`` + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go + :start-after: begin unordered collection + :end-before: end unordered collection + :language: go + :dedent: + + .. output:: + :language: none + :visible: false + + Number of documents inserted: 2 + Number of documents replaced or updated: 2 + Number of documents deleted: 1 + +The following documents are present in the ``books`` collection after +the bulk operation: + +.. code-block:: none + :copyable: false + + {"title":"Atonement","author":"Ian McEwan","length":351} + {"title":"Middlemarch","author":"George Eliot","length":904} + {"title":"Pale Fire","author":"Vladimir Nabokov","length":246} + +Write to Multiple Namespaces +---------------------------- + +To perform a bulk operation across multiple namespaces, call the +``BulkWrite()`` method on your client and pass an array of +:ref:`ClientWriteModel ` documents as a parameter. + +Modify Client.BulkWrite() Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To modify the behavior of your bulk write operation, pass a ``ClientBulkWriteOptions`` +instance to the ``BulkWrite()`` method. + +The ``ClientBulkWriteOptions`` type allows you to configure options by using the +following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetBypassDocumentValidation()`` + - | Specifies whether the operation can opt-out of document level validation. + | Default: ``false`` + + * - ``SetOrdered()`` + - | Specifies whether the driver stops performing write operations after an error occurs. + | Default: ``true`` + + * - ``SetComment()`` + - | Specifies a comment to attach to the operation. + | Default: ``nil`` + + * - ``SetLet()`` + - | Specifies parameters for update and delete operations, which improves command + readability by separating the variables from the query text. + | Default: none + + * - ``SetWriteConcern()`` + - | Specifies the write concern for the operations. + | Default: ``nil`` + + * - ``SetVerboseResults()`` + - | Specifies whether detailed information about each successful operation is + included in the result. + | Default: ``false`` + +Client.BulkWrite() Return Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``BulkWrite()`` method returns a ``ClientBulkWriteResult`` type, which +includes information about the bulk operation. + +The ``ClientBulkWriteResult`` type contains the following properties: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Property + - Description + + * - ``InsertedCount`` + - The number of documents inserted. + + * - ``MatchedCount`` + - The number of documents matched by the :ref:`query filter ` in update and replace operations. + + * - ``ModifiedCount`` + - The number of documents modified by update and replace operations. + + * - ``DeletedCount`` + - The number of documents deleted. + + * - ``UpsertedCount`` + - The number of documents :ref:`upserted ` by update and replace operations. + + * - ``InsertResults`` + - A map of an operation index to the ``_id`` value of each inserted document. + + * - ``UpdateResults`` + - A map of an operation index to the ``_id`` value of each updated document. + + * - ``DeleteResults`` + - A map of an operation index to the ``_id`` value of each deleted document. + + * - ``Acknowledged`` + - A boolean value that indicates whether the write operation was acknowledged. + + * - ``HasVerboseResults`` + - A boolean value that indicates whether the result contains detailed results. + .. _golang-write-model-client: Define Client-Level Operation Models @@ -611,79 +679,11 @@ the following operations: :start-after: begin bulk delete model client :end-before: end bulk delete model client -Collection-Level Execution Order --------------------------------- - -To specify whether the bulk write performs the operations -in order or unordered, you can set the ``Ordered`` option -to a boolean value. To set this option, specify the ``Ordered`` -field of a ``BulkWriteOptions`` instance. - -Ordered -~~~~~~~ - -By default, the ``BulkWrite()`` method runs bulk operations in -order you added them and stops if an error occurs. - -.. tip:: - - This is equivalent to passing a value of ``true`` to the ``SetOrdered()`` - method, as shown in the following code: - - .. code-block:: go - - opts := options.BulkWrite().SetOrdered(true) - -Unordered -~~~~~~~~~ - -To run bulk write operations in any order and continue if an error -occurs, pass a value of ``false`` to the ``SetOrdered()`` method. The method -reports errors after the operation completes. - -Example -``````` - -The following example performs the following actions in any order: - -- Inserts two documents -- Replaces a document where the ``title`` is "My Brilliant Friend" with a new document -- Increments every document's ``length`` by ``10`` if the current - ``length`` value is less than ``200`` -- Deletes all documents where the ``author`` field value includes ``"Jam"`` - -.. io-code-block:: - :copyable: true - - .. input:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go - :start-after: begin unordered collection - :end-before: end unordered collection - :language: go - :dedent: - - .. output:: - :language: none - :visible: false - - Number of documents inserted: 2 - Number of documents replaced or updated: 2 - Number of documents deleted: 1 - -The following documents are present in the ``books`` collection after -the bulk operation: - -.. code-block:: none - :copyable: false - - {"title":"Atonement","author":"Ian McEwan","length":351} - {"title":"Middlemarch","author":"George Eliot","length":904} - {"title":"Pale Fire","author":"Vladimir Nabokov","length":246} - Client-Level Execution Order ---------------------------- To specify whether the bulk write performs the operations -in order or unordered, you can set the ``Ordered`` option +in order, you can set the ``Ordered`` option to a boolean value. To set this option, specify the ``Ordered`` field of a ``ClientBulkWriteOptions`` instance. From 10b25656266c5908644a09b4e25166d2a1ef58a0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 13 Mar 2025 15:56:13 -0400 Subject: [PATCH 07/16] edits --- .../crud/write-operations/bulk.txt | 98 +++++++------------ 1 file changed, 36 insertions(+), 62 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 1dd745d6..4e04e125 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -66,15 +66,17 @@ To run the examples in this guide, load the sample data into the .. include:: /includes/fundamentals/automatic-db-coll-creation.rst -Write to One Namespace ----------------------- +.. _golang-bulk-collection: + +Collection Bulk Write +--------------------- To perform a bulk operation on a single namespace, call the ``BulkWrite()`` method on a collection and pass an array of :ref:`WriteModel ` documents as a parameter. -Modify Collection.BulkWrite() Behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modify Collection-Level Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To modify the behavior of your bulk write operation, pass a ``BulkWriteOptions`` instance to the ``BulkWrite()`` method. @@ -97,8 +99,8 @@ following methods: - | Specifies whether the driver stops performing write operations after an error occurs. | Default: ``true`` -Collection.BulkWrite() Return Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Collection-Level Return Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``BulkWrite()`` method returns a ``BulkWriteResult`` type, which includes information about the bulk operation. @@ -132,15 +134,15 @@ The ``BulkWriteResult`` type contains the following properties: .. _golang-write-model-collection: -Define Collection-Level Operation Models ----------------------------------------- +Define Collection Bulk Write Models +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To define the write operations for your bulk operation on one namespace, create a ``WriteModel`` for each insert, replace, update, or delete. InsertOneModel -~~~~~~~~~~~~~~ +`````````````` To define an insert operation for a bulk write, create an ``InsertOneModel`` specifying the document you want to insert. To @@ -160,10 +162,7 @@ using the following method: * - ``SetDocument()`` - | The document to insert. -Example -``````` - -This following example creates two ``InsertOneModel`` instances to +The following example creates two ``InsertOneModel`` instances to insert two documents into the ``books`` collection: .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/bulkOps.go @@ -173,7 +172,7 @@ insert two documents into the ``books`` collection: :end-before: end bulk insert model collection ReplaceOneModel -~~~~~~~~~~~~~~~ +``````````````` To define a replace operation for a bulk write, create a ``ReplaceOneModel`` specifying the document you want @@ -210,9 +209,6 @@ using the following methods: * - ``SetUpsert()`` - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. -Example -``````` - The following example creates a ``ReplaceOneModel`` to replace a document in the ``books`` collection in which the ``title`` value is ``"Lucy"``: @@ -223,7 +219,7 @@ document in the ``books`` collection in which the ``title`` value is ``"Lucy"``: :end-before: end bulk replace model collection UpdateOneModel -~~~~~~~~~~~~~~ +`````````````` To define an update operation for a bulk write, create an ``UpdateOneModel`` specifying the document you want to update @@ -263,9 +259,6 @@ by using the following methods: * - ``SetUpsert()`` - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. -Example -``````` - The following example creates an ``UpdateOneModel`` to update a document in the ``books`` collection, decrementing a document's ``length`` by ``15`` if the ``author`` is ``"Elena Ferrante"``: @@ -277,7 +270,7 @@ document's ``length`` by ``15`` if the ``author`` is ``"Elena Ferrante"``: :end-before: end bulk update model collection DeleteOneModel -~~~~~~~~~~~~~~ +`````````````` To define a delete operation for a bulk write, create a ``DeleteOneModel`` specifying the document you want to delete. @@ -302,9 +295,6 @@ by using the following methods: * - ``SetHint()`` - | The index to use to scan for documents. -Example -``````` - The following example creates a ``DeleteManyModel`` to delete documents in the ``books`` collection in which the ``length`` is greater than ``300``: @@ -316,7 +306,7 @@ greater than ``300``: :end-before: end bulk delete model collection Collection-Level Execution Order --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify whether the bulk write performs the operations in order, you can set the ``Ordered`` option @@ -324,7 +314,7 @@ to a boolean value. To set this option, specify the ``Ordered`` field of a ``BulkWriteOptions`` instance. Ordered -~~~~~~~ +``````` By default, the ``BulkWrite()`` method runs bulk operations in order you added them and stops if an error occurs. @@ -339,15 +329,12 @@ order you added them and stops if an error occurs. opts := options.BulkWrite().SetOrdered(true) Unordered -~~~~~~~~~ +````````` To run bulk write operations in any order and continue if an error occurs, pass a value of ``false`` to the ``SetOrdered()`` method. The method reports errors after the operation completes. -Example -``````` - The following example performs the following actions in any order: - Inserts two documents @@ -383,15 +370,17 @@ the bulk operation: {"title":"Middlemarch","author":"George Eliot","length":904} {"title":"Pale Fire","author":"Vladimir Nabokov","length":246} -Write to Multiple Namespaces ----------------------------- +.. _golang-bulk-client: + +Client Bulk Write +----------------- To perform a bulk operation across multiple namespaces, call the ``BulkWrite()`` method on your client and pass an array of :ref:`ClientWriteModel ` documents as a parameter. -Modify Client.BulkWrite() Behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modify Client-Level Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To modify the behavior of your bulk write operation, pass a ``ClientBulkWriteOptions`` instance to the ``BulkWrite()`` method. @@ -432,8 +421,8 @@ following methods: included in the result. | Default: ``false`` -Client.BulkWrite() Return Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Client-Level Return Value +~~~~~~~~~~~~~~~~~~~~~~~~~ The ``BulkWrite()`` method returns a ``ClientBulkWriteResult`` type, which includes information about the bulk operation. @@ -479,15 +468,15 @@ The ``ClientBulkWriteResult`` type contains the following properties: .. _golang-write-model-client: -Define Client-Level Operation Models ------------------------------------- +Define Client Bulk Write Models +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify the write operations for your bulk operation on multiple namespaces, create a ``ClientWriteModel`` for each insert, replace, update, or delete. ClientInsertOneModel -~~~~~~~~~~~~~~~~~~~~ +```````````````````` To define an insert operation for a bulk write, create a ``ClientInsertOneModel`` specifying the document you want to insert. To insert multiple documents, create @@ -506,10 +495,7 @@ by using the following method: * - ``SetDocument()`` - | The document to insert. -Example -``````` - -This following example creates two ``ClientInsertOneModel`` instances to +The following example creates two ``ClientInsertOneModel`` instances to insert one document into the ``books`` collection and one document into the ``poems`` collection: @@ -520,7 +506,7 @@ insert one document into the ``books`` collection and one document into the :end-before: end bulk insert model client ClientReplaceOneModel -~~~~~~~~~~~~~~~~~~~~~ +````````````````````` To define a replace operation for a bulk write, create a ``ClientReplaceOneModel`` specifying the document @@ -557,9 +543,6 @@ using the following methods: * - ``SetUpsert()`` - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. -Example -``````` - This example creates ``ClientReplaceOneModel`` instances to define the following operations: @@ -576,7 +559,7 @@ the following operations: :end-before: end bulk replace model client ClientUpdateOneModel -~~~~~~~~~~~~~~~~~~~~ +```````````````````` To define an update operation for a bulk write, create a ``ClientUpdateOneModel`` specifying the document you @@ -616,9 +599,6 @@ by using the following methods: - | Whether to insert a new document if the :ref:`query filter ` doesn't match any documents. -Example -``````` - This example creates ``ClientUpdateOneModel`` instances to define the following operations: @@ -635,7 +615,7 @@ the following operations: :end-before: end bulk update model client ClientDeleteOneModel -~~~~~~~~~~~~~~~~~~~~ +```````````````````` To define a delete operation for a bulk write, create a ``ClientDeleteOneModel`` specifying the document you want @@ -661,9 +641,6 @@ by using the following methods: * - ``SetHint()`` - | The index to use to scan for documents. -Example -``````` - This example creates ``ClientDeleteOneModel`` instances to define the following operations: @@ -680,7 +657,7 @@ the following operations: :end-before: end bulk delete model client Client-Level Execution Order ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify whether the bulk write performs the operations in order, you can set the ``Ordered`` option @@ -688,7 +665,7 @@ to a boolean value. To set this option, specify the ``Ordered`` field of a ``ClientBulkWriteOptions`` instance. Ordered -~~~~~~~ +``````` By default, the ``BulkWrite()`` method executes bulk operations in order you added them and stops if an error occurs. @@ -703,15 +680,12 @@ order you added them and stops if an error occurs. opts := options.ClientBulkWrite().SetOrdered(true) Unordered -~~~~~~~~~ +````````` To run bulk write operations in any order and continue if an error occurs, pass a value of ``false`` to the ``SetOrdered()`` method. The method reports errors after the operation completes. -Example -``````` - The following example performs the following actions in any order: - Inserts a new document into the ``books`` and ``poems`` collections From 559fef293362101821a1fae5c8cce2b05989b8ae Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 14 Mar 2025 15:32:39 -0400 Subject: [PATCH 08/16] RR feedback 2 --- .../crud/write-operations/bulk.txt | 350 +++++++++--------- 1 file changed, 183 insertions(+), 167 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 4e04e125..88ad9ad4 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -21,20 +21,17 @@ of calls to the server by performing multiple write operations in a single method. The ``Collection`` and ``Client`` classes both provide a ``BulkWrite()`` -method. When calling ``BulkWrite()`` on a ``Collection`` instance, you can -perform multiple write operations on a single collection. When calling -``BulkWrite()`` on a ``Client`` instance, you can perform bulk writes across -multiple namespaces. In MongoDB, a namespace consists of the database name and the collection -name in the format ``.``. +method. You can use the ``Collection.BulkWrite()`` method to perform +multiple write operations on a single collection. When calling +the ``Client.BulkWrite()`` method, you can perform bulk writes across +multiple namespaces. In MongoDB, a namespace consists of a database name +and a collection name. -.. important:: Client Bulk Write Requirements +.. important:: Client Bulk Write Server Requirement To perform bulk operations on a ``Client`` instance, - ensure that your application meets the following - requirements: - - - Uses {+driver-short+} v2.1 or later - - Connects to {+mdb-server+} v8.0 or later + ensure that your application connects to {+mdb-server+} + v8.0 or later Sample Data ~~~~~~~~~~~ @@ -75,63 +72,6 @@ To perform a bulk operation on a single namespace, call the ``BulkWrite()`` method on a collection and pass an array of :ref:`WriteModel ` documents as a parameter. -Modify Collection-Level Behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To modify the behavior of your bulk write operation, pass a ``BulkWriteOptions`` -instance to the ``BulkWrite()`` method. - -The ``BulkWriteOptions`` type allows you to configure options by using the -following methods: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Method - - Description - - * - ``SetBypassDocumentValidation()`` - - | Specifies whether the operation can opt-out of document level validation. - | Default: ``false`` - - * - ``SetOrdered()`` - - | Specifies whether the driver stops performing write operations after an error occurs. - | Default: ``true`` - -Collection-Level Return Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``BulkWrite()`` method returns a ``BulkWriteResult`` type, which -includes information about the bulk operation. - -The ``BulkWriteResult`` type contains the following properties: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Property - - Description - - * - ``InsertedCount`` - - The number of documents inserted. - - * - ``MatchedCount`` - - The number of documents matched by the :ref:`query filter ` in update and replace operations. - - * - ``ModifiedCount`` - - The number of documents modified by update and replace operations. - - * - ``DeletedCount`` - - The number of documents deleted. - - * - ``UpsertedCount`` - - The number of documents :ref:`upserted ` by update and replace operations. - - * - ``UpsertedIDs`` - - A map of an operation index to the ``_id`` of each :ref:`upserted ` document. - .. _golang-write-model-collection: Define Collection Bulk Write Models @@ -250,7 +190,7 @@ by using the following methods: * - ``SetSort()`` - | The criteria to use when ordering matching documents. - This method is not available for the ``UpdateMnyModel`` + This method is only available for the ``UpdateOneModel`` class. * - ``SetUpdate()`` @@ -305,6 +245,63 @@ greater than ``300``: :start-after: begin bulk delete model collection :end-before: end bulk delete model collection +Modify Collection-Level Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To modify the behavior of your bulk write operation, pass a ``BulkWriteOptions`` +instance to the ``BulkWrite()`` method. + +The ``BulkWriteOptions`` type allows you to configure options by using the +following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetBypassDocumentValidation()`` + - | Specifies whether the operation can opt-out of document level validation. + | Default: ``false`` + + * - ``SetOrdered()`` + - | Specifies whether the driver stops performing write operations after an error occurs. + | Default: ``true`` + +Collection-Level Return Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``BulkWrite()`` method returns a ``BulkWriteResult`` type, which +includes information about the bulk operation. + +The ``BulkWriteResult`` type contains the following properties: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Property + - Description + + * - ``InsertedCount`` + - The number of documents inserted. + + * - ``MatchedCount`` + - The number of documents matched by the :ref:`query filter ` in update and replace operations. + + * - ``ModifiedCount`` + - The number of documents modified by update and replace operations. + + * - ``DeletedCount`` + - The number of documents deleted. + + * - ``UpsertedCount`` + - The number of documents :ref:`upserted ` by update and replace operations. + + * - ``UpsertedIDs`` + - A map of an operation index to the ``_id`` of each :ref:`upserted ` document. + Collection-Level Execution Order ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -379,93 +376,6 @@ To perform a bulk operation across multiple namespaces, call the ``BulkWrite()`` method on your client and pass an array of :ref:`ClientWriteModel ` documents as a parameter. -Modify Client-Level Behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To modify the behavior of your bulk write operation, pass a ``ClientBulkWriteOptions`` -instance to the ``BulkWrite()`` method. - -The ``ClientBulkWriteOptions`` type allows you to configure options by using the -following methods: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Method - - Description - - * - ``SetBypassDocumentValidation()`` - - | Specifies whether the operation can opt-out of document level validation. - | Default: ``false`` - - * - ``SetOrdered()`` - - | Specifies whether the driver stops performing write operations after an error occurs. - | Default: ``true`` - - * - ``SetComment()`` - - | Specifies a comment to attach to the operation. - | Default: ``nil`` - - * - ``SetLet()`` - - | Specifies parameters for update and delete operations, which improves command - readability by separating the variables from the query text. - | Default: none - - * - ``SetWriteConcern()`` - - | Specifies the write concern for the operations. - | Default: ``nil`` - - * - ``SetVerboseResults()`` - - | Specifies whether detailed information about each successful operation is - included in the result. - | Default: ``false`` - -Client-Level Return Value -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``BulkWrite()`` method returns a ``ClientBulkWriteResult`` type, which -includes information about the bulk operation. - -The ``ClientBulkWriteResult`` type contains the following properties: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Property - - Description - - * - ``InsertedCount`` - - The number of documents inserted. - - * - ``MatchedCount`` - - The number of documents matched by the :ref:`query filter ` in update and replace operations. - - * - ``ModifiedCount`` - - The number of documents modified by update and replace operations. - - * - ``DeletedCount`` - - The number of documents deleted. - - * - ``UpsertedCount`` - - The number of documents :ref:`upserted ` by update and replace operations. - - * - ``InsertResults`` - - A map of an operation index to the ``_id`` value of each inserted document. - - * - ``UpdateResults`` - - A map of an operation index to the ``_id`` value of each updated document. - - * - ``DeleteResults`` - - A map of an operation index to the ``_id`` value of each deleted document. - - * - ``Acknowledged`` - - A boolean value that indicates whether the write operation was acknowledged. - - * - ``HasVerboseResults`` - - A boolean value that indicates whether the result contains detailed results. - .. _golang-write-model-client: Define Client Bulk Write Models @@ -473,7 +383,16 @@ Define Client Bulk Write Models To specify the write operations for your bulk operation on multiple namespaces, create a ``ClientWriteModel`` for each insert, -replace, update, or delete. +replace, update, or delete. Pass each write model to the +``ClientBulkWrite`` struct and specify the target database and collection, +as shown in the following code: + +.. code-block:: go + + writes := []mongo.ClientBulkWrite{ + {"", "", }, + ... + } ClientInsertOneModel ```````````````````` @@ -614,6 +533,12 @@ the following operations: :start-after: begin bulk update model client :end-before: end bulk update model client +.. note:: + + To update all documents that match the ``author`` field + query filters in the preceding example, use ``ClientUpdateManyModel`` + instances. + ClientDeleteOneModel ```````````````````` @@ -656,6 +581,93 @@ the following operations: :start-after: begin bulk delete model client :end-before: end bulk delete model client +Modify Client-Level Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To modify the behavior of your bulk write operation, pass a ``ClientBulkWriteOptions`` +instance to the ``BulkWrite()`` method. + +The ``ClientBulkWriteOptions`` type allows you to configure options by using the +following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetBypassDocumentValidation()`` + - | Specifies whether the operation can opt-out of document level validation. + | Default: ``false`` + + * - ``SetOrdered()`` + - | Specifies whether the driver stops performing write operations after an error occurs. + | Default: ``true`` + + * - ``SetComment()`` + - | Specifies a comment to attach to the operation. + | Default: ``nil`` + + * - ``SetLet()`` + - | Specifies parameters for update and delete operations, which improves command + readability by separating the variables from the query text. + | Default: none + + * - ``SetWriteConcern()`` + - | Specifies the write concern for the operations. + | Default: ``nil`` + + * - ``SetVerboseResults()`` + - | Specifies whether detailed information about each successful operation is + included in the result. + | Default: ``false`` + +Client-Level Return Value +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``BulkWrite()`` method returns a ``ClientBulkWriteResult`` type, which +includes information about the bulk operation. + +The ``ClientBulkWriteResult`` type contains the following properties: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Property + - Description + + * - ``InsertedCount`` + - The number of documents inserted. + + * - ``MatchedCount`` + - The number of documents matched by the :ref:`query filter ` in update and replace operations. + + * - ``ModifiedCount`` + - The number of documents modified by update and replace operations. + + * - ``DeletedCount`` + - The number of documents deleted. + + * - ``UpsertedCount`` + - The number of documents :ref:`upserted ` by update and replace operations. + + * - ``InsertResults`` + - A map of an operation index to the ``_id`` value of each inserted document. + + * - ``UpdateResults`` + - A map of an operation index to the ``_id`` value of each updated document. + + * - ``DeleteResults`` + - A map of an operation index to the ``_id`` value of each deleted document. + + * - ``Acknowledged`` + - A boolean value that indicates whether the write operation was acknowledged. + + * - ``HasVerboseResults`` + - A boolean value that indicates whether the result contains detailed results. + Client-Level Execution Order ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -732,23 +744,27 @@ API Documentation ~~~~~~~~~~~~~~~~~ To learn more about any of the methods or types discussed in this -guide, see the following API Documentation: +guide used for collection bulk writes, see the following API documentation: - `Collection.BulkWrite() <{+api+}/mongo#Collection.BulkWrite>`__ -- `Client.BulkWrite() <{+api+}/mongo#Client.BulkWrite>`__ - `BulkWriteOptions <{+api+}/mongo/options#BulkWriteOptions>`__ -- `ClientBulkWriteOptions <{+api+}/mongo/options#ClientBulkWriteOptions>`__ - `BulkWriteResult <{+api+}/mongo#BulkWriteResult>`__ -- `ClientBulkWriteResult <{+api+}/mongo#ClientBulkWriteResult>`__ - `NewInsertOneModel() <{+api+}/mongo#NewInsertOneModel>`__ -- `NewClientInsertOneModel() <{+api+}/mongo#NewClientInsertOneModel>`__ - `NewReplaceOneModel() <{+api+}/mongo#NewReplaceOneModel>`__ -- `NewClientReplaceOneModel() <{+api+}/mongo#NewClientReplaceOneModel>`__ - `NewUpdateOneModel() <{+api+}/mongo#NewUpdateOneModel>`__ -- `NewClientUpdateOneModel() <{+api+}/mongo#NewClientUpdateOneModel>`__ - `NewUpdateManyModel() <{+api+}/mongo#NewUpdateManyModel>`__ -- `NewClientUpdateManyModel() <{+api+}/mongo#NewClientUpdateManyModel>`__ - `NewDeleteOneModel() <{+api+}/mongo#NewDeleteOneModel>`__ -- `NewClientDeleteOneModel() <{+api+}/mongo#NewClientDeleteOneModel>`__ - `NewDeleteManyModel() <{+api+}/mongo#NewDeleteManyModel>`__ -- `NewClientDeleteManyModel() <{+api+}/mongo#NewClientDeleteManyModel>`__ + +To learn more about any of the methods or types discussed in this +guide used for client bulk writes, see the following API documentation: + +- `Client.BulkWrite() <{+api+}/mongo#Client.BulkWrite>`__ +- `ClientBulkWriteOptions <{+api+}/mongo/options#ClientBulkWriteOptions>`__ +- `ClientBulkWriteResult <{+api+}/mongo#ClientBulkWriteResult>`__ +- `NewClientInsertOneModel() <{+api+}/mongo#NewClientInsertOneModel>`__ +- `NewClientReplaceOneModel() <{+api+}/mongo#NewClientReplaceOneModel>`__ +- `NewClientUpdateOneModel() <{+api+}/mongo#NewClientUpdateOneModel>`__ +- `NewClientUpdateManyModel() <{+api+}/mongo#NewClientUpdateManyModel>`__ +- `NewClientDeleteOneModel() <{+api+}/mongo#NewClientDeleteOneModel>`__ +- `NewClientDeleteManyModel() <{+api+}/mongo#NewClientDeleteManyModel>`__ \ No newline at end of file From ff3c3e29eac3601f3ee15255d72f59783d00f807 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 14 Mar 2025 15:44:43 -0400 Subject: [PATCH 09/16] edits --- .../crud/write-operations/bulk.txt | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 88ad9ad4..f31641b9 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -158,8 +158,8 @@ document in the ``books`` collection in which the ``title`` value is ``"Lucy"``: :start-after: begin bulk replace model collection :end-before: end bulk replace model collection -UpdateOneModel -`````````````` +UpdateOneModel and UpdateManyModel +`````````````````````````````````` To define an update operation for a bulk write, create an ``UpdateOneModel`` specifying the document you want to update @@ -209,8 +209,8 @@ document's ``length`` by ``15`` if the ``author`` is ``"Elena Ferrante"``: :start-after: begin bulk update model collection :end-before: end bulk update model collection -DeleteOneModel -`````````````` +DeleteOneModel and DeleteManyModel +`````````````````````````````````` To define a delete operation for a bulk write, create a ``DeleteOneModel`` specifying the document you want to delete. @@ -477,8 +477,8 @@ the following operations: :start-after: begin bulk replace model client :end-before: end bulk replace model client -ClientUpdateOneModel -```````````````````` +ClientUpdateOneModel and ClientUpdateManyModel +`````````````````````````````````````````````` To define an update operation for a bulk write, create a ``ClientUpdateOneModel`` specifying the document you @@ -509,7 +509,7 @@ by using the following methods: * - ``SetSort()`` - | The criteria to use when ordering matching documents. - This method is not available for the ``ClientUpdateManyModel`` class. + This method is only available for the ``ClientUpdateOneModel`` class. * - ``SetUpdate()`` - | The modifications to apply on the matched documents. @@ -539,8 +539,8 @@ the following operations: query filters in the preceding example, use ``ClientUpdateManyModel`` instances. -ClientDeleteOneModel -```````````````````` +ClientDeleteOneModel and ClientDeleteManyModel +`````````````````````````````````````````````` To define a delete operation for a bulk write, create a ``ClientDeleteOneModel`` specifying the document you want @@ -743,8 +743,8 @@ following guides: API Documentation ~~~~~~~~~~~~~~~~~ -To learn more about any of the methods or types discussed in this -guide used for collection bulk writes, see the following API documentation: +To learn more about the methods or types used for collection bulk +writes, see the following API documentation: - `Collection.BulkWrite() <{+api+}/mongo#Collection.BulkWrite>`__ - `BulkWriteOptions <{+api+}/mongo/options#BulkWriteOptions>`__ @@ -756,8 +756,8 @@ guide used for collection bulk writes, see the following API documentation: - `NewDeleteOneModel() <{+api+}/mongo#NewDeleteOneModel>`__ - `NewDeleteManyModel() <{+api+}/mongo#NewDeleteManyModel>`__ -To learn more about any of the methods or types discussed in this -guide used for client bulk writes, see the following API documentation: +To learn more about the methods or types used for client bulk writes, +see the following API documentation: - `Client.BulkWrite() <{+api+}/mongo#Client.BulkWrite>`__ - `ClientBulkWriteOptions <{+api+}/mongo/options#ClientBulkWriteOptions>`__ From 51a35d1ef000cbf513868047cfa2710dc4056756 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 14 Mar 2025 15:52:03 -0400 Subject: [PATCH 10/16] whats new --- source/whats-new.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/source/whats-new.txt b/source/whats-new.txt index b2957ed1..2756b57b 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -26,6 +26,7 @@ What's New Learn what's new in: +* :ref:`Version 2.1 ` * :ref:`Version 2.0 ` * :ref:`Version 1.17 ` * :ref:`Version 1.16 ` @@ -36,6 +37,22 @@ Learn what's new in: * :ref:`Version 1.12.1 ` * :ref:`Version 1.12 ` +.. _golang-version-2.1: + +What's New in 2.1 +----------------- + +This release includes the following improvements and fixes: + +- Adds a new bulk write API that allows you to perform + insert, update, and delete operations on multiple databases and collections + in one request. To learn more, see the :ref:`golang-bulk` guide. + +- Adds the ``bson.Vector`` type, which improves the efficiency of Atlas + Vector Search queries. + +.. TODO: add link to Atlas Vector search page + .. _golang-version-2.0: What's New in 2.0 From 0b8a0e837baee07d322cb096ebf9e97b18b0003d Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 14 Mar 2025 15:54:05 -0400 Subject: [PATCH 11/16] link --- source/whats-new.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index a5606c98..3fefdb89 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -51,7 +51,8 @@ and fixes: - Introduces the new `Client.BulkWrite <{+api+}/mongo#Client.BulkWrite>`__ method, enabling clients to perform multiple insert, update, and delete operations across - multiple databases and collections in a single request. + multiple databases and collections in a single request. To learn more, see the + :ref:`golang-bulk` guide. - Introduces the new `bson.Vector <{+api+}/bson#Vector>`__ type to make inserting and querying vector data by using :atlas:`Atlas Vector Search ` From fd73034df76439d3d0bb69992d4150f3c811e2d9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 14 Mar 2025 15:55:24 -0400 Subject: [PATCH 12/16] wording --- source/fundamentals/crud/write-operations/bulk.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index f31641b9..dcd83d1a 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -22,8 +22,8 @@ in a single method. The ``Collection`` and ``Client`` classes both provide a ``BulkWrite()`` method. You can use the ``Collection.BulkWrite()`` method to perform -multiple write operations on a single collection. When calling -the ``Client.BulkWrite()`` method, you can perform bulk writes across +multiple write operations on a single collection. You can use the +``Client.BulkWrite()`` method to perform bulk writes across multiple namespaces. In MongoDB, a namespace consists of a database name and a collection name. From ffa48a0622e621ef8f7d91abb95d27594a694ed6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 17 Mar 2025 13:13:53 -0400 Subject: [PATCH 13/16] fix merge error --- source/whats-new.txt | 4 ---- 1 file changed, 4 deletions(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index 3fefdb89..1e126ac9 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -26,11 +26,7 @@ What's New Learn what's new in: -<<<<<<< HEAD -* :ref:`Version 2.1 ` -======= * :ref:`Version 2.1 ` ->>>>>>> upstream/master * :ref:`Version 2.0 ` * :ref:`Version 1.17 ` * :ref:`Version 1.16 ` From c4b0bed1d60fc692ae8556536de4544a3a0e5cb3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 17 Mar 2025 17:42:18 -0400 Subject: [PATCH 14/16] tech review --- .../fundamentals/crud/write-operations/bulk.txt | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index dcd83d1a..0c45aa77 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -15,7 +15,7 @@ Bulk Operations Overview -------- -In this guide, you can learn how to use {+driver-short+} to +In this guide, you can learn how to use the {+driver-long+} to perform **bulk operations**. Bulk operations reduce the number of calls to the server by performing multiple write operations in a single method. @@ -265,6 +265,17 @@ following methods: - | Specifies whether the operation can opt-out of document level validation. | Default: ``false`` + * - ``SetComment()`` + - | Specifies a comment to attach to the operation. + | Default: ``nil`` + + * - ``SetLet()`` + - | Specifies a document with a list of values to improve operation readability. Values + must be constant or closed expressions that don't reference document fields. For more + information, see the :manual:`let statement + ` in the {+mdb-server+} manual. + | Default: ``nil`` + * - ``SetOrdered()`` - | Specifies whether the driver stops performing write operations after an error occurs. | Default: ``true`` @@ -302,6 +313,9 @@ The ``BulkWriteResult`` type contains the following properties: * - ``UpsertedIDs`` - A map of an operation index to the ``_id`` of each :ref:`upserted ` document. + * - ``Acknowledged`` + - A boolean value that indicates whether the write operation was acknowledged. + Collection-Level Execution Order ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 7cb65023000140b798b51681d28420d8c6069433 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 18 Mar 2025 09:55:23 -0400 Subject: [PATCH 15/16] QH feedback 2 --- source/fundamentals/crud/write-operations/bulk.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 0c45aa77..4a602140 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -624,9 +624,11 @@ following methods: | Default: ``nil`` * - ``SetLet()`` - - | Specifies parameters for update and delete operations, which improves command - readability by separating the variables from the query text. - | Default: none + - | Specifies a document with a list of values to improve operation readability. Values + must be constant or closed expressions that don't reference document fields. For more + information, see the :manual:`let statement + ` in the {+mdb-server+} manual. + | Default: ``nil`` * - ``SetWriteConcern()`` - | Specifies the write concern for the operations. From c9e1022b9656ea9f3244c767e8eb96f3faca8be9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 31 Mar 2025 09:46:58 -0400 Subject: [PATCH 16/16] let links --- source/fundamentals/crud/write-operations/bulk.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 4a602140..63756523 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -272,8 +272,9 @@ following methods: * - ``SetLet()`` - | Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more - information, see the :manual:`let statement - ` in the {+mdb-server+} manual. + information, see the ``let`` field for the :manual:`delete + ` and :manual:`update + ` commands in the {+mdb-server+} manual. | Default: ``nil`` * - ``SetOrdered()`` @@ -626,8 +627,10 @@ following methods: * - ``SetLet()`` - | Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more - information, see the :manual:`let statement - ` in the {+mdb-server+} manual. + information, see the ``let`` field for the :manual:`delete + ` and :manual:`update + ` commands in the {+mdb-server+} + manual. | Default: ``nil`` * - ``SetWriteConcern()``