1+ .. _golang-replacement-document:
2+ .. _golang-replace:
3+
14=================
25Replace Documents
36=================
@@ -15,4 +18,113 @@ Replace Documents
1518.. meta::
1619 :keywords: code example, go, write, add data, change
1720
18- .. TODO
21+ Overview
22+ --------
23+
24+ In this guide, you can learn how to use the {+driver-short+} to perform a replace
25+ operation on a document in a MongoDB collection. A replace operation performs
26+ differently than an update operation. An update operation
27+ modifies only the specified fields in a target document. A replace operation removes
28+ all fields in the target document and replaces them with new ones.
29+
30+ Parameters
31+ ----------
32+
33+ ``ReplaceOne()`` expects a **replacement document**, which is the document
34+ that you want to take the place of an existing document. Replacement
35+ documents use the following format:
36+
37+ .. code-block:: go
38+
39+ bson.D{{"<field>", "<value>"}, {"<field>", "<value>"}, ... }
40+
41+ Return Values
42+ -------------
43+
44+ ``ReplaceOne()`` returns an ``UpdateResult`` type that
45+ contains information about the replace operation if the operation is
46+ successful. The ``UpdateResult`` type contains the following properties:
47+
48+ .. list-table::
49+ :widths: 30 70
50+ :header-rows: 1
51+
52+ * - Property
53+ - Description
54+
55+ * - ``MatchedCount``
56+ - The number of documents matched by the filter
57+
58+ * - ``ModifiedCount``
59+ - The number of documents modified by the operation
60+
61+ * - ``UpsertedCount``
62+ - The number of documents upserted by the operation
63+
64+ * - ``UpsertedID``
65+ - The ``_id`` of the upserted document, or ``nil`` if there is none
66+
67+ If multiple documents match the query filter passed to ``ReplaceOne()``,
68+ the method selects and replaces the first matched document. Your replace
69+ operation fails if no documents match the query filter.
70+
71+ Example
72+ -------
73+
74+ The following document describes a kitchen item:
75+
76+ .. code-block:: json
77+ :copyable: false
78+
79+ {
80+ "_id" : 2056,
81+ "item" : "Mug",
82+ "brand" : "Simply Ceramics",
83+ "price" : 2.99,
84+ "material" : "Glass"
85+ }
86+
87+ The following example uses the ``ReplaceOne()`` method to substitute
88+ this document with one that contains an ``item`` field with a
89+ value of "Cup" and a ``quantity`` field with a value of 107:
90+
91+ .. io-code-block::
92+ :copyable: true
93+
94+ .. input::
95+ :language: go
96+
97+ filter := bson.D{{"_id", 2056}}
98+ replacement := bson.D{{"item", "Cup"}, {"quantity", 107}}
99+
100+ result, err := collection.ReplaceOne(context.TODO(), filter, replacement)
101+ fmt.Printf("Documents matched: %v\n", result.MatchedCount)
102+ fmt.Printf("Documents replaced: %v\n", result.ModifiedCount)
103+
104+ .. output::
105+ :language: none
106+ :visible: false
107+
108+ Documents matched: 1
109+ Documents replaced: 1
110+
111+ The replaced document contains the contents of the replacement document
112+ and the immutable ``_id`` field as follows:
113+
114+ .. code-block:: json
115+ :copyable: false
116+
117+ {
118+ "_id" : 2056,
119+ "item" : "Cup",
120+ "quantity" : 107
121+ }
122+
123+ API Documentation
124+ -----------------
125+
126+ To learn more about any of the methods or types discussed in this
127+ guide, see the following API Documentation:
128+
129+ - `ReplaceOne() <{+api+}/mongo#Collection.ReplaceOne>`__
130+ - `UpdateResult <{+api+}/mongo#UpdateResult>`__
0 commit comments