Skip to content

Commit 43d9db7

Browse files
jason-price-mongodbjason-price-mongodb
jason-price-mongodb
and
jason-price-mongodb
authored
DOCSP-29667-bulk-command-additional-updates (#5777)
* DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates * DOCSP-29667-bulk-command-additional-updates --------- Co-authored-by: jason-price-mongodb <[email protected]>
1 parent 1bf09d6 commit 43d9db7

File tree

11 files changed

+288
-50
lines changed

11 files changed

+288
-50
lines changed

‎config/redirects

+1-1
Original file line numberDiff line numberDiff line change
@@ -2536,7 +2536,7 @@ raw: ${prefix}/${version}/applications/drivers -> ${base}/drivers/
25362536
[v7.0-*]: ${prefix}/${version}/tutorial/upgrade-revision -> ${base}/${version}/release-notes/
25372537

25382538
## DOCSP-29667 New page for bulkWrite
2539-
[*-v7.1): ${prefix}/${version}/reference/command/bulkWrite -> ${base}/${version}/reference/command/
2539+
[*-v7.3): ${prefix}/${version}/reference/command/bulkWrite -> ${base}/${version}/reference/command/
25402540

25412541
# DOCSP-31908 Removing free monitoring pages after decomission
25422542
[*]: ${prefix}/${version}/reference/method/db.enableFreeMonitoring -> ${base}/${version}/administration/free-monitoring/

‎snooty.toml

+2-1
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,7 @@ toc_landing_pages = [
212212
"/release-notes/7.1",
213213
"/release-notes/7.2",
214214
"/release-notes/7.3",
215+
"/release-notes/8.0",
215216
"/replication",
216217
"/security",
217218
"/sharding",
@@ -262,7 +263,7 @@ windows-dir-version = "6.0" # wizard
262263
package-name-org = "mongodb-org"
263264
package-name-enterprise = "mongodb-enterprise"
264265
package-name = "mongodb"
265-
version = "7.3"
266+
version = "8.0"
266267
latest-lts-version = "7.0"
267268
last-supported-version = "5.0"
268269
release = "7.1.1"

‎source/includes/bulkWrite-introduction.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Starting in MongoDB 7.2, you can use the new :dbcommand:`bulkWrite`
1+
Starting in MongoDB 8.0, you can use the new :dbcommand:`bulkWrite`
22
command to perform many insert, update, and delete operations on
33
multiple collections in one request. The existing
44
:method:`db.collection.bulkWrite` method only allows you to modify one

‎source/reference/command.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ Query and Write Operation Commands
135135
- Performs many insert, update, and delete operations on multiple
136136
collections in one request.
137137

138-
.. versionadded:: 7.2
138+
.. versionadded:: 8.0
139139

140140
- No
141141

‎source/reference/command/bulkWrite.txt

+229-38
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Definition
1515

1616
.. dbcommand:: bulkWrite
1717

18-
.. versionadded:: 7.2
18+
.. versionadded:: 8.0
1919

2020
.. include:: /includes/bulkWrite-introduction.rst
2121

@@ -84,6 +84,7 @@ The command has this syntax:
8484
bypassDocumentValidation: <boolean>,
8585
comment: <string>,
8686
let: <document>,
87+
errorsOnly: <boolean>,
8788
cursor: { batchSize: <integer> },
8889
writeConcern: <string>
8990
} )
@@ -243,6 +244,14 @@ The command takes the following fields:
243244
For ``let`` examples, see :ref:`update-variables-example` and
244245
:ref:`delete-let-example`.
245246

247+
* - ``errorsOnly``
248+
- boolean
249+
- Optional
250+
- If ``true``, the operation only returns errors and omits
251+
other output.
252+
253+
Default is ``false``.
254+
246255
* - ``cursor batchSize``
247256
- integer
248257
- Optional
@@ -315,10 +324,30 @@ The command returns a document with these fields:
315324
- integer
316325
- Number of documents modified by an update operation.
317326

318-
* - ``numErrors``
327+
* - ``nErrors``
319328
- integer
320329
- Number of errors for the ``bulkWrite`` command.
321330

331+
* - ``nInserted``
332+
- integer
333+
- Number of inserted documents.
334+
335+
* - ``nMatched``
336+
- integer
337+
- Number of matched documents.
338+
339+
* - ``nModified``
340+
- integer
341+
- Number of modified documents.
342+
343+
* - ``nUpserted``
344+
- integer
345+
- Number of upserted documents.
346+
347+
* - ``nDeleted``
348+
- integer
349+
- Number of deleted documents.
350+
322351
* - ``ok``
323352
- integer
324353
- ``1`` indicates the ``bulkWrite`` command was successful.
@@ -352,9 +381,39 @@ operations with both ``multi`` set to ``true`` and retryable writes.
352381
Operation Performance
353382
~~~~~~~~~~~~~~~~~~~~~
354383

355-
If you run multiple operations in one ``bulkWrite`` command, you will
356-
obtain similar performance if you run the same operations individually
357-
in separate insert, update, and delete commands.
384+
If you rewrite existing insert, update, and delete commands as a
385+
``bulkWrite`` command and set ``errorsOnly`` to ``true``, the
386+
``bulkWrite`` command has similar performance as the existing commands.
387+
If you set ``errorsOnly`` to ``false``, performance is worse.
388+
389+
In addition, if you have a sequence of commands like this:
390+
391+
.. code-block:: javascript
392+
:copyable: false
393+
394+
insert
395+
update
396+
delete
397+
398+
If you replace those commands with the following example fragment, then
399+
the command with the following fragment is faster regardless of other
400+
options:
401+
402+
.. code-block:: javascript
403+
:copyable: false
404+
405+
{
406+
bulkWrite: 0,
407+
ops: [
408+
insert,
409+
update,
410+
delete
411+
]
412+
}
413+
414+
Most of the performance improvement is because of network latency, which
415+
is variable depending on your implementation, but the example is always
416+
faster.
358417

359418
Examples
360419
--------
@@ -422,22 +481,28 @@ The following ``bulkWrite`` example modifies a single namespace:
422481
.. step:: Examine the output
423482

424483
The following ``bulkWrite`` example output, with various ``ok: 1``
425-
fields and ``numErrors: 0``, indicates all operations were
484+
fields and ``nErrors: 0``, indicates all operations were
426485
successful:
427486

428487
.. code-block:: javascript
429488
:copyable: false
430489

431490
{
432491
cursor: {
433-
id: Long("0"),
492+
id: Long('0'),
434493
firstBatch: [
435494
{ ok: 1, idx: 0, n: 1 },
436495
{ ok: 1, idx: 1, n: 1, nModified: 1 },
437496
{ ok: 1, idx: 2, n: 1 }
438-
]
497+
],
498+
ns: 'admin.$cmd.bulkWrite'
439499
},
440-
numErrors: 0,
500+
nErrors: 0,
501+
nInserted: 1,
502+
nMatched: 1,
503+
nModified: 1,
504+
nUpserted: 0,
505+
nDeleted: 1,
441506
ok: 1
442507
}
443508

@@ -548,7 +613,7 @@ operations for two namespaces:
548613

549614
{
550615
cursor: {
551-
id: Long("0"),
616+
id: Long('0'),
552617
firstBatch: [
553618
{ ok: 1, idx: 0, n: 1 },
554619
{ ok: 1, idx: 1, n: 1 },
@@ -559,9 +624,15 @@ operations for two namespaces:
559624
{ ok: 1, idx: 6, n: 1, nModified: 1 },
560625
{ ok: 1, idx: 7, n: 1 },
561626
{ ok: 1, idx: 8, n: 1 }
562-
]
627+
],
628+
ns: 'admin.$cmd.bulkWrite'
563629
},
564-
numErrors: 0,
630+
nErrors: 0,
631+
nInserted: 4,
632+
nMatched: 2,
633+
nModified: 2,
634+
nUpserted: 0,
635+
nDeleted: 3,
565636
ok: 1
566637
}
567638

@@ -641,39 +712,159 @@ operations that don't change any documents:
641712

642713
{
643714
cursor: {
644-
id: Long("0"),
645-
firstBatch: [
646-
{
647-
ok: 0,
648-
idx: 0,
649-
code: 11000,
650-
errmsg: 'E11000 duplicate key error collection:
651-
test.pizzas index: _id_ dup key: { _id: 1 }',
652-
keyPattern: { _id: 1 },
653-
keyValue: { _id: 1 },
654-
n: 0
655-
},
656-
{
657-
ok: 0,
658-
idx: 1,
659-
code: 11000,
660-
errmsg: 'E11000 duplicate key error collection:
661-
test.pizzas index: _id_ dup key: { _id: 2 }',
662-
keyPattern: { _id: 1 },
663-
keyValue: { _id: 2 },
664-
n: 0
665-
},
666-
{ ok: 1, idx: 2, n: 0, nModified: 0 },
667-
{ ok: 1, idx: 3, n: 0 }
668-
]
715+
id: Long("0"),
716+
firstBatch: [
717+
{
718+
ok: 0,
719+
idx: 0,
720+
code: 11000,
721+
errmsg: 'E11000 duplicate key error collection:
722+
test.pizzas index: _id_ dup key: { _id: 1 }',
723+
keyPattern: { _id: 1 },
724+
keyValue: { _id: 1 },
725+
n: 0
726+
},
727+
{
728+
ok: 0,
729+
idx: 1,
730+
code: 11000,
731+
errmsg: 'E11000 duplicate key error collection:
732+
test.pizzas index: _id_ dup key: { _id: 2 }',
733+
keyPattern: { _id: 1 },
734+
keyValue: { _id: 2 },
735+
n: 0
736+
},
737+
{ ok: 1, idx: 2, n: 0, nModified: 0 },
738+
{ ok: 1, idx: 3, n: 0 }
739+
],
740+
ns: 'admin.$cmd.bulkWrite'
669741
},
670-
numErrors: 2,
742+
nErrors: 2,
743+
nInserted: 0,
744+
nMatched: 0,
745+
nModified: 0,
746+
nUpserted: 0,
747+
nDeleted: 0,
671748
ok: 1
672749
}
673750

674751
For details about the output fields, including the error codes and
675752
messages, see the earlier :ref:`bulkWrite-output` section.
676753

754+
Bulk Write Example with errorsOnly Enabled
755+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
756+
757+
The following ``bulkWrite`` example sets ``errorsOnly`` to ``true`` to
758+
only show the error output:
759+
760+
.. procedure::
761+
:style: normal
762+
763+
.. step:: Create the pizzas example collection
764+
765+
If you already have the ``pizzas`` collection in your ``test``
766+
database, use the :method:`db.collection.drop` method to drop it
767+
first and then run:
768+
769+
.. include:: /includes/pizza-example-collection.rst
770+
771+
.. step:: Attempt to modify the pizzas example collection
772+
773+
Run the following ``bulkWrite`` command to perform insert, update,
774+
and delete operations on the ``pizzas`` collection with
775+
``errorsOnly`` set to ``true``:
776+
777+
.. code-block:: javascript
778+
779+
db.adminCommand( {
780+
bulkWrite: 1,
781+
782+
// The ops array contains the insert, update, and delete
783+
// operations.
784+
ops: [
785+
786+
// The namespace ID indexes are specified immediately after
787+
// the insert, update, and delete text.
788+
// For example, "insert: 0" specifies the 0 namespace ID index,
789+
// which is the "test.pizzas" namespace in nsInfo.
790+
791+
// Attempt to add a duplicate document with an
792+
// _id of 1, which already exists and causes an error.
793+
{ insert: 0, document: { _id: 1, type: "tomato",
794+
size: "small", price: 12 } },
795+
796+
// Attempt to add another duplicate document.
797+
{ insert: 0, document: { _id: 2, type: "pepper",
798+
size: "small", price: 12 } },
799+
800+
// Attempt to change the price for extra large pizzas,
801+
// which don't exist. This doesn't cause an error but
802+
// doesn't update any documents.
803+
{ update: 0, filter: { size: "extra large" },
804+
updateMods: { $set: { price: 15 } } },
805+
806+
// Attempt to remove a document that doesn't exist.
807+
// This doesn't cause an error but doesn't delete any documents.
808+
{ delete: 0, filter: { _id: 8 } }
809+
],
810+
811+
// The nsInfo array contains the namespace to apply the
812+
// previous operations to.
813+
nsInfo: [
814+
{ ns: "test.pizzas" } // Namespace ID index is 0.
815+
],
816+
817+
// Set the ordered field to false to run the remaining operations
818+
// after an operation returns an error.
819+
ordered: false,
820+
821+
// Set the errorsOnly field to true to only output the errors.
822+
errorsOnly: true
823+
} )
824+
825+
.. step:: Examine the output
826+
827+
The following ``bulkWrite`` example output shows the errors:
828+
829+
.. code-block:: javascript
830+
:copyable: false
831+
832+
{
833+
cursor: {
834+
id: Long("0"),
835+
firstBatch: [
836+
{
837+
ok: 0,
838+
idx: 0,
839+
code: 11000,
840+
errmsg: 'E11000 duplicate key error collection:
841+
test.pizzas index: _id_ dup key: { _id: 1 }',
842+
keyPattern: { _id: 1 },
843+
keyValue: { _id: 1 },
844+
n: 0
845+
},
846+
{
847+
ok: 0,
848+
idx: 1,
849+
code: 11000,
850+
errmsg: 'E11000 duplicate key error collection:
851+
test.pizzas index: _id_ dup key: { _id: 2 }',
852+
keyPattern: { _id: 1 },
853+
keyValue: { _id: 2 },
854+
n: 0
855+
},
856+
],
857+
ns: 'admin.$cmd.bulkWrite'
858+
},
859+
nErrors: 2,
860+
nInserted: 0,
861+
nMatched: 0,
862+
nModified: 0,
863+
nUpserted: 0,
864+
nDeleted: 0,
865+
ok: 1
866+
}
867+
677868
Learn More
678869
----------
679870

0 commit comments

Comments
 (0)