MongoDB – db.collection.findOneAndUpdate() Method

The findOneAndUpdate() method updates the first matched document in the collection that matches the selection criteria. If more than one document matched the selection criteria then it updates only the first matched document. When we update the document, the value of the _id field remains unchanged. This method will return the original document but if we want to return the updated document then we have to set the value of the returnNewDocument parameter to true. It takes three parameters, the first one is the selection criteria, the second one is the new data to be updated, and the remaining are optional. Using this method you can also replace embedded documents. You can also use this method in multi-document transactions.

Syntax:

db.collection.findOneAndUpdate(

selection_criteria: <document>,

update_data: <document>, 

{

   projection: <document>,

    sort: <document>,

    maxTimeMS: <number>,

    upsert: <boolean>,

    returnNewDocument: <boolean>,

    collation: <document>,

    arrayFilters: [ <filterdocument1>, … ]

})

Parameters:

• The first parameter is the selection criteria for the update. The type of this parameter is document.
• The second parameter is a document that to be updated. The type of this parameter is document.
• The third parameter is optional.

Optional Parameters:

• projection: The type of this parameter is document. The projection parameter determines which fields are returned to the matching documents.

This document takes:

{ field1: <value1>, field2: <value2> ... }

Here if the value of the field is 1/true then it specifies the inclusion of the field, or if the value of the field is 0/false then it specifies the exclusion of the field.

• sort: Determines which document the operation will modify if the query selects multiple documents. findOneAndupdate() will update the first document in the sort order specified by this argument. The type of this parameter is document.
• maxTimeMS: The type of this parameter is number. It specifies the time limit in milliseconds within which the operation must complete. It will give an error if the limit is exceeded.
• upsert: The default value of this parameter is false. If the value of this option is set to true and no document matches the given filter query, then this method creates a new document and returns null(after inserting a new document) unless the value of returnNewDocument option is set to true. Or if the value of this upsert option is set to true, then this method updates the document that matches the given filter query.
• returnNewDocument: The type of this parameter is boolean. By default, this method returns the original document. To return the updated document, use the returnNewDocument and set its value to true.
• Collation: It specifies the use of the collation for operations. It allows users to specify the language-specific rules for string comparison like rules for lettercase and accent marks. The type of this parameter is a document.
• arrayFilters: It is an array of filter documents that indicates which array elements to modify for an update operation on an array field. The type of this parameter is an array.

Return:

It returns the original document but if we want to return the updated document then we have to set the value of the returnNewDocument parameter to true.

Examples:

In the following examples, we are working with:

Database: gfg

Collections: student

Document: Three documents contains the details of the students

• Update the first matched document:

db.student.findOneAndUpdate({name:"Nikhil"},{$inc:{score:4}})

Here, we update the first matched document according to the selection criteria(i.e., name:”Nikhil”) by a new document(i.e., {$inc:{score:4}} – the value of the score field is increase by 4) and return the original document:

After update:

• Update the value of the embedded document:

db.student.findOneAndUpdate({name:"Ashok"},{$inc:{"score.math":50}})

Here, we update the value of the math field in the embedded document.

After update:

• Update the first matched document and return the updated document:

 db.student.findOneAndUpdate({name:"Vishal"},{$inc:{score:4}},{returnNewDocument:true})

Here, we update the first matched document according to the selection criteria(i.e., name:”Vishal”) by a new document(i.e., {$inc:{score:4}} – the value of the score field is increase by 4) and return the new updated document because we set the value of the returnNewDocument to true.