From 5755a9be66ed47d29e605048c694206335297c57 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 4 Jun 2025 14:40:24 -0400 Subject: [PATCH 1/4] DOCSP-49977 Replace One --- source/crud/update/replace.txt | 110 ++++++++++++++++++++++++++++++++- 1 file changed, 109 insertions(+), 1 deletion(-) diff --git a/source/crud/update/replace.txt b/source/crud/update/replace.txt index c2a43651..efa99338 100644 --- a/source/crud/update/replace.txt +++ b/source/crud/update/replace.txt @@ -1,3 +1,5 @@ +.. _golang-replacement-document: + ================= Replace Documents ================= @@ -15,4 +17,110 @@ Replace Documents .. meta:: :keywords: code example, go, write, add data, change -.. TODO \ No newline at end of file +Overview +-------- + +In this guide, you can learn how to use {+driver-short+} to perform a replace +operation on a document in a MongoDB collection. A replace operation performs +differently than an update operation. An update operation +modifies only the specified fields in a target document. A replace operation removes *all* fields +in the target document and replaces them with new ones. + +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 + } + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the `ReplaceOne() <{+api+}/mongo#Collection.ReplaceOne>`__ API Documentation. From 9b063419f77726202cf2012f958e2a50bb7c6d97 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 4 Jun 2025 14:53:36 -0400 Subject: [PATCH 2/4] add to TOC --- source/connect.txt | 4 ++-- source/crud/update.txt | 9 +++++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 5be7092e..f074f648 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -24,8 +24,8 @@ Connection Guide :titlesonly: :maxdepth: 1 - Create a MongoClient - Choose a Connection Target + Create a MongoClient + Choose a Connection Target Connection Options Connection Troubleshooting diff --git a/source/crud/update.txt b/source/crud/update.txt index bbbb7777..47e49fbb 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -19,7 +19,12 @@ Modify Documents :depth: 2 :class: singlecol -.. TODO edit +.. toctree:: + :caption: Update Documents + + Replace Documents + Update Arrays + Upsert Overview -------- @@ -312,7 +317,7 @@ following usage examples: - :ref:`golang-update-one` - :ref:`golang-update-many` -- :ref:`golang-replace` +- :ref:`golang-replacement-document` To learn more about the operations mentioned, see the following guides: From e402db0491584de69e79d84de243b3edbffc3293 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 4 Jun 2025 15:05:32 -0400 Subject: [PATCH 3/4] edit headings --- source/crud/update/replace.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/crud/update/replace.txt b/source/crud/update/replace.txt index efa99338..dc011ec3 100644 --- a/source/crud/update/replace.txt +++ b/source/crud/update/replace.txt @@ -20,14 +20,13 @@ Replace Documents Overview -------- -In this guide, you can learn how to use {+driver-short+} to perform a replace +In this guide, you can learn how to use the {+driver-short+} to perform a replace operation on a document in a MongoDB collection. A replace operation performs differently than an update operation. An update operation -modifies only the specified fields in a target document. A replace operation removes *all* fields -in the target document and replaces them with new ones. +modifies only the specified fields in a target document. A replace operation removes all fields in the target document and replaces them with new ones. Parameters -~~~~~~~~~~ +---------- ``ReplaceOne()`` expects a **replacement document**, which is the document that you want to take the place of an existing document. Replacement @@ -38,7 +37,7 @@ documents use the following format: bson.D{{"", ""}, {"", ""}, ... } Return Values -~~~~~~~~~~~~~ +------------- ``ReplaceOne()`` returns an ``UpdateResult`` type that contains information about the replace operation if the operation is @@ -68,7 +67,7 @@ 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: From a829be2fd5f5d721dd3e7f610752df616d1f07f9 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 6 Jun 2025 14:11:01 -0400 Subject: [PATCH 4/4] RR review --- source/crud/update/replace.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/source/crud/update/replace.txt b/source/crud/update/replace.txt index dc011ec3..3b65a7a3 100644 --- a/source/crud/update/replace.txt +++ b/source/crud/update/replace.txt @@ -1,4 +1,5 @@ .. _golang-replacement-document: +.. _golang-replace: ================= Replace Documents @@ -23,7 +24,8 @@ Overview In this guide, you can learn how to use the {+driver-short+} to perform a replace operation on a document in a MongoDB collection. A replace operation performs differently than an update operation. An update operation -modifies only the specified fields in a target document. A replace operation removes all fields in the target document and replaces them with new ones. +modifies only the specified fields in a target document. A replace operation removes +all fields in the target document and replaces them with new ones. Parameters ---------- @@ -122,4 +124,7 @@ API Documentation ----------------- To learn more about any of the methods or types discussed in this -guide, see the `ReplaceOne() <{+api+}/mongo#Collection.ReplaceOne>`__ API Documentation. +guide, see the following API Documentation: + +- `ReplaceOne() <{+api+}/mongo#Collection.ReplaceOne>`__ +- `UpdateResult <{+api+}/mongo#UpdateResult>`__