Skip to content

Commit b44cdfc

Browse files
mongoKartmongoKart
committed
wip
1 parent 6fd6830 commit b44cdfc

File tree

6 files changed

+1025
-925
lines changed

6 files changed

+1025
-925
lines changed

‎source/fundamentals/crud/write-operations/update.txt

+355-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Update Documents
1616
:values: reference
1717

1818
.. meta::
19-
:keywords: update, synchronous, asynchronous, bulk
19+
:keywords: synchronous, asynchronous
2020

2121
.. toctree::
2222
:caption: Update Documents
@@ -26,3 +26,357 @@ Update Documents
2626

2727
Overview
2828
--------
29+
30+
In this guide, you can learn how to use the {+driver-long+} to update
31+
values in MongoDB documents.
32+
33+
The {+driver-short+} provides the following methods to update values:
34+
35+
- ``UpdateOne()``: Updates one or more fields in a single document.
36+
- ``UpdateOneAsync()``: The asynchronous version of ``UpdateOne()``.
37+
- ``UpdateMany()``: Updates one or more fields in multiple documents.
38+
- ``UpdateManyAsync()``: The asynchronous version of ``UpdateMany()``.
39+
40+
The following sections describe these methods in more detail.
41+
42+
.. note:: Method Overloads
43+
44+
Many of the methods in this guide have multiple overloads. The examples
45+
in this guide use the simplest overload for demonstration purposes. For
46+
more information about the available overloads, see the
47+
:manual:`{+new-api-root+} API documentation </api-reference>`.
48+
49+
.. tip:: Interactive Lab
50+
51+
This page includes a short interactive lab that demonstrates how to
52+
modify data by using the ``UpdateManyAsync()`` method. You can complete this
53+
lab directly in your browser window without installing MongoDB or a code editor.
54+
55+
To start the lab, click the :guilabel:`Open Interactive Tutorial` button at the
56+
top of the page. To expand the lab to a full-screen format, click the
57+
full-screen button (:guilabel:`⛶`) in the top-right corner of the lab pane.
58+
59+
Methods and Parameters
60+
----------------------
61+
62+
The ``UpdateOne()``, ``UpdateOneAsync()``, ``UpdateMany()``, and ``UpdateManyAsync()``
63+
methods all accept the following parameters:
64+
65+
.. list-table::
66+
:widths: 30 70
67+
:header-rows: 1
68+
69+
* - Parameter
70+
- Description
71+
72+
* - ``filter``
73+
- An instance of the ``FilterDefinition`` class that specifies the documents to update.
74+
To learn how to create a query filter, see :ref:`csharp-specify-query`.
75+
76+
**Data Type:** `FilterDefinition<TDocument> <{+new-api-root+>/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__
77+
78+
* - ``update``
79+
- An instance of the ``UpdateDefinition`` class. This object specifies the kind of update
80+
operation, the fields to update, and the new value for each field. To learn how to
81+
create an ``UpdateDefinition`` object,
82+
see :ref:`csharp-update-fields` and :ref:`csharp-update-arrays`.
83+
84+
**Data Type:** `UpdateDefinition<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinition-1.html>`__
85+
86+
* - ``options``
87+
- *Optional.* An instance of the ``UpdateOptions`` class that specifies the
88+
configuration for the update operation. The default value is ``null``. To learn
89+
about the available options, see :ref:`csharp-update-options`.
90+
91+
**Data Type:** `UpdateOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateOptions.html>`__
92+
93+
* - ``cancellationToken``
94+
- *Optional.* A token that you can use to cancel the operation.
95+
96+
**Data type**: `CancellationToken <https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken>`__
97+
98+
Update Multiple Values
99+
----------------------
100+
101+
The ``UpdateOne()``, ``UpdateOneAsync()``, ``UpdateMany()``, and ``UpdateManyAsync()``
102+
methods each accept one ``UpdateDefinition`` object. The following sections describe how
103+
to multiple values in a single method call.
104+
105+
Combine Update Definitions
106+
~~~~~~~~~~~~~~~~~~~~~~~~~~
107+
108+
The ``Builders.Update.Combine()`` method lets you combine multiple ``UpdateDefinition``
109+
objects. This method accepts the following parameter:
110+
111+
.. list-table::
112+
:widths: 30 70
113+
:header-rows: 1
114+
115+
* - Parameter
116+
- Description
117+
118+
* - ``updates``
119+
- An array of update definitions to combine.
120+
121+
**Data Type:** ``UpdateDefinition<TDocument>[]``
122+
123+
The ``Combine()`` method returns a single ``UpdateDefinition`` object that defines
124+
multiple update operations.
125+
126+
The following code example uses the ``Combine()`` method to combine a
127+
:manual:`$set </reference/operator/update/set/#mongodb-update-up.-set>` operation and a
128+
:manual:`$pop </reference/operator/update/pop/#mongodb-update-up.-pop>`
129+
operation:
130+
131+
.. tabs::
132+
133+
.. tab:: UpdateOne (Synchronous)
134+
:tabid: update-one-sync
135+
136+
.. literalinclude:: /includes/code-examples/update-one/UpdateOne.cs
137+
:language: csharp
138+
:copyable: true
139+
:dedent:
140+
:start-after: // start-combine-sync
141+
:end-before: // end-combine-sync
142+
143+
.. tab:: UpdateOne (Asynchronous)
144+
:tabid: update-one-async
145+
146+
.. literalinclude:: /includes/code-examples/update-one/UpdateOne.cs
147+
:language: csharp
148+
:copyable: true
149+
:dedent:
150+
:start-after: // start-combine-async
151+
:end-before: // end-combine-async
152+
153+
.. tab:: UpdateMany (Synchronous)
154+
:tabid: update-many-sync
155+
156+
.. literalinclude:: /includes/code-examples/update-many/UpdateMany.cs
157+
:language: csharp
158+
:copyable: true
159+
:dedent:
160+
:start-after: // start-combine-sync
161+
:end-before: // end-combine-sync
162+
163+
.. tab:: UpdateMany (Asynchronous)
164+
:tabid: update-many-async
165+
166+
.. literalinclude:: /includes/code-examples/update-many/UpdateMany.cs
167+
:language: csharp
168+
:copyable: true
169+
:dedent:
170+
:start-after: // start-combine-async
171+
:end-before: // end-combine-async
172+
173+
Update Pipelines
174+
~~~~~~~~~~~~~~~~
175+
176+
Builders.Update.Pipeline is used to create an update pipeline for MongoDB update operations. An update pipeline allows you to specify a sequence of update stages that modify the documents in a collection. Each stage in the pipeline is an update operation that transforms the document in some way. This is similar to the aggregation pipeline but is used specifically for updates.
177+
This method accepts the following parameter:
178+
179+
.. list-table::
180+
:widths: 30 70
181+
:header-rows: 1
182+
183+
* - Parameter
184+
- Description
185+
186+
* - ``pipeline``
187+
- A ``PipelineDefinition`` instance that specifies the update pipeline.
188+
189+
**Data Type:** ``PipelineDefinition<TDocument, TDocument>``
190+
191+
.. tip:: Aggregation Pipelines in Update Operations
192+
193+
If you are using MongoDB Version 4.2 or later, you can use aggregation
194+
pipelines made up of a subset of aggregation stages in update operations. For
195+
more information on the aggregation stages MongoDB supports in
196+
aggregation pipelines used in update operations, see the tutorial about building
197+
:manual:`updates with aggregation pipelines </tutorial/update-documents-with-aggregation-pipeline/>`.
198+
199+
.. _csharp-update-options:
200+
201+
Customize the Update Operation
202+
------------------------------
203+
204+
To combine multiple update definitions into one, call the ``Builders.Update.Combine()`` method.
205+
This method accepts the following parameter:
206+
207+
The preceding update methods optionally accept an ``UpdateOptions`` object as an additional
208+
parameter. You can use this argument to configure the update operation.
209+
210+
The ``UpdateOptions`` class contains the following properties:
211+
212+
.. list-table::
213+
:widths: 30 70
214+
:header-rows: 1
215+
216+
* - Property
217+
- Description
218+
219+
* - ``ArrayFilters``
220+
- Specifies which array elements to modify for an update operation on an array field.
221+
See :manual:`the MongoDB server manual</reference/command/update/#update-elements-match-arrayfilters-criteria>`
222+
for more information.
223+
224+
**Data Type:** IEnumerable<`ArrayFilterDefinition <{+new-api-root+>/MongoDB.Driver/MongoDB.Driver.ArrayFilterDefinition.html>`__>
225+
226+
* - ``BypassDocumentValidation``
227+
- Specifies whether the update operation bypasses document validation. This lets you
228+
update documents that don't meet the schema validation requirements, if any
229+
exist. See :manual:`the MongoDB server manual</core/schema-validation/#schema-validation>`
230+
for more information on schema validation.
231+
232+
**Data Type:** ``bool?``
233+
234+
* - ``Collation``
235+
- Specifies the kind of language collation to use when sorting
236+
results. See :manual:`the MongoDB server manual</reference/collation/#std-label-collation>`
237+
for more information on collation.
238+
239+
**Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__
240+
241+
* - ``Comment``
242+
- Gets or sets the user-provided comment for the operation.
243+
See :manual:`the MongoDB server manual</reference/command/update/#command-fields>`
244+
for more information.
245+
246+
**Data Type:** `BsonValue <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonValue.html>`__
247+
248+
* - ``Hint``
249+
- Gets or sets the index to use to scan for documents.
250+
See :manual:`the MongoDB server manual</reference/command/update/#std-label-update-command-hint>`
251+
for more information.
252+
253+
**Data Type:** `BsonValue <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonValue.html>`__
254+
255+
* - ``IsUpsert``
256+
- Specifies whether the update operation performs an upsert operation if no
257+
documents match the query filter.
258+
See :manual:`the MongoDB server manual </reference/command/update/#std-label-update-command-upsert>`
259+
for more information.
260+
261+
**Data Type:** ``bool``
262+
263+
* - ``Let``
264+
- Gets or sets the let document.
265+
See :manual:`the MongoDB server manual </reference/command/update/#std-label-update-let-syntax>`
266+
for more information.
267+
268+
**Data Type:** `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__
269+
270+
Example
271+
~~~~~~~
272+
273+
The following code uses the ``UpdateMany()`` method to find all documents where the
274+
``borough`` field has the value "Manhattan", then updates the ``borough``
275+
value in these documents to "Manhattan (north)". Because the ``IsUpsert`` option is
276+
set to ``true``, the driver inserts a new document if the query filter doesn't
277+
match any existing documents.
278+
279+
.. io-code-block::
280+
:copyable: true
281+
282+
.. input::
283+
:language: csharp
284+
285+
var filter = Builders<Restaurant>.Filter
286+
.Eq(restaurant => restaurant.Borough, "Manhattan");
287+
288+
var update = Builders<Restaurant>.Update
289+
.Set(restaurant => restaurant.Borough, "Manhattan (north)");
290+
291+
UpdateOptions opts = new UpdateOptions()
292+
{
293+
Comment = new BsonString("Borough updated for C# Driver Fundamentals"),
294+
IsUpsert = true
295+
};
296+
297+
Console.WriteLine("Updating documents...");
298+
var result = _restaurantsCollection.UpdateMany(filter, update, opts);
299+
300+
Console.WriteLine($"Updated documents: {result.ModifiedCount}");
301+
Console.WriteLine($"Result acknowledged? {result.IsAcknowledged}");
302+
303+
.. output::
304+
:language: none
305+
:visible: false
306+
307+
Updating documents...
308+
Updated documents: 10259
309+
Result acknowledged? True
310+
311+
Return Value
312+
------------
313+
314+
The ``UpdateOne()`` and ``UpdateMany()`` methods return an ``UpdateResult``
315+
object. The ``UpdateOneAsync()`` and ``UpdateManyAsync()`` methods return an asynchronous
316+
version of this type, a ``Task<UpdateResult>`` object.
317+
The ``UpdateResult`` class contains the following properties:
318+
319+
.. list-table::
320+
:widths: 30 70
321+
:header-rows: 1
322+
323+
* - Property
324+
- Description
325+
326+
* - ``IsAcknowledged``
327+
- Indicates whether the replace operation was acknowledged by MongoDB.
328+
329+
**Data Type:** ``bool``
330+
331+
* - ``IsModifiedCountAvailable``
332+
- Indicates whether you can read the count of replaced records on the
333+
``ReplaceOneResult``.
334+
335+
**Data Type:** ``bool``
336+
337+
* - ``MatchedCount``
338+
- The number of documents that matched the query filter, regardless of
339+
whether one was replaced.
340+
341+
**Data Type:** ``long``
342+
343+
* - ``ModifiedCount``
344+
- The number of documents replaced by the replace operation.
345+
346+
**Data Type:** ``long``
347+
348+
* - ``UpsertedId``
349+
- The ID of the document that was upserted in the database, if the driver
350+
performed an upsert.
351+
352+
**Data Type:** `BsonValue <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonValue.html>`__
353+
354+
Additional Information
355+
----------------------
356+
357+
For runnable examples of the update operations, see the following usage
358+
examples:
359+
360+
- :ref:`csharp-update-one`
361+
- :ref:`csharp-update-many`
362+
363+
To learn more about creating query filters, see the :ref:`csharp-specify-query` guide.
364+
365+
API Documentation
366+
~~~~~~~~~~~~~~~~~
367+
368+
To learn more about any of the methods or types discussed in this
369+
guide, see the following API documentation:
370+
371+
* `UpdateOne() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateOne.html>`__
372+
* `UpdateOneAsync() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateOneAsync.html>`__
373+
* `UpdateMany() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateMany.html>`__
374+
* `UpdateManyAsync() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateManyAsync.html>`__
375+
* `UpdateOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateOptions.html>`__
376+
* `UpdateResult <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateResult.html>`__
377+
378+
.. _csharp-update-instruqt-lab:
379+
380+
.. instruqt:: /mongodb-docs/tracks/update-a-document---c-net-driver?token=em_69t_l-j0BC_en7Uy
381+
:title: UpdateManyAsync() Lesson
382+
:drawer:

0 commit comments

Comments
 (0)