MongoDB upsert example using Mongo Shell and Java Driver

MongoDB upsert option is used with update method which creates a new document if the query does not retrieve any documents satisfying the criteria. The default value for this option is false. The upsert option does an insert based on the field and value pairs specified in the update parameter or field and value pairs specified in both query and update parameter.

Upsert option set for update

This operation first searches for the document if not present then inserts the new document into the database.

The car with the name Qualis is checked for existence and if not, a document with car name “Qualis” and speed 50 is inserted into the database. The nUpserted with value “1” indicates a new document is inserted.

Note that to avoid inserting the same document more than once, create an index on the name field thereby ensuring that the document will be inserted only once for the upsert option on every update specified. If the upsert fails because of duplicate index key error, retrying results in the successful update operation.


The upsert operation can be used for multiple documents or in bulk with the methods-update, updateOne and replaceOne.

The syntax for upsert option is

Upsert option set for find() method in bulk

The upsert operation for multiple documents in find method inserts a single document if the query does not satisfy the criteria as specified in the input parameter.

This operation first initialize and creates an unordered bulk list named “car” and then calls the find method with upsert option in update. The Insert field and value pairs are specified with $setOnInsert tag to insert if the document is not present. The $set is specified to update the “cno” for the car if the document already exists. Finally bulk execute method is called to execute either the insert or update statements. Since the document is not present insertion is done first and upon that the cno is updated for the inserted record.

Upsert option set for updateOne method in bulk

This method accepts parameters for updation as field/key and value pairs.

This creates an unordered bulk list with upsert option and inserts the “ferrari” document if not found in the updateOne method using the field and value pairs specified.

Upsert set for updateOne using update operators

This uses the update operators for setting the values for the fields. $setOnInsert and $set are the operators.

The value of name is set using $setonInsert and update is done using $set operators.

Upsert option set for replaceOne method in bulk

This performs an insert using the replaceOne method by accepting field and value pairs only as the argument.

This performs an insertion of document and this inserted document is the replacement document.

Java Program for MongoDB upsert

In this section we will write a java program to work on the upsert option with update, updateOne and replaceOne methods.

Output of the above program when executed for a collection that doesn’t exists produce following results.

That’s all for MongoDB upsert method with different scenario examples, we will look into more of MongoDB features in coming posts.

By admin

Leave a Reply