Skip to content

Commit 8230d41

Browse files
kyuan-mongodbkyuan-mongodb
authored
DOCSP-15915 crud bulk operations (#81)
* added CRUD Bulk Operations page
1 parent 8eeabf5 commit 8230d41

File tree

4 files changed

+531
-1
lines changed

4 files changed

+531
-1
lines changed

‎source/fundamentals/crud.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ CRUD Operations
1010
/fundamentals/crud/read-operations
1111
/fundamentals/crud/write-operations
1212
/fundamentals/crud/query-document
13+
/fundamentals/crud/bulk
1314
/fundamentals/crud/compound-operations
1415

1516
CRUD (Create, Read, Update, Delete) operations enable you to work with
@@ -23,3 +24,6 @@ data stored in MongoDB.
2324
Some operations combine aspects of read and write operations. See our
2425
guide on :doc:`compound operations </fundamentals/crud/compound-operations>`
2526
to learn more about these hybrid methods.
27+
28+
You can also perform multiple CRUD operations using bulk operations. See
29+
our guide on :doc:`bulk operations </fundamentals/crud/bulk>` to learn more.

‎source/fundamentals/crud/bulk.txt

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
===============
2+
Bulk Operations
3+
===============
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you will learn how to use **bulk operations** in the
17+
MongoDB Java Driver.
18+
19+
To perform a create, replace, update or delete (CRUD) operation, you
20+
use their corresponding method. For example, to insert one document,
21+
update multiple documents, and delete one document in your collection,
22+
you use the ``insertOne()``, ``updateMany()`` and ``deleteOne()`` methods.
23+
24+
The ``MongoClient`` performs these operations by making a call for each
25+
operation to the database. You can reduce the number of calls to the
26+
database to one by using bulk operations.
27+
28+
Performing Bulk Operations
29+
--------------------------
30+
31+
Bulk operations consist of a large number of CRUD operations. To perform
32+
the bulk operation, pass a ``List`` of ``WriteModel`` documents to the
33+
``bulkWrite()`` method. A ``WriteModel`` is a model that represents any
34+
of the CRUD operations.
35+
36+
The following sections show how to create and use each ``WriteModel``
37+
document. The examples in each section contain the following documents
38+
in a collection:
39+
40+
.. code-block:: json
41+
42+
{ "_id": 1 }
43+
{ "_id": 2 }
44+
45+
For additional information on the classes and method mentioned in this
46+
section, see the following resources:
47+
48+
- :java-sync-api:`bulkWrite() <com/mongodb/client/MongoCollection.html#bulkWrite(java.util.List,com.mongodb.client.model.BulkWriteOptions)>` API Documentation
49+
- :java-core-api:`WriteModel <com/mongodb/client/model/WriteModel.html>` API Documentation
50+
- :java-core-api:`BulkWriteOptions <com/mongodb/client/model/BulkWriteOptions.html>` API Documentation
51+
52+
Insert Operation
53+
~~~~~~~~~~~~~~~~
54+
55+
To perform an insert operation, create an ``InsertOneModel`` specifying
56+
the document you want to insert. To insert multiple documents, you must
57+
create an ``InsertOneModel`` for each document you want to insert.
58+
59+
Example
60+
```````
61+
62+
The following example creates an ``InsertOneModel`` for two documents
63+
where the ``_id`` is "3" and "4":
64+
65+
.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
66+
:language: java
67+
:dedent:
68+
:start-after: begin insertDocumentsExample
69+
:end-before: end insertDocumentsExample
70+
71+
.. note::
72+
73+
When performing a ``bulkWrite()``, the ``InsertOneModel`` cannot
74+
insert a document with an ``_id`` that already exists in the
75+
collection. Instead, the method throws a ``MongoBulkWriteException``.
76+
77+
The following example tries to insert two documents where the ``_id`` is
78+
"1" and "3":
79+
80+
.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
81+
:language: java
82+
:dedent:
83+
:start-after: begin insertExceptionExample
84+
:end-before: end insertExceptionExample
85+
86+
The following shows the output of the code above:
87+
88+
.. code-block:: shell
89+
90+
A MongoBulkWriteException occured with the following message:
91+
Bulk write operation error on server sample-shard-00-02.pw0q4.mongodb.net:27017.
92+
Write errors: [BulkWriteError{index=0, code=11000, message='E11000 duplicate key
93+
error collection: crudOps.bulkWrite index: _id_ dup key: { _id: 1 }', details={}}].
94+
95+
To see why the document with the ``_id`` of "3" didn't insert, see
96+
the :ref:`Order of Execution <orderOfExecution>` section.
97+
98+
For additional information on the class mentioned in this
99+
section, see the following resource:
100+
101+
- :java-core-api:`InsertOneModel <com/mongodb/client/model/InsertOneModel.html>` API Documentation
102+
103+
Replace Operation
104+
~~~~~~~~~~~~~~~~~
105+
106+
To perform a replace operation, create a ``ReplaceOneModel`` specifying
107+
a query filter for document you want to replace with the replacement
108+
document.
109+
110+
.. note::
111+
112+
When performing a ``bulkWrite()``, the ``ReplaceOneModel`` cannot
113+
make changes to a document that violate unique index constraints on
114+
the collection, and the model does not replace a document if there
115+
are no matches to your query filter.
116+
117+
Example
118+
```````
119+
120+
The following example creates a ``ReplaceOneModel`` to
121+
replace a document where the ``_id`` is "1" with a document that
122+
contains an additional field:
123+
124+
.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
125+
:language: java
126+
:dedent:
127+
:start-after: begin replaceDocumentsExample
128+
:end-before: end replaceDocumentsExample
129+
130+
For additional information on the class and concept mentioned in this
131+
section, see the following resources:
132+
133+
- :java-core-api:`ReplaceOneModel <com/mongodb/client/model/ReplaceOneModel.html>` API Documentation
134+
- :manual:`Unique indexes </core/index-unique/>` Server Manual Explanation
135+
136+
Update Operation
137+
~~~~~~~~~~~~~~~~
138+
139+
To perform an update operation, create an ``UpdateOneModel`` or an
140+
``UpdateManyModel`` specifying a query filter for documents you want to
141+
update with what the updates are.
142+
143+
The ``UpdateOneModel`` updates the first document that matches your query
144+
filter and the ``UpdateManyModel`` updates all the documents that
145+
match your query filter.
146+
147+
.. note::
148+
149+
When performing a ``bulkWrite()``, the ``UpdateOneModel`` and
150+
``UpdateManyModel`` cannot make changes to a document that violate
151+
unique index constraints on the collection, and the models do not
152+
update any documents if there are no matches to your query filter.
153+
154+
Example
155+
```````
156+
157+
The following example creates an ``UpdateOneModel`` to update
158+
a document where the ``_id`` is "2" to a document that
159+
contains an additional field:
160+
161+
.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
162+
:language: java
163+
:dedent:
164+
:start-after: begin updateDocumentsExample
165+
:end-before: end updateDocumentsExample
166+
167+
For additional information on the classes and concept mentioned in this
168+
section, see the following resources:
169+
170+
- :java-core-api:`UpdateOneModel <com/mongodb/client/model/UpdateOneModel.html>` API Documentation
171+
- :java-core-api:`UpdateManyModel <com/mongodb/client/model/UpdateManyModel.html>` API Documentation
172+
- :manual:`unique indexes </core/index-unique/>` Server Manual Explanation
173+
174+
Delete Operation
175+
~~~~~~~~~~~~~~~~
176+
177+
To perform a delete operation, create a ``DeleteOneModel`` or a
178+
``DeleteManyModel`` specifying a query filter for documents you want to
179+
delete.
180+
181+
The ``DeleteOneModel`` deletes the first document that matches your query
182+
filter and the ``DeleteManyModel`` deletes all the documents that
183+
match your query filter.
184+
185+
.. note::
186+
187+
When performing a ``bulkWrite()``, the ``DeleteOneModel`` and
188+
``DeleteOneModel`` do not delete any documents if there are no matches
189+
to your query filter.
190+
191+
Example
192+
```````
193+
194+
The following example creates a ``DeleteOneModel`` to delete
195+
a document where the ``_id`` is "1":
196+
197+
.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
198+
:language: java
199+
:dedent:
200+
:start-after: begin deleteDocumentsExample
201+
:end-before: end deleteDocumentsExample
202+
203+
For additional information on the classes mentioned in this
204+
section, see the following resources:
205+
206+
- :java-core-api:`DeleteOneModel <com/mongodb/client/model/DeleteOneModel.html>` API Documentation
207+
- :java-core-api:`DeleteManyModel <com/mongodb/client/model/DeleteManyModel.html>` API Documentation
208+
209+
.. _orderOfExecution:
210+
211+
Order of Execution
212+
------------------
213+
214+
The ``bulkWrite()`` method accepts an optional ``BulkWriteOptions`` as
215+
a second parameter to specify if you want to execute the bulk operations
216+
as ordered or unordered.
217+
218+
Ordered Execution
219+
~~~~~~~~~~~~~~~~~
220+
221+
By default, the ``bulkWrite()`` method executes bulk operations in
222+
order. This means that the bulk operations execute in the order you
223+
added them to the list until an error occurs, if any.
224+
225+
Example
226+
```````
227+
228+
The following example performs these bulk operations:
229+
230+
- An insert operation for a document where the ``_id`` is "3"
231+
- A replace operation for a document where the ``_id`` is "1" with a document that contains an additional field
232+
- An update operation for a document where the ``_id`` is "3" to a document that contains an additional field
233+
- A delete operation for all documents that contain the field ``x`` with the value "2"
234+
235+
.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
236+
:language: java
237+
:dedent:
238+
:start-after: begin bulkWriteExample
239+
:end-before: end bulkWriteExample
240+
241+
After running this example, your collection contains the following
242+
document:
243+
244+
.. code-block:: json
245+
:copyable: false
246+
247+
{ "_id": 2 }
248+
249+
Unordered Execution
250+
~~~~~~~~~~~~~~~~~~~
251+
252+
You can also execute bulk operations in any order by specifying "false"
253+
to the ``order()`` method on ``BulkWriteOptions``. This means that
254+
all the bulk operations execute regardless if an error occurs and
255+
reports the errors at the end, if any.
256+
257+
Adding to the example above, including the following specifies the bulk
258+
operations to execute in any order:
259+
260+
.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
261+
:language: java
262+
:dedent:
263+
:start-after: begin bulkWriteNotOrderedExample
264+
:end-before: end bulkWriteNotOrderedExample
265+
266+
.. note::
267+
268+
Unordered bulk operations do not guarantee order of execution. The
269+
order may differ from the way you list them to optimize the runtime.
270+
271+
In the exampel above, if the ``bulkWrite()`` method decided to
272+
perform the insert operation after the update operation, nothing
273+
changes with the update operation because the document does not exist
274+
at that point in time. Your collection then contains the following
275+
documents:
276+
277+
.. code-block:: json
278+
:copyable: false
279+
280+
{ "_id": 2 }
281+
{ "_id": 3 }
282+
283+
For additional information on the class and method mentioned in this
284+
section, see the following resources:
285+
286+
- :java-core-api:`BulkWriteOptions <com/mongodb/client/model/BulkWriteOptions.html>` API Documentation
287+
- :java-core-api:`ordered() <com/mongodb/client/model/BulkWriteOptions.html#ordered(boolean)>` API Documentation
288+
289+
Summary
290+
-------
291+
292+
To perform a bulk operation, you create and pass a list of
293+
``WriteModel`` documents to the ``bulkWrite()`` method.
294+
295+
There are 6 different ``WriteModel`` documents: ``InsertOneModel``,
296+
``ReplaceOneModel``, ``UpdateOneModel``, ``UpdateManyModel``,
297+
``DeleteOneModel`` and ``DeleteManyModel``.
298+
299+
There are two ways to execute the ``bulkWrite()`` method:
300+
301+
- Ordered, which performs the bulk operations in order until an error occurs, if any
302+
- Unordered, which performs all the bulk operations in any order and reports errors at the end, if any

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,6 @@ Write Operations
1919
/fundamentals/crud/write-operations/delete
2020
/fundamentals/crud/write-operations/change-a-document
2121
/fundamentals/crud/write-operations/upsert
22-
22+
2323
..
2424
/fundamentals/crud/write-operations/embedded-arrays

0 commit comments

Comments
 (0)