Skip to content

Commit 45aceb4

Browse files
jmikolajmikola
committed
PHPLIB-246: Document BulkWriteException thrown by write operations
Clarify how the "ordered" option may impact bulk write operations. Also advise users to inspect the BulkWriteException's WriteResult to determine the nature of the error.
1 parent ff8426c commit 45aceb4

11 files changed

+62
-3
lines changed

‎docs/includes/apiargs-MongoDBCollection-method-bulkWrite-option.yaml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ arg_name: option
66
name: ordered
77
type: boolean
88
description: |
9-
If ``true``: when a single write fails, the operation returns without
10-
performing the remaining writes.
9+
If ``true``: when a single write fails, the operation will stop without
10+
performing the remaining writes and throw an exception.
1111
1212
If ``false``: when a single write fails, the operation will continue with the
13-
remaining writes, if any.
13+
remaining writes, if any, and throw an exception.
1414
1515
The default is ``true``.
1616
interface: phpmethod

‎docs/includes/extracts-bulkwriteexception.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
ref: bulkwriteexception-result
2+
content: |
3+
If a :php:`MongoDB\\Driver\\Exception\\BulkWriteException
4+
<mongodb-driver-exception-bulkwriteexception>` is thrown, users should call
5+
:php:`getWriteResult() <mongodb-driver-writeexception.getwriteresult>` and
6+
inspect the returned :php:`MongoDB\\Driver\\WriteResult
7+
<mongodb-driver-writeresult>` object to determine the nature of the error.
8+
9+
For example, a write operation may have been successfully applied to the
10+
primary server but failed to satisfy the write concern (e.g. replication took
11+
too long). Alternatively, a write operation may have failed outright (e.g.
12+
unique key violation).
13+
---
14+
ref: bulkwriteexception-ordered
15+
content: |
16+
In the case of a bulk write, the result may indicate multiple successful write
17+
operations and/or errors. If the ``ordered`` option is ``true``, some
18+
operations may have succeeded before the first error was encountered and the
19+
exception thrown. If the ``ordered`` option is ``false``, multiple errors may
20+
have been encountered.
21+
...

‎docs/includes/extracts-error.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
ref: error-driver-bulkwriteexception
2+
content: |
3+
:php:`MongoDB\\Driver\\Exception\\BulkWriteException
4+
<mongodb-driver-exception-bulkwriteexception>` for errors related to the write
5+
operation. Users should inspect the value returned by :php:`getWriteResult()
6+
<mongodb-driver-writeexception.getwriteresult>` to determine the nature of the
7+
error.
8+
---
19
ref: error-driver-invalidargumentexception
210
content: |
311
:php:`MongoDB\\Driver\\Exception\\InvalidArgumentException

‎docs/reference/method/MongoDBCollection-bulkWrite.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,15 @@ Errors/Exceptions
4040

4141
.. include:: /includes/extracts/error-unsupportedexception.rst
4242
.. include:: /includes/extracts/error-invalidargumentexception.rst
43+
.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
4344
.. include:: /includes/extracts/error-driver-runtimeexception.rst
4445

46+
Behavior
47+
--------
48+
49+
.. include:: /includes/extracts/bulkwriteexception-result.rst
50+
.. include:: /includes/extracts/bulkwriteexception-ordered.rst
51+
4552
.. todo: add output and examples
4653

4754
See Also

‎docs/reference/method/MongoDBCollection-deleteMany.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,14 @@ Errors/Exceptions
4040

4141
.. include:: /includes/extracts/error-unsupportedexception.rst
4242
.. include:: /includes/extracts/error-invalidargumentexception.rst
43+
.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
4344
.. include:: /includes/extracts/error-driver-runtimeexception.rst
4445

4546
Behavior
4647
--------
4748

4849
.. include:: /includes/extracts/note-bson-comparison.rst
50+
.. include:: /includes/extracts/bulkwriteexception-result.rst
4951

5052
Example
5153
-------

‎docs/reference/method/MongoDBCollection-deleteOne.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,14 @@ Errors/Exceptions
4242

4343
.. include:: /includes/extracts/error-unsupportedexception.rst
4444
.. include:: /includes/extracts/error-invalidargumentexception.rst
45+
.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
4546
.. include:: /includes/extracts/error-driver-runtimeexception.rst
4647

4748
Behavior
4849
--------
4950

5051
.. include:: /includes/extracts/note-bson-comparison.rst
52+
.. include:: /includes/extracts/bulkwriteexception-result.rst
5153

5254
Example
5355
-------

‎docs/reference/method/MongoDBCollection-insertMany.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,15 @@ Errors/Exceptions
3939
-----------------
4040

4141
.. include:: /includes/extracts/error-invalidargumentexception.rst
42+
.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
4243
.. include:: /includes/extracts/error-driver-runtimeexception.rst
4344

45+
Behavior
46+
--------
47+
48+
.. include:: /includes/extracts/bulkwriteexception-result.rst
49+
.. include:: /includes/extracts/bulkwriteexception-ordered.rst
50+
4451
Example
4552
-------
4653

‎docs/reference/method/MongoDBCollection-insertOne.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,14 @@ Errors/Exceptions
3939
-----------------
4040

4141
.. include:: /includes/extracts/error-invalidargumentexception.rst
42+
.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
4243
.. include:: /includes/extracts/error-driver-runtimeexception.rst
4344

45+
Behavior
46+
--------
47+
48+
.. include:: /includes/extracts/bulkwriteexception-result.rst
49+
4450
Example
4551
-------
4652

‎docs/reference/method/MongoDBCollection-replaceOne.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,14 @@ Errors/Exceptions
4242

4343
.. include:: /includes/extracts/error-unsupportedexception.rst
4444
.. include:: /includes/extracts/error-invalidargumentexception.rst
45+
.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
4546
.. include:: /includes/extracts/error-driver-runtimeexception.rst
4647

4748
Behavior
4849
--------
4950

5051
.. include:: /includes/extracts/note-bson-comparison.rst
52+
.. include:: /includes/extracts/bulkwriteexception-result.rst
5153

5254
Example
5355
-------

‎docs/reference/method/MongoDBCollection-updateMany.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,14 @@ Errors/Exceptions
4040

4141
.. include:: /includes/extracts/error-unsupportedexception.rst
4242
.. include:: /includes/extracts/error-invalidargumentexception.rst
43+
.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
4344
.. include:: /includes/extracts/error-driver-runtimeexception.rst
4445

4546
Behavior
4647
--------
4748

4849
.. include:: /includes/extracts/note-bson-comparison.rst
50+
.. include:: /includes/extracts/bulkwriteexception-result.rst
4951

5052
Examples
5153
--------

0 commit comments

Comments
 (0)