From 5168af9db320e145150b448b2871c555a48e70b2 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 10 Jun 2025 20:11:06 -0400 Subject: [PATCH 01/12] DOCSP-49976 Update Documents --- source/crud/query/retrieve.txt | 6 +-- source/crud/update.txt | 41 +++++++++++++++++-- .../code-snippets/updateMany.go | 2 +- 3 files changed, 41 insertions(+), 8 deletions(-) diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 4087759c..84b96a3d 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -130,7 +130,7 @@ following methods: .. _golang-find-example: Find Example -```````````` +------------ The following example passes a context, filter, and ``FindOptions`` to the ``Find()`` method, which performs the following actions: @@ -158,7 +158,7 @@ the ``Find()`` method, which performs the following actions: .. _golang-find-one-example: Find One Example -```````````````` +---------------- The following example passes a context, filter, and ``FindOneOptions`` to the ``FindOne()`` method, which performs the following actions: @@ -185,7 +185,7 @@ to the ``FindOne()`` method, which performs the following actions: .. _golang-find-one-by-id: Find One by ObjectId Example -```````````````````````````` +---------------------------- This example defines an ``id`` variable with a value of type ``ObjectId`` and uses ``id`` to specify a query filter. The filter matches a document diff --git a/source/crud/update.txt b/source/crud/update.txt index 47e49fbb..1e62fcc8 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -2,7 +2,7 @@ .. _golang-update: ================ -Modify Documents +Update Documents ================ .. facet:: @@ -150,8 +150,8 @@ changes. See our :ref:`upsert guide ` to learn how to insert a new document if no documents match the query filter. -Example -``````` +UpdateOne() Example +------------------- The following document describes an employee: @@ -167,7 +167,7 @@ The following document describes an employee: ... } -The following example uses the ``UpdateByID()`` method to: +The following example uses the ``UpdateOne()`` method to: - Match the document where the ``_id`` value is 2158. - Set the ``name`` field to "Mary Wollstonecraft Shelley" and the @@ -209,6 +209,39 @@ The following shows the updated document resulting from the preceding update ope ... } +UpdateMany() Example +-------------------- + +The following example uses the ``listingsAndReviews`` collection in the +``sample_airbnb`` dataset from the :atlas:`Atlas sample datasets `. +The example performs the following on the ``listingsAndReviews`` collection: + +- Matches documents in which the market field of the address subdocument, ``address.market`` is "Sydney" +- Updates the ``price`` in the matched documents by 1.15 times + +.. literalinclude:: /includes/usage-examples/code-snippets/updateMany.go + :start-after: begin updatemany + :end-before: end updatemany + :emphasize-lines: 9 + :language: go + :copyable: + :dedent: + +After you run the example, you can find the following updated +documents in the ``listingsAndReviews`` collection: + +.. code-block:: json + :copyable: false + + // results truncated + ... + { "_id" : "10091713", ... , "name" : "Surry Hills Studio", ... , "price" : 181.00, ... }, + { "_id" : "9908871", ... , "name" : "Family friendly beach house", ... , "price" : 751.00, ... }, + { "_id" : "20989061", ... , "name" : "Big and sunny Narraben room", ... , "price" : 60.00, ... }, + ... + +For an example on how to find multiple documents, see :ref:`golang-find-example`. + .. _golang-replacement-document: Replace diff --git a/source/includes/usage-examples/code-snippets/updateMany.go b/source/includes/usage-examples/code-snippets/updateMany.go index 1acf729b..7e8578a7 100644 --- a/source/includes/usage-examples/code-snippets/updateMany.go +++ b/source/includes/usage-examples/code-snippets/updateMany.go @@ -46,10 +46,10 @@ func main() { if err != nil { panic(err) } - // end updatemany // Prints the number of updated documents fmt.Printf("Documents updated: %v\n", result.ModifiedCount) + // end updatemany // When you run this file for the first time, it should print: // Number of documents replaced: 609 From a53a8c65419b253cbbc2eba7d89e58939fef990a Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 10 Jun 2025 20:26:45 -0400 Subject: [PATCH 02/12] edits --- snooty.toml | 1 + source/crud/update.txt | 134 +++-------------------------------------- 2 files changed, 11 insertions(+), 124 deletions(-) diff --git a/snooty.toml b/snooty.toml index 12ebd493..3330ac44 100644 --- a/snooty.toml +++ b/snooty.toml @@ -3,6 +3,7 @@ title = "Go Driver" toc_landing_pages = [ "/connect", "/crud", + "/crud/update", "/monitoring-and-logging", "/security", "/security/authentication", diff --git a/source/crud/update.txt b/source/crud/update.txt index 1e62fcc8..60f3635d 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -29,13 +29,11 @@ Update Documents Overview -------- -In this guide, you can learn how to modify documents in MongoDB using -**update** and **replace** operations. +In this guide, you can learn how to update documents in MongoDB using +**update** operations. Update operations change the fields that you specify while leaving other -fields and values unchanged. Replace operations remove all existing fields -except for ``_id`` in a document and substitute the deleted fields with -the new fields and values you specify. +fields and values unchanged. In MongoDB, all methods to modify documents follow the same pattern: @@ -52,23 +50,19 @@ The pattern expects you to: * Specify the field and value changes. * Specify options, if you must modify the method behavior. -The driver provides the following methods to modify documents: +The driver provides the following methods to update documents: * ``UpdateByID()`` * ``UpdateOne()`` * ``UpdateMany()`` -* ``ReplaceOne()`` -* ``BulkWrite()`` *(not discussed in this guide)* -* ``FindOneAndUpdate()`` *(not discussed in this guide)* -* ``FindOneAndReplace()`` *(not discussed in this guide)* A Note About ``_id`` ~~~~~~~~~~~~~~~~~~~~ Each document in a MongoDB collection has a unique and immutable ``_id`` -field. You cannot use update and replace operations to change the -``_id`` field. If you attempt to change this field, the update and -replace methods return a ``WriteError``. +field. You cannot use update operations to change the +``_id`` field. If you attempt to change this field, the update +methods return a ``WriteError``. .. _golang-update-documents: @@ -151,7 +145,7 @@ See our :ref:`upsert guide ` to learn how to insert a new document if no documents match the query filter. UpdateOne() Example -------------------- +~~~~~~~~~~~~~~~~~~~ The following document describes an employee: @@ -210,7 +204,7 @@ The following shows the updated document resulting from the preceding update ope } UpdateMany() Example --------------------- +~~~~~~~~~~~~~~~~~~~~ The following example uses the ``listingsAndReviews`` collection in the ``sample_airbnb`` dataset from the :atlas:`Atlas sample datasets `. @@ -242,121 +236,14 @@ documents in the ``listingsAndReviews`` collection: For an example on how to find multiple documents, see :ref:`golang-find-example`. -.. _golang-replacement-document: - -Replace -------- - -Use the ``ReplaceOne()`` method to replace a single document. - -Parameters -~~~~~~~~~~ - -``ReplaceOne()`` expects a **replacement document**, which is the document -that you want to take the place of an existing document. Replacement -documents use the following format: - -.. code-block:: go - - bson.D{{"", ""}, {"", ""}, ... } - -Return Values -~~~~~~~~~~~~~ - -``ReplaceOne()`` returns an ``UpdateResult`` type that -contains information about the replace operation if the operation is -successful. The ``UpdateResult`` type contains the following properties: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Property - - Description - - * - ``MatchedCount`` - - The number of documents matched by the filter - - * - ``ModifiedCount`` - - The number of documents modified by the operation - - * - ``UpsertedCount`` - - The number of documents upserted by the operation - - * - ``UpsertedID`` - - The ``_id`` of the upserted document, or ``nil`` if there is none - -If multiple documents match the query filter passed to ``ReplaceOne()``, -the method selects and replaces the first matched document. Your replace -operation fails if no documents match the query filter. - -Example -``````` - -The following document describes a kitchen item: - -.. code-block:: json - :copyable: false - - { - "_id" : 2056, - "item" : "Mug", - "brand" : "Simply Ceramics", - "price" : 2.99, - "material" : "Glass" - } - -The following example uses the ``ReplaceOne()`` method to substitute -this document with one that contains an ``item`` field with a -value of "Cup" and a ``quantity`` field with a value of 107: - -.. io-code-block:: - :copyable: true - - .. input:: - :language: go - - filter := bson.D{{"_id", 2056}} - replacement := bson.D{{"item", "Cup"}, {"quantity", 107}} - - result, err := collection.ReplaceOne(context.TODO(), filter, replacement) - fmt.Printf("Documents matched: %v\n", result.MatchedCount) - fmt.Printf("Documents replaced: %v\n", result.ModifiedCount) - - .. output:: - :language: none - :visible: false - - Documents matched: 1 - Documents replaced: 1 - -The replaced document contains the contents of the replacement document -and the immutable ``_id`` field as follows: - -.. code-block:: json - :copyable: false - - { - "_id" : 2056, - "item" : "Cup", - "quantity" : 107 - } - Additional Information ---------------------- -For runnable examples of the update and replace operations, see the -following usage examples: - -- :ref:`golang-update-one` -- :ref:`golang-update-many` -- :ref:`golang-replacement-document` - To learn more about the operations mentioned, see the following guides: - :ref:`golang-query-document` -- :ref:`golang-upsert` +- :ref:`golang-retrieve` - :ref:`golang-compound-operations` - :manual:`Update Operators ` @@ -373,4 +260,3 @@ guide, see the following API Documentation: - `UpdateByID() <{+api+}/mongo#Collection.UpdateByID>`__ - `UpdateMany() <{+api+}/mongo#Collection.UpdateMany>`__ - `UpdateResult <{+api+}/mongo#UpdateResult>`__ -- `ReplaceOne() <{+api+}/mongo#Collection.ReplaceOne>`__ From d686c1b185b8909ba9a05616b540b0f943adff30 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 10 Jun 2025 20:46:56 -0400 Subject: [PATCH 03/12] retrieve ex fixes --- source/crud/query/retrieve.txt | 129 +++++++++++++++------------------ 1 file changed, 60 insertions(+), 69 deletions(-) diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 84b96a3d..c77fa962 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -59,6 +59,8 @@ Find Operations Use **find operations** to retrieve data from MongoDB. Find operations consist of the ``Find()`` and ``FindOne()`` methods. +.. _golang-find-example: + Find All Documents ~~~~~~~~~~~~~~~~~~ @@ -66,72 +68,6 @@ The ``Find()`` method expects you to pass a ``Context`` type and a query filter. The method returns *all* documents that match the filter as a ``Cursor`` type. -For an example that uses the ``Find()`` method, see the :ref:`golang-find-example` -section of this page. To learn how to access data by using a cursor, see -the :ref:`golang-cursor` guide. - -Find One Document -~~~~~~~~~~~~~~~~~ - -The ``FindOne()`` method expects you to pass a ``Context`` type and a -query filter. The method returns *the first document* that matches the -filter as a ``SingleResult`` type. - -For an example that uses the ``FindOne()`` method, see the -:ref:`golang-find-one-example` section of this page. For an example that -uses ``FindOne()`` and queries by using a specific ``ObjectId`` value, see -the :ref:`golang-find-one-by-id` section of this page. - -To learn how to access data from a ``SingleResult`` type, see -:ref:`golang-bson-unmarshalling` in the BSON guide. - -.. _golang-retrieve-options: - -Modify Behavior -~~~~~~~~~~~~~~~ - -You can modify the behavior of ``Find()`` and ``FindOne()`` by passing -in a ``FindOptions`` and ``FindOneOptions`` type respectively. If you -don't specify any options, the driver uses the default values for each -option. - -You can configure the commonly used options in both types with the -following methods: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Method - - Description - - * - ``SetCollation()`` - - | The type of language collation to use when sorting results. - | Default: ``nil`` - - * - ``SetLimit()`` - - | The maximum number of documents to return. - | Default: ``0`` - | This option is not available for ``FindOneOptions``. The - ``FindOne()`` method internally uses ``SetLimit(-1)``. - - * - ``SetProjection()`` - - | The fields to include in the returned documents. - | Default: ``nil`` - - * - ``SetSkip()`` - - | The number of documents to skip. - | Default: ``0`` - - * - ``SetSort()`` - - | The field and type of sort to order the matched documents. You can specify an ascending or descending sort. - | Default: none - -.. _golang-find-example: - -Find Example ------------- - The following example passes a context, filter, and ``FindOptions`` to the ``Find()`` method, which performs the following actions: @@ -155,10 +91,16 @@ the ``Find()`` method, which performs the following actions: {"item":"Sencha","rating":7,"date_ordered":"2009-11-18T05:00:00Z"} {"item":"Masala","rating":8,"date_ordered":"2009-12-01T05:00:00Z"} +To learn how to access data by using a cursor, see the :ref:`golang-cursor` guide. + .. _golang-find-one-example: -Find One Example ----------------- +Find One Document +~~~~~~~~~~~~~~~~~ + +The ``FindOne()`` method expects you to pass a ``Context`` type and a +query filter. The method returns *the first document* that matches the +filter as a ``SingleResult`` type. The following example passes a context, filter, and ``FindOneOptions`` to the ``FindOne()`` method, which performs the following actions: @@ -182,10 +124,17 @@ to the ``FindOne()`` method, which performs the following actions: {"item":"Masala","rating":9,"date_ordered":"2009-11-12T05:00:00Z"} +For an example that +uses ``FindOne()`` and queries by using a specific ``ObjectId`` value, see +the :ref:`golang-find-one-by-id` section of this page. + +To learn how to access data from a ``SingleResult`` type, see +:ref:`golang-bson-unmarshalling` in the BSON guide. + .. _golang-find-one-by-id: Find One by ObjectId Example ----------------------------- +```````````````````````````` This example defines an ``id`` variable with a value of type ``ObjectId`` and uses ``id`` to specify a query filter. The filter matches a document @@ -232,6 +181,48 @@ as parameters to the ``FindOne()`` method to perform the following actions: about the ``_id`` field, see the :ref:`_id Field ` section of the Insert a Document page. +.. _golang-retrieve-options: + +Modify Behavior +~~~~~~~~~~~~~~~ + +You can modify the behavior of ``Find()`` and ``FindOne()`` by passing +in a ``FindOptions`` and ``FindOneOptions`` type respectively. If you +don't specify any options, the driver uses the default values for each +option. + +You can configure the commonly used options in both types with the +following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``SetCollation()`` + - | The type of language collation to use when sorting results. + | Default: ``nil`` + + * - ``SetLimit()`` + - | The maximum number of documents to return. + | Default: ``0`` + | This option is not available for ``FindOneOptions``. The + ``FindOne()`` method internally uses ``SetLimit(-1)``. + + * - ``SetProjection()`` + - | The fields to include in the returned documents. + | Default: ``nil`` + + * - ``SetSkip()`` + - | The number of documents to skip. + | Default: ``0`` + + * - ``SetSort()`` + - | The field and type of sort to order the matched documents. You can specify an ascending or descending sort. + | Default: none + .. _golang-retrieve-aggregation: Aggregation Operations From 977725449450db14a8cb8c7f7b5e57d56e397e2f Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 10 Jun 2025 20:51:00 -0400 Subject: [PATCH 04/12] upsert edit --- source/crud/update/upsert.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/update/upsert.txt b/source/crud/update/upsert.txt index f9dc2949..2b58049c 100644 --- a/source/crud/update/upsert.txt +++ b/source/crud/update/upsert.txt @@ -85,7 +85,7 @@ method in the options of the following write operation methods: equivalent to passing ``false`` to the ``SetUpsert()`` method. Example -~~~~~~~ +------- The following example performs the following actions: From 4df22eefa5456a78047bc1764c8f50692956959b Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 10 Jun 2025 20:58:39 -0400 Subject: [PATCH 05/12] vale edit --- source/crud/query/retrieve.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index c77fa962..b08ecbf3 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -187,7 +187,7 @@ Modify Behavior ~~~~~~~~~~~~~~~ You can modify the behavior of ``Find()`` and ``FindOne()`` by passing -in a ``FindOptions`` and ``FindOneOptions`` type respectively. If you +in a ``FindOptions`` and ``FindOneOptions`` type. If you don't specify any options, the driver uses the default values for each option. From 2dee41048a7ffca4cb64dd2c1b07a37a5400b932 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 11 Jun 2025 16:26:45 -0400 Subject: [PATCH 06/12] headings --- source/crud/update.txt | 54 ++++++++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/source/crud/update.txt b/source/crud/update.txt index 60f3635d..dc1e76e0 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -1,5 +1,6 @@ .. _golang-change-document: .. _golang-update: +.. _golang-update-documents: ================ Update Documents @@ -56,28 +57,23 @@ The driver provides the following methods to update documents: * ``UpdateOne()`` * ``UpdateMany()`` -A Note About ``_id`` -~~~~~~~~~~~~~~~~~~~~ +Use the ``UpdateOne()`` or ``UpdateByID()`` method to update a single +document. + +Use the ``UpdateMany()`` method to update multiple documents. + +A Note About _id +~~~~~~~~~~~~~~~~~ Each document in a MongoDB collection has a unique and immutable ``_id`` field. You cannot use update operations to change the ``_id`` field. If you attempt to change this field, the update methods return a ``WriteError``. -.. _golang-update-documents: - -Update ------- - -Use the ``UpdateOne()`` or ``UpdateByID()`` method to update a single -document. - -Use the ``UpdateMany()`` method to update multiple documents. - .. _golang-update-document: Parameters -~~~~~~~~~~ +---------- Each method takes an **update document** that includes at least one **update operator**. The update operator specifies the type of update to perform. The update @@ -110,7 +106,7 @@ and descriptions `. `. Return Values -~~~~~~~~~~~~~ +------------- ``UpdateOne()``, ``UpdateByID()``, and ``UpdateMany()`` return an ``UpdateResult`` type that contains information about the update @@ -145,7 +141,7 @@ See our :ref:`upsert guide ` to learn how to insert a new document if no documents match the query filter. UpdateOne() Example -~~~~~~~~~~~~~~~~~~~ +------------------- The following document describes an employee: @@ -204,7 +200,7 @@ The following shows the updated document resulting from the preceding update ope } UpdateMany() Example -~~~~~~~~~~~~~~~~~~~~ +-------------------- The following example uses the ``listingsAndReviews`` collection in the ``sample_airbnb`` dataset from the :atlas:`Atlas sample datasets `. @@ -213,13 +209,25 @@ The example performs the following on the ``listingsAndReviews`` collection: - Matches documents in which the market field of the address subdocument, ``address.market`` is "Sydney" - Updates the ``price`` in the matched documents by 1.15 times -.. literalinclude:: /includes/usage-examples/code-snippets/updateMany.go - :start-after: begin updatemany - :end-before: end updatemany - :emphasize-lines: 9 - :language: go - :copyable: - :dedent: +.. io-code-block:: + :copyable: true + + .. input:: + :language: go + + .. literalinclude:: /includes/usage-examples/code-snippets/updateMany.go + :start-after: begin updatemany + :end-before: end updatemany + :emphasize-lines: 9 + :language: go + :copyable: + :dedent: + + .. output:: + :language: none + :visible: false + + Documents updated: 609 After you run the example, you can find the following updated documents in the ``listingsAndReviews`` collection: From 984cbd117802eb52a93d8c2f6c4c6917dc434678 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 11 Jun 2025 16:32:39 -0400 Subject: [PATCH 07/12] input format --- source/crud/update.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/source/crud/update.txt b/source/crud/update.txt index dc1e76e0..92488cc6 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -213,7 +213,6 @@ The example performs the following on the ``listingsAndReviews`` collection: :copyable: true .. input:: - :language: go .. literalinclude:: /includes/usage-examples/code-snippets/updateMany.go :start-after: begin updatemany From b626801cf4e1d2405094f55be069b29753e28b31 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 11 Jun 2025 16:39:09 -0400 Subject: [PATCH 08/12] revert output --- source/crud/update.txt | 31 ++++++++++--------------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/source/crud/update.txt b/source/crud/update.txt index 92488cc6..67352ce1 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -209,27 +209,16 @@ The example performs the following on the ``listingsAndReviews`` collection: - Matches documents in which the market field of the address subdocument, ``address.market`` is "Sydney" - Updates the ``price`` in the matched documents by 1.15 times -.. io-code-block:: - :copyable: true - - .. input:: - - .. literalinclude:: /includes/usage-examples/code-snippets/updateMany.go - :start-after: begin updatemany - :end-before: end updatemany - :emphasize-lines: 9 - :language: go - :copyable: - :dedent: - - .. output:: - :language: none - :visible: false - - Documents updated: 609 - -After you run the example, you can find the following updated -documents in the ``listingsAndReviews`` collection: +.. literalinclude:: /includes/usage-examples/code-snippets/updateMany.go + :start-after: begin updatemany + :end-before: end updatemany + :emphasize-lines: 9 + :language: go + :copyable: + :dedent: + +The following query updates 609 documents. After you run the example, you can +find the following updated documents in the ``listingsAndReviews`` collection: .. code-block:: json :copyable: false From 90f3dcd7dad8f22c11f34b9a44d033be1e5efa07 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 13 Jun 2025 15:04:57 -0400 Subject: [PATCH 09/12] edit code example and RR review --- source/crud/query/retrieve.txt | 2 +- source/crud/update.txt | 91 +++++++++++++++++----------------- 2 files changed, 46 insertions(+), 47 deletions(-) diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index b08ecbf3..be821e2a 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -187,7 +187,7 @@ Modify Behavior ~~~~~~~~~~~~~~~ You can modify the behavior of ``Find()`` and ``FindOne()`` by passing -in a ``FindOptions`` and ``FindOneOptions`` type. If you +a ``FindOptions`` or ``FindOneOptions`` instance. If you don't specify any options, the driver uses the default values for each option. diff --git a/source/crud/update.txt b/source/crud/update.txt index 67352ce1..70208208 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -30,7 +30,7 @@ Update Documents Overview -------- -In this guide, you can learn how to update documents in MongoDB using +In this guide, you can learn how to update documents in MongoDB by using **update** operations. Update operations change the fields that you specify while leaving other @@ -53,14 +53,9 @@ The pattern expects you to: The driver provides the following methods to update documents: -* ``UpdateByID()`` -* ``UpdateOne()`` -* ``UpdateMany()`` - -Use the ``UpdateOne()`` or ``UpdateByID()`` method to update a single -document. - -Use the ``UpdateMany()`` method to update multiple documents. +* ``UpdateByID()``: Updates a single document based on its ``_id``. +* ``UpdateOne()``: Updates a single document. +* ``UpdateMany()``: Updates multiple documents. A Note About _id ~~~~~~~~~~~~~~~~~ @@ -70,6 +65,11 @@ field. You cannot use update operations to change the ``_id`` field. If you attempt to change this field, the update methods return a ``WriteError``. +Sample Data +~~~~~~~~~~~ + + + .. _golang-update-document: Parameters @@ -98,8 +98,8 @@ and descriptions `. .. note:: Aggregation Pipelines in Update Operations - If you are using MongoDB Server version 4.2 or later, you can use aggregation - pipelines made up of a subset of aggregation stages in update operations. To learn more about + You can use aggregation pipelines made up of a subset of aggregation + stages in update operations. To learn more about the aggregation stages MongoDB supports in aggregation pipelines, see our tutorial on performing :manual:`updates with aggregation pipelines @@ -143,26 +143,31 @@ to learn how to insert a new document if no documents match the query filter. UpdateOne() Example ------------------- -The following document describes an employee: +The following example uses the ``listingsAndReviews`` collection in the +``sample_airbnb`` dataset from the :atlas:`Atlas sample datasets `. +The following document describes an airbnb listing: .. code-block:: json :copyable: false { - "_id" : 2158, - "name" : "Mary Shelley", - "department" : "Marketing", - "role" : "Marketing Analyst", - "bonus" : 2500, + "_id": "10006546", + "listing_url": "https://www.airbnb.com/rooms/10006546", + "name": "Ribeira Charming Duplex", + "summary": "Fantastic duplex apartment with three bedrooms, located in the historic area of Porto, Ribeira (Cube)...", + ... + "minimum_nights": "2", + "maximum_nights": "30", + ... + "accommodates": 8, ... } The following example uses the ``UpdateOne()`` method to: -- Match the document where the ``_id`` value is 2158. -- Set the ``name`` field to "Mary Wollstonecraft Shelley" and the - ``role`` field to "Marketing Director". -- Increment the value of the ``bonus`` field by 2000. +- Match the document where the ``_id`` value is ``"10006546"``. +- Set the ``name`` field to "Ribiera River View Duplex". +- Increment the value of the ``accommodates`` field by 1. .. io-code-block:: :copyable: true @@ -170,9 +175,9 @@ The following example uses the ``UpdateOne()`` method to: .. input:: :language: go - filter := bson.D{{"_id", 2158}} - update := bson.D{{"$set", bson.D{{"name", "Mary Wollstonecraft Shelley"}, - {"role", "Marketing Director"}}}, {"$inc", bson.D{{"bonus", 2000}}}} + filter := bson.D{{"_id", "10006546"}} + update := bson.D{{"$set", bson.D{{"name", "Ribiera River View Duplex"}}}, + {"$inc", bson.D{{"accomodates", 1}}}} result, err := collection.UpdateOne(context.TODO(), filter, update) fmt.Printf("Documents matched: %v\n", result.MatchedCount) @@ -191,11 +196,15 @@ The following shows the updated document resulting from the preceding update ope :copyable: false { - "_id" : 2158, - "name" : "Mary Wollstonecraft Shelley", - "department" : "Marketing", - "role" : "Marketing Director", - "bonus" : 4500, + "_id": "10006546", + "listing_url": "https://www.airbnb.com/rooms/10006546", + "name": "Ribeira River View Duplex", + "summary": "Fantastic duplex apartment with three bedrooms, located in the historic area of Porto, Ribeira (Cube)...", + ... + "minimum_nights": "2", + "maximum_nights": "30", + ... + "accommodates": 9, ... } @@ -203,11 +212,12 @@ UpdateMany() Example -------------------- The following example uses the ``listingsAndReviews`` collection in the -``sample_airbnb`` dataset from the :atlas:`Atlas sample datasets `. -The example performs the following on the ``listingsAndReviews`` collection: +``sample_airbnb`` dataset from the :atlas:`Atlas sample datasets `. -- Matches documents in which the market field of the address subdocument, ``address.market`` is "Sydney" -- Updates the ``price`` in the matched documents by 1.15 times +The following example uses the ``UpdateMany()`` method to: + +- Match documents in which the value of the ``address.market`` field is ``"Sydney"``. +- Multiply the ``price`` value in the matched documents by ``1.15`` .. literalinclude:: /includes/usage-examples/code-snippets/updateMany.go :start-after: begin updatemany @@ -217,20 +227,9 @@ The example performs the following on the ``listingsAndReviews`` collection: :copyable: :dedent: -The following query updates 609 documents. After you run the example, you can -find the following updated documents in the ``listingsAndReviews`` collection: - -.. code-block:: json - :copyable: false - - // results truncated - ... - { "_id" : "10091713", ... , "name" : "Surry Hills Studio", ... , "price" : 181.00, ... }, - { "_id" : "9908871", ... , "name" : "Family friendly beach house", ... , "price" : 751.00, ... }, - { "_id" : "20989061", ... , "name" : "Big and sunny Narraben room", ... , "price" : 60.00, ... }, - ... +The update operation updates ``609`` documents. -For an example on how to find multiple documents, see :ref:`golang-find-example`. +To learn more about how to retrieve multiple documents, see :ref:`golang-find-example`. Additional Information ---------------------- From ae2a718d4be878eea558ffc963d03460772bd556 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 13 Jun 2025 15:21:17 -0400 Subject: [PATCH 10/12] edit --- source/crud/update.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/update.txt b/source/crud/update.txt index 70208208..02240721 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -165,7 +165,7 @@ The following document describes an airbnb listing: The following example uses the ``UpdateOne()`` method to: -- Match the document where the ``_id`` value is ``"10006546"``. +- Match the document where the ``_id`` value is "10006546". - Set the ``name`` field to "Ribiera River View Duplex". - Increment the value of the ``accommodates`` field by 1. From 748aba1d736e74346ba48cf203f27c68a08a3a55 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 13 Jun 2025 15:25:17 -0400 Subject: [PATCH 11/12] Edit --- source/crud/update.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/crud/update.txt b/source/crud/update.txt index 02240721..5a6d1ef5 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -165,9 +165,9 @@ The following document describes an airbnb listing: The following example uses the ``UpdateOne()`` method to: -- Match the document where the ``_id`` value is "10006546". -- Set the ``name`` field to "Ribiera River View Duplex". -- Increment the value of the ``accommodates`` field by 1. +- Match the document where the ``_id`` value is ``"10006546"``. +- Set the ``name`` field to ``"Ribiera River View Duplex"``. +- Increment the value of the ``accommodates`` field by ``1``. .. io-code-block:: :copyable: true From 92f40c5ff582432555fae9e55259af2ca8bb9fad Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 16 Jun 2025 23:38:30 -0400 Subject: [PATCH 12/12] RR review --- source/crud/update.txt | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/source/crud/update.txt b/source/crud/update.txt index 5a6d1ef5..100be569 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -65,11 +65,6 @@ field. You cannot use update operations to change the ``_id`` field. If you attempt to change this field, the update methods return a ``WriteError``. -Sample Data -~~~~~~~~~~~ - - - .. _golang-update-document: Parameters @@ -101,9 +96,10 @@ and descriptions `. You can use aggregation pipelines made up of a subset of aggregation stages in update operations. To learn more about the aggregation stages MongoDB supports in - aggregation pipelines, see our tutorial on performing - :manual:`updates with aggregation pipelines - `. + aggregation pipelines, see the tutorial on performing + :manual:`Updates with Aggregation Pipeline + ` + tutorial in the Server Manual. Return Values ------------- @@ -137,7 +133,7 @@ the method selects and updates the first matched document. If no documents match the query filter, the update operation makes no changes. -See our :ref:`upsert guide ` +See the :ref:`upsert guide ` to learn how to insert a new document if no documents match the query filter. UpdateOne() Example