diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index 1a2477b2d..8af873102 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -623,6 +623,54 @@ Even though the write operation inserting a document with a duplicate key result in an error, the other operations are executed because the write operation is unordered. +.. _java-bulk-insert-troubleshooting: + +Troubleshooting +--------------- + +Bulk Write Exception +~~~~~~~~~~~~~~~~~~~~ + +If the driver encounters an error during a bulk write operation, the driver +throws a `MongoBulkWriteException. +<{+core-api+}/MongoBulkWriteException.html>`__ A ``MongoBulkWriteException`` +contains a ``writeErrors`` field consisting of a list of one or more +``WriteError`` objects associated with the same bulk write operation. + +Consider a collection that has a schema validation rule where the value of the +``quantity`` field must be an ``int`` type. In the following example, the driver +throws a ``MongoBulkWriteException`` when you attempt to insert a document with +a ``quantity`` field value of ``"three"`` and another with a ``quantity`` field +value of ``"ten"``. + +.. code-block:: none + :copyable: false + :emphasize-lines: 1-2, 6-9, 13-16 + + Exception in thread "main" com.mongodb.MongoBulkWriteException: Bulk write + operation result had errors at + com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:258) + ... at + BulkWriteMultipleValidationErrorsExample.main(BulkWriteMultipleValidationErrorsExample.java:30) + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Apple","quantity":"three"} }} at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + ... 19 more + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Banana","quantity":"ten"} }} at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + at + com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + ... 19 more + +To learn more about schema validation, see Schema Validation in the Server +Manual Entries section. + Additional Information ---------------------- @@ -637,6 +685,7 @@ MongoCollection - `bulkWrite() <{+driver-api+}/MongoCollection.html#bulkWrite(com.mongodb.client.ClientSession,java.util.List)>`__ - `BulkWriteOptions <{+core-api+}/client/model/BulkWriteOptions.html>`__ +- `WriteError <{+core-api+}/WriteError.html>`__ - `MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__ MongoClient @@ -651,3 +700,4 @@ Server Manual Entries - :manual:`MongoCollection.bulkWrite() ` - :manual:`MongoClient.bulkWrite() ` +- :manual:`Schema Validation ` diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 84a9cc5c6..92fb1e96f 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -15,7 +15,7 @@ Insert Operations .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol Overview @@ -189,6 +189,40 @@ operation and an insert many operation: insertOne() document id: BsonObjectId{value=...} insertMany() document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}} +.. _java-insert-troubleshooting: + +Troubleshooting +--------------- + +Write Exception +~~~~~~~~~~~~~~~ + +The driver throws a `MongoWriteException +<{+core-api+}/MongoWriteException.html>`__ for any write errors that occur when +performing single write operations. A ``MongoWriteException`` object has an +``error`` field containing the ``WriteError`` object that caused it. + +Consider a collection that has a schema validation rule where the value of the +``quantity`` field must be an ``int`` type. In the following example, the driver +throws a ``MongoWriteException`` if you attempt to insert a document where the +value of ``quantity`` is ``"three"``. + +.. code-block:: none + :copyable: false + :emphasize-lines: 1, 4-7 + + Exception in thread "main" com.mongodb.MongoWriteException: Document failed validation at + com.mongodb.internal.connection.ProtocolHelper.getWriteException(ProtocolHelper.java:228) + ... + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Apple","quantity":"three"} } } at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + +To learn more about schema validation, see Schema Validation in the Server +Manual Entries section. + Additional Information ---------------------- @@ -202,8 +236,14 @@ For more information about the methods and classes used to insert documents, see - `insertMany() <{+driver-api+}/MongoCollection.html#insertMany(java.util.List)>`__ - `InsertManyResult <{+core-api+}/client/result/InsertManyResult.html>`__ +For more information about the error types discussed in the Troubleshooting section, see the following API documentation: + +- `WriteError <{+core-api+}/WriteError.html>`__ +- `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ + Server Manual Entries ~~~~~~~~~~~~~~~~~~~~~ - :manual:`db.collection.insertOne() ` - :manual:`db.collection.insertMany() ` +- :manual:`Schema Validation `