Skip to content

Commit cb693cf

Browse files
mongoKartmongoKart
committed
wip
1 parent 6690f80 commit cb693cf

File tree

2 files changed

+280
-109
lines changed

2 files changed

+280
-109
lines changed

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

Lines changed: 213 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -40,29 +40,54 @@ Define the Write Operations
4040
For each write operation you want to perform, create an instance of one of
4141
the following operation classes:
4242

43-
- ``BulkWriteInsertOneModel``
44-
- ``BulkWriteUpdateOneModel``
45-
- ``BulkWriteUpdateManyModel``
46-
- ``BulkWriteReplaceOneModel``
47-
- ``BulkWriteDeleteOneModel``
48-
- ``BulkWriteDeleteManyModel``
43+
- ``BulkWriteInsertOneModel<TDocument>``
44+
- ``BulkWriteUpdateOneModel<TDocument>``
45+
- ``BulkWriteUpdateManyModel<TDocument>``
46+
- ``BulkWriteReplaceOneModel<TDocument>``
47+
- ``BulkWriteDeleteOneModel<TDocument>``
48+
- ``BulkWriteDeleteManyModel<TDocument>``
4949

5050
Then, pass an ``IReadOnlyList`` of the instances you created to the
5151
``MongoClient.BulkWrite()`` or ``MongoClient.BulkWriteAsync()`` method.
5252

5353
The following sections show how to create and use instances of the preceding classes.
5454

55+
.. tip:: Bulk Write Operations with POCOs
56+
57+
The examples in this guide use ``BsonDocument`` as the type for ``TDocument``.
58+
You can also use a Plain Old CLR Objects (POCO) as the type for ``TDocument``.
59+
60+
To use a POCO, define a class that represents the documents in your collection.
61+
The class must have properties that match the fields in your documents.
62+
For more information, see :ref:`<csharp-poco>`.
63+
5564
Insert Operations
5665
~~~~~~~~~~~~~~~~~
5766

58-
To perform an insert operation, create an instance of the ``BulkWriteInsertOneModel`` class
59-
and pass the following arguments:
67+
To perform an insert operation, create an instance of the
68+
``BulkWriteInsertOneModel<TDocument>`` class.
69+
The ``BulkWriteInsertOneModel<TDocument>`` constructor accepts the following parameters:
70+
71+
.. list-table::
72+
:header-rows: 1
73+
:stub-columns: 1
74+
:widths: 10 10 20 (Optional)
75+
76+
* - Parameter
77+
- Description
78+
79+
* - ``collectionNamespace``
80+
- | The database and collection to insert the BSON document into.
81+
|
82+
| **Data Type:** {+string-data-type+} or `CollectionNamespace <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollectionNamespace.html>`__
6083

61-
- The names of the database and collection to insert the BSON document into, in the format
62-
"database.collection"
63-
- The BSON document to insert into the collection, as a ``BsonDocument`` object
84+
* - ``document``
85+
- | The document to insert into the collection.
86+
|
87+
| **Data Type:** ``TDocument``
6488

65-
The following example creates an instance of the ``BulkWriteInsertOneModel`` class. The
89+
The following example creates an instance of the ``BulkWriteInsertOneModel<TDocument>``
90+
class. The
6691
``BsonDocument`` object represents a new restaurant named "Mongo's Deli" to be inserted
6792
into the ``sample_restaurants.restaurants`` collection.
6893

@@ -73,28 +98,83 @@ into the ``sample_restaurants.restaurants`` collection.
7398
:copyable:
7499
:dedent: 8
75100

76-
To insert multiple documents, create an instance of ``BulkWriteInsertOneModel`` for
77-
each document.
101+
.. tip:: Insert Multiple Documents
102+
103+
To insert multiple documents, create an instance of the
104+
``BulkWriteInsertOneModel<TDocument>`` class for each document you want to insert.
78105

79106
Update Operations
80107
~~~~~~~~~~~~~~~~~
81108

82-
To update a document, create an instance of the ``BulkWriteUpdateOneModel`` class and pass
83-
the following arguments:
109+
To update a document, create an instance of the ``BulkWriteUpdateOneModel<TDocument>``
110+
class. The ``BulkWriteUpdateOneModel<TDocument>`` constructor accepts the following
111+
parameters:
84112

85-
- The names of the database and collection to insert the BSON document into, in the format
86-
"database.collection".
87-
- A **query filter** that specifies the criteria used to match documents in your collection.
88-
The ``BulkWriteUpdateOneModel`` operation updates *only the first document* that matches your
89-
query filter.
90-
- The update operation you want to perform. For more information about update
91-
operations, see the :manual:`Field Update Operators
92-
</reference/operator/update-field/>` guide in the {+mdb-server+} manual.
113+
.. list-table::
114+
:header-rows: 1
115+
:stub-columns: 1
116+
117+
* - Parameter
118+
- Description
119+
120+
* - ``collectionNamespace``
121+
- | The database and collection to insert the BSON document into.
122+
|
123+
| **Data Type:** {+string-data-type+} or `CollectionNamespace <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollectionNamespace.html>`__
93124

94-
The following example creates an instance of the ``BulkWriteUpdateOneModel`` class. The
125+
* - ``filter``
126+
- | The **query filter** that specifies the criteria used to match documents in your collection.
127+
| The ``UpdateOne`` operation updates *only the first document* that matches the
128+
| query filter.
129+
|
130+
| **Data Type:** `FilterDefinition<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__
131+
132+
* - ``update``
133+
- | The update operation you want to perform. For more information about update
134+
| operations, see
135+
| :manual:`Field Update Operators </reference/operator/update-field/>` in the
136+
| {+mdb-server+} manual.
137+
|
138+
| **Data Type:** `UpdateDefinition<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinition-1.html>`__
139+
140+
* - ``collation``
141+
- | *Optional.* The language collation to use when sorting results. See
142+
| :manual:`the delete statements</reference/command/delete/#std-label-deletes-array-collation>`
143+
for more information.
144+
|
145+
| **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__
146+
| **Default:** ``null``
147+
148+
* - ``hint``
149+
- | *Optional.* The index to use to scan for documents.
150+
See :manual:`the MongoDB server manual</reference/command/update/#std-label-update-command-hint>`
151+
for more information.
152+
|
153+
| **Data Type:** `BsonValue <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonValue.html>`__
154+
| **Default:** ``null``
155+
156+
* - ``isUpsert``
157+
- | *Optional.* Specifies whether the update operation performs an upsert operation if no
158+
| documents match the query filter.
159+
| See :manual:`the MongoDB server manual </reference/command/update/#std-label-update-command-upsert>`
160+
| for more information.
161+
|
162+
| **Data Type:** {+bool-data-type+}
163+
| **Default:** ``false``
164+
165+
* - ``arrayFilters``
166+
- | Specifies which array elements to modify for an update operation on an array field.
167+
| See :manual:`the MongoDB server manual</reference/command/update/#update-elements-match-arrayfilters-criteria>`
168+
| for more information.
169+
|
170+
| **Data Type:** `IEnumerable<ArrayFilterDefinition> <https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.ienumerable-1?view=net-8.0>`__
171+
| **Default:** ``null``
172+
173+
The following example creates an instance of the ``BulkWriteUpdateOneModel<TDocument>``
174+
class, and uses ``BsonDocument`` as the type for ``TDocument``. The
95175
filter matches the first document in the ``sample_restaurants.restaurants`` collection
96-
where the ``name`` field is ``"Mongo's Deli"``. The update operation sets the ``cuisine``
97-
field to ``"Sandwiches and Salads"``.
176+
where the value of the ``name`` field is ``"Mongo's Deli"``. The update operation sets
177+
the value of the ``cuisine`` field to ``"Sandwiches and Salads"``.
98178

99179
.. literalinclude:: /includes/fundamentals/code-examples/BulkWrite.cs
100180
:start-after: start-bulk-update-one
@@ -103,14 +183,17 @@ field to ``"Sandwiches and Salads"``.
103183
:copyable:
104184
:dedent: 8
105185

106-
To update multiple documents, create an instance of the ``BulkWriteUpdateManyModel`` class
107-
and pass in the same arguments described previously. The ``BulkWriteUpdateManyModel``
186+
To update multiple documents, create an instance of the
187+
``BulkWriteUpdateManyModel<TDocument>`` class. The constructor for this class
188+
accepts the same parameters as the ``BulkWriteUpdateOneModel<TDocument>`` constructor.
189+
The ``BulkWriteUpdateManyModel<TDocument>``
108190
operation updates *all documents* that match your query filter.
109191

110-
The following example creates an instance of the ``BulkWriteUpdateManyModel`` class. The
192+
The following example creates an instance of the ``BulkWriteUpdateManyModel<TDocument>``
193+
class, and uses ``BsonDocument`` as the type for ``TDocument``. The
111194
filter matches all documents in the ``sample_restaurants.restaurants`` collection
112-
where the ``name`` field is ``"Mongo's Deli"``. The update operation sets the ``cuisine``
113-
field to ``"Sandwiches and Salads"``.
195+
where the value of the ``name`` field is ``"Mongo's Deli"``. The update operation sets
196+
the value of the ``cuisine`` field to ``"Sandwiches and Salads"``.
114197

115198
.. literalinclude:: /includes/fundamentals/code-examples/BulkWrite.cs
116199
:start-after: start-bulk-update-many
@@ -122,79 +205,144 @@ field to ``"Sandwiches and Salads"``.
122205
Replace Operations
123206
~~~~~~~~~~~~~~~~~~
124207

125-
A replace operation removes all fields and values in a specified document and
126-
replaces them with new ones. To perform a replace operation, create an instance
127-
of the ``BulkWriteReplaceOneModel`` class and pass it a query filter and the fields and values you want
128-
to store in the matching document.
208+
To replace the fields in a document, create an instance of the
209+
``BulkWriteReplaceOneModel<TDocument>`` class. The ``BulkWriteReplaceOneModel<TDocument>``
210+
constructor accepts the following parameters:
129211

130-
The following example creates an instance of ``ReplaceOne``:
212+
.. list-table::
213+
:header-rows: 1
214+
:stub-columns: 1
131215

132-
.. literalinclude:: /includes/write/bulk-write.py
216+
* - Parameter
217+
- Description
218+
219+
* - ``collectionNamespace``
220+
- | The database and collection to insert the BSON document into.
221+
|
222+
| **Data Type:** {+string-data-type+} or `CollectionNamespace <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollectionNamespace.html>`__
223+
224+
* - ``filter``
225+
- | The **query filter** that specifies the criteria used to match documents in your collection.
226+
| The ``UpdateOne`` operation updates *only the first document* that matches the
227+
| query filter.
228+
|
229+
| **Data Type:** `FilterDefinition<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__
230+
231+
* - ``replacement``
232+
- | The replacement document, which specifies the fields and values to insert in the
233+
| target document.
234+
|
235+
| **Data Type:** ``TDocument``
236+
237+
* - ``collation``
238+
- | *Optional.* The language collation to use when sorting results. See
239+
| :manual:`the delete statements</reference/command/delete/#std-label-deletes-array-collation>`
240+
for more information.
241+
|
242+
| **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__
243+
| **Default:** ``null``
244+
245+
* - ``hint``
246+
- | *Optional.* The index to use to scan for documents.
247+
See :manual:`the MongoDB server manual</reference/command/update/#std-label-update-command-hint>`
248+
for more information.
249+
|
250+
| **Data Type:** `BsonValue <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonValue.html>`__
251+
| **Default:** ``null``
252+
253+
* - ``isUpsert``
254+
- | *Optional.* Specifies whether the update operation performs an upsert operation if no
255+
| documents match the query filter.
256+
| See :manual:`the MongoDB server manual </reference/command/update/#std-label-update-command-upsert>`
257+
| for more information.
258+
|
259+
| **Data Type:** {+bool-data-type+}
260+
| **Default:** ``false``
261+
262+
The following example creates an instance of the ``BulkWriteReplaceOneyModel<TDocument>``
263+
class, and uses ``BsonDocument`` as the type for ``TDocument``. The
264+
filter matches the document in the ``sample_restaurants.restaurants`` collection
265+
where the value of the ``restaurant_id`` field is ``"1234"``. The replace operation
266+
removes all fields from this document and sets new values in the ``name``, ``cuisine``,
267+
``borough``, and ``restaurant_id`` fields.
268+
269+
.. literalinclude:: /includes/fundamentals/code-examples/BulkWrite.cs
133270
:start-after: start-bulk-replace-one
134271
:end-before: end-bulk-replace-one
135-
:language: python
272+
:language: csharp
136273
:copyable:
274+
:dedent: 8
137275

138-
To replace multiple documents, you must create an instance of ``ReplaceOne`` for each document.
276+
.. tip:: Replace Multiple Documents
277+
278+
To replace multiple documents, you must create an instance of the
279+
``BulkWriteReplaceOneModel<TDocument>`` class for each document you want to replace.
139280

140281
Delete Operations
141282
~~~~~~~~~~~~~~~~~
142283

143-
To delete a document, create an instance of ``DeleteOne`` and pass in a
144-
query filter specifying the document you want to delete. ``DeleteOne`` removes
145-
only *the first* document that matches your query filter.
284+
To delete a document, create an instance of the ``BulkWriteDeleteOneModel`` and pass in
285+
a query filter that specifies the document that you want to delete. The
286+
``BulkWriteDeleteOneModel`` operation removes
287+
only the *first document* that matches your query filter.
146288

147-
The following example creates an instance of ``DeleteOne``:
289+
The following example creates an instance of the ``BulkWriteDeleteOneModel`` class:
148290

149-
.. literalinclude:: /includes/write/bulk-write.py
291+
.. literalinclude:: /includes/fundamentals/code-examples/BulkWrite.cs
150292
:start-after: start-bulk-delete-one
151293
:end-before: end-bulk-delete-one
152-
:language: python
294+
:language: csharp
153295
:copyable:
296+
:dedent: 8
154297

155-
To delete multiple documents, create an instance of ``DeleteMany`` and pass in a
156-
query filter specifying the document you want to delete. ``DeleteMany`` removes
157-
*all* documents that match your query filter.
298+
To delete multiple documents, create an instance of the ``BulkWriteDeleteManyModel``
299+
class and pass a query filter that specifies the document that you want to delete.
300+
The ``BulkWriteDeleteManyModel`` operation removes *all* documents that match your
301+
query filter.
158302

159-
The following example creates an instance of ``DeleteMany``:
303+
The following example creates an instance of the ``BulkWriteDeleteManyModel`` class:
160304

161-
.. literalinclude:: /includes/write/bulk-write.py
305+
.. literalinclude:: /includes/fundamentals/code-examples/BulkWrite.cs
162306
:start-after: start-bulk-delete-many
163307
:end-before: end-bulk-delete-many
164-
:language: python
308+
:language: csharp
165309
:copyable:
310+
:dedent: 8
166311

167-
Call the ``bulk_write()`` Method
312+
Call the ``BulkWrite()`` Method
168313
--------------------------------
169314

170-
After you define a class instance for each operation you want to perform,
171-
pass a list of these instances to the ``bulk_write()`` method.
172-
By default, the method runs the operations in the order
315+
After you define a ``BulkWriteModel`` instance for each operation that you want to perform,
316+
pass an ``IList`` of these instances to the ``BulkWrite()`` or ``BulkWriteAsync()`` method.
317+
By default, these methods run the operations in the order
173318
they're defined in the list.
174319

175-
The following example performs multiple write operations by using the
176-
``bulk_write()`` method:
320+
The following code examples show how to use the asynchronous
321+
``BulkWriteAsync()`` method and the synchronous ``BulkWrite()`` method to
322+
perform multiple write operations.
177323

178324
.. io-code-block::
179325

180-
.. input:: /includes/write/bulk-write.py
326+
.. input:: /includes/fundamentals/code-examples/BulkWrite.cs
181327
:start-after: start-bulk-write-mixed
182328
:end-before: end-bulk-write-mixed
183-
:language: python
329+
:language: csharp
330+
:dedent: 8
184331

185332
.. output::
186333

187334
BulkWriteResult({'writeErrors': [], 'writeConcernErrors': [], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 2, 'nModified': 2, 'nRemoved': 1, 'upserted': []}, acknowledged=True)
188335

189-
If any of the write operations fail, {+driver-short+} raises a
190-
``BulkWriteError`` and does not perform any further operations.
191-
``BulkWriteError`` provides a ``details`` attribute that includes the operation
336+
If any of the write operations fail, the {+driver-short+} raises a
337+
``BulkWriteException`` and does not perform any further operations.
338+
``BulkWriteException`` provides a ``details`` attribute that includes the operation
192339
that failed, and details about the exception.
193340

194341
.. note::
195342

196-
When {+driver-short+} runs a bulk operation, it uses the ``write_concern`` of the
197-
collection in which the operation is running. The driver reports all write
343+
When the {+driver-short+} executes a bulk write operation, it uses the
344+
``WriteConcern`` of the
345+
collection on which the operation is running. The driver reports all write
198346
concern errors after attempting all operations, regardless of execution order.
199347

200348
Customize Bulk Write Operations

0 commit comments

Comments
 (0)