Skip to content

Commit e9c1d38

Browse files
mongoKartmongoKart
committed
wip
1 parent 2c0e416 commit e9c1d38

File tree

3 files changed

+191
-66
lines changed

3 files changed

+191
-66
lines changed

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

Lines changed: 157 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -20,52 +20,22 @@ Update Arrays
2020
Overview
2121
--------
2222

23-
On this page, you can learn how to use the {+driver-long+} to update array
24-
fields in MongoDB documents. This page describes how to create ``UpdateDefinition<TDocument>``
25-
objects that specify the update operations you want to perform on array fields.
26-
You can pass these objects to the update methods described on the
27-
:ref:`<csharp-update-documents>` page.
23+
On this page, you can learn how to create ``UpdateDefinition`` objects for array fields.
24+
An ``UpdateDefinition`` object specifies the kind of update operation to perform, the
25+
fields to update, and the new value for each field, if applicable.
2826

2927
The {+driver-short+} supports the array update operators and modifiers described in the
3028
:manual:`{+mdb-server+} manual </reference/operator/update/#array>`.
31-
To specify an update operation, call the corresponding method from the ``Builders.Update``
32-
property. The following sections describe these methods in more detail.
29+
To create an ``UpdateDefinition`` object for one of these operators, call the corresponding
30+
method from the ``Builders.Update`` property.
31+
The following sections describe these methods in more detail.
3332

34-
.. note:: Method Overloads
33+
After you create an ``UpdateDefinition``, pass it to one of the update methods
34+
described on the :ref:`<csharp-update-documents>` page.
3535

36-
Many of the methods on this page have multiple overloads. The examples
37-
in this guide show only one overload for each method. For
38-
more information about the available overloads, see the
39-
:manual:`{+new-api-root+} API documentation </api-reference>`.
36+
.. include:: /includes/method-overloads.rst
4037

41-
Sample Data
42-
~~~~~~~~~~~
43-
44-
The examples in this guide use the ``restaurants`` collection
45-
from the ``sample_restaurants`` database. The documents in this
46-
collection use the following ``Restaurant``, ``Address``, and ``GradeEntry``
47-
classes as models:
48-
49-
.. literalinclude:: /includes/code-examples/Restaurant.cs
50-
:language: csharp
51-
:copyable:
52-
:dedent:
53-
54-
.. literalinclude:: /includes/code-examples/Address.cs
55-
:language: csharp
56-
:copyable:
57-
:dedent:
58-
59-
.. literalinclude:: /includes/code-examples/GradeEntry.cs
60-
:language: csharp
61-
:copyable:
62-
:dedent:
63-
64-
.. include:: /includes/convention-pack-note.rst
65-
66-
This collection is from the :atlas:`sample datasets </sample-data>` provided
67-
by Atlas. See the :ref:`<csharp-quickstart>` to learn how to create a free MongoDB cluster
68-
and load this sample data.
38+
.. include:: /includes/atlas-sample-data.rst
6939

7040
Add One Value
7141
-------------
@@ -90,35 +60,64 @@ This method accepts the following parameters:
9060

9161
**Data Type:** ``TItem``
9262

93-
The following code example pushes a new ``GradeEntry`` object into the ``Grades``
94-
array in the matching document. Select the :guilabel:`Synchronous` or
95-
:guilabel:`Asynchronous` tab to see the corresponding code.
63+
The following code example uses the ``Push()`` method to add a new ``GradeEntry`` object
64+
to the ``Grades`` array in the matching documents:
9665

9766
.. tabs::
9867

99-
.. tab:: Synchronous
100-
:tabid: update-one-array-sync
68+
.. tab:: UpdateOne (Sync)
69+
:tabid: update-one-push-sync
10170

102-
.. literalinclude:: /includes/code-examples/update-one/UpdateOne.cs
71+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
10372
:language: csharp
10473
:copyable: true
10574
:dedent:
106-
:start-after: // start-update-one-array
107-
:end-before: // end-update-one-array
75+
:start-after: // start-update-one-push
76+
:end-before: // end-update-one-push
10877

109-
.. tab:: Asynchronous
110-
:tabid: update-one-array-async
78+
.. tab:: UpdateOne (Async)
79+
:tabid: update-one-push-async
11180

112-
.. literalinclude:: /includes/code-examples/update-one/UpdateOne.cs
81+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
11382
:language: csharp
11483
:copyable: true
11584
:dedent:
116-
:start-after: // start-update-one-array-async
117-
:end-before: // end-update-one-array-async
85+
:start-after: // start-update-one-push-async
86+
:end-before: // end-update-one-push-async
87+
88+
.. tab:: UpdateMany (Sync)
89+
:tabid: update-many-push-sync
90+
91+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
92+
:language: csharp
93+
:copyable: true
94+
:dedent:
95+
:start-after: // start-update-many-push
96+
:end-before: // end-update-many-push
97+
98+
.. tab:: UpdateMany (Async)
99+
:tabid: update-many-push-async
100+
101+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
102+
:language: csharp
103+
:copyable: true
104+
:dedent:
105+
:start-after: // start-update-many-push-async
106+
:end-before: // end-update-many-push-async
107+
108+
.. tip:: Configure the Push Operation
109+
110+
To add a value at a specific position in an array, or to sort or slice the array after
111+
updating it, call the ``PushEach()`` method instead.
112+
TODO: link this
118113

119114
To add one value to the end of an array, *but only if it doesn't already exist in the array*,
120-
call the ``Builders.Update.AddToSet()`` method.
121-
This method accepts the following parameters:
115+
call the ``Builders.Update.AddToSet()`` method.
116+
{+mdb-server+} determines whether the value already exists in the array by
117+
comparing the value's BSON representation to the BSON representation of each
118+
other element in the array.
119+
120+
The ``AddToSet()`` method accepts the following parameters:
122121

123122
.. list-table::
124123
:widths: 30 70
@@ -137,13 +136,97 @@ This method accepts the following parameters:
137136

138137
**Data Type:** ``TItem``
139138

140-
The following code example pushes a new ``GradeEntry`` object into the ``Grades``
141-
array in the matching document. Select the :guilabel:`Synchronous` or
142-
:guilabel:`Asynchronous` tab to see the corresponding code.
139+
The following code example tries to use the ``AddToSet()`` method to re-add the first
140+
``GradeEntry`` object to the ``Grades`` array in the matching documents. Because
141+
the value already exists in the array, the update operation does nothing.
143142

144-
.. tip:: Specify a Position
145-
146-
To add a value at a specific position in an array, call the ``PushEach()`` method.
143+
.. tabs::
144+
145+
.. tab:: UpdateOne (Sync)
146+
:tabid: update-one-addtoset-sync
147+
148+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
149+
:language: csharp
150+
:copyable: true
151+
:dedent:
152+
:start-after: // start-update-one-addtoset
153+
:end-before: // end-update-one-addtoset
154+
155+
.. tab:: UpdateOne (Async)
156+
:tabid: update-one-addtoset-async
157+
158+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
159+
:language: csharp
160+
:copyable: true
161+
:dedent:
162+
:start-after: // start-update-one-addtoset-async
163+
:end-before: // end-update-one-addtoset-async
164+
165+
.. tab:: UpdateMany (Sync)
166+
:tabid: update-many-addtoset-sync
167+
168+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
169+
:language: csharp
170+
:copyable: true
171+
:dedent:
172+
:start-after: // start-update-many-addtoset
173+
:end-before: // end-update-many-addtoset
174+
175+
.. tab:: UpdateMany (Async)
176+
:tabid: update-many-addtoset-async
177+
178+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
179+
:language: csharp
180+
:copyable: true
181+
:dedent:
182+
:start-after: // start-update-many-addtoset-async
183+
:end-before: // end-update-many-addtoset-async
184+
185+
The following code example uses the ``PushEach()`` method to add two new ``GradeEntry``
186+
objects to the start of the ``Grades`` array. It then sorts the array elements in
187+
descending order by the values of their ``Score`` fields.
188+
189+
.. tabs::
190+
191+
.. tab:: UpdateOne (Sync)
192+
:tabid: update-one-pusheach-sync
193+
194+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
195+
:language: csharp
196+
:copyable: true
197+
:dedent:
198+
:start-after: // start-update-one-pusheach
199+
:end-before: // end-update-one-pusheach
200+
201+
.. tab:: UpdateOne (Async)
202+
:tabid: update-one-pusheach-async
203+
204+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
205+
:language: csharp
206+
:copyable: true
207+
:dedent:
208+
:start-after: // start-update-one-pusheach-async
209+
:end-before: // end-update-one-pusheach-async
210+
211+
.. tab:: UpdateMany (Sync)
212+
:tabid: update-many-pusheach-sync
213+
214+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
215+
:language: csharp
216+
:copyable: true
217+
:dedent:
218+
:start-after: // start-update-many-pusheach
219+
:end-before: // end-update-many-pusheach
220+
221+
.. tab:: UpdateMany (Async)
222+
:tabid: update-many-pusheach-async
223+
224+
.. literalinclude:: /includes/code-examples/UpdateArrays.cs
225+
:language: csharp
226+
:copyable: true
227+
:dedent:
228+
:start-after: // start-update-many-pusheach-async
229+
:end-before: // end-update-many-pusheach-async
147230

148231
Add Multiple Values
149232
-------------------
@@ -169,20 +252,23 @@ This method accepts the following parameters:
169252
**Data Type:** ``IEnumerable<TItem>``
170253

171254
* - ``slice``
172-
- The number of elements to keep in the array. If the value is negative, the
173-
method keeps the specified number of elements from the end of the array.
255+
- The number of elements to keep in the array, counted from the start of the array
256+
after updates. If the value is negative,
257+
the method keeps the specified number of elements from the end of the array.
174258

175259
**Data Type:** ``int?``
176260

177261
* - ``position``
178-
- The position in the array at which to add the values.
262+
- The position in the array at which to add the values. By default, the method
263+
adds the values to the end of the array.
179264

180265
**Data Type:** ``int?``
181266

182267
* - ``sort``
183-
- The values to add to the array field.
268+
- A ``SortDefinition`` object that specifies how the driver sorts the array elements
269+
after adding the new values.
184270

185-
**Data Type:** `SortDefinition<TItem> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinition-1.html>`__
271+
**Data Type:** `SortDefinition<TItem> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinition-1.html>`__
186272

187273
To add multiple values to an array only if they aren't there, call the
188274
``Builders.Update.AddToSetEach()`` method. This method accepts the following parameters:
@@ -204,6 +290,11 @@ To add multiple values to an array only if they aren't there, call the
204290

205291
**Data Type:** ``IEnumerable<TItem>``
206292

293+
.. tip::
294+
295+
If you call the ``AddToSet()`` method with more than one value, the driver automatically
296+
performs the operation as if you called the ``AddToSetEach()`` method.
297+
207298
Remove Values
208299
-------------
209300

‎source/includes/atlas-sample-data.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
Sample Data
2+
~~~~~~~~~~~
3+
4+
The examples in this guide use the ``restaurants`` collection
5+
from the ``sample_restaurants`` database. The documents in this
6+
collection use the following ``Restaurant``, ``Address``, and ``GradeEntry``
7+
classes as models:
8+
9+
.. literalinclude:: /includes/code-examples/Restaurant.cs
10+
:language: csharp
11+
:copyable:
12+
:dedent:
13+
14+
.. literalinclude:: /includes/code-examples/Address.cs
15+
:language: csharp
16+
:copyable:
17+
:dedent:
18+
19+
.. literalinclude:: /includes/code-examples/GradeEntry.cs
20+
:language: csharp
21+
:copyable:
22+
:dedent:
23+
24+
.. include:: /includes/convention-pack-note.rst
25+
26+
This collection is from the :atlas:`sample datasets </sample-data>` provided
27+
by Atlas. See the :ref:`<csharp-quickstart>` to learn how to create a free MongoDB cluster
28+
and load this sample data.

‎source/includes/method-overloads.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. note:: Method Overloads
2+
3+
Many of the methods on this page have multiple overloads. The examples
4+
in this guide show only one overload for each method. For
5+
more information about the available overloads, see the
6+
:manual:`{+new-api-root+} API documentation </api-reference>`.

0 commit comments

Comments
 (0)