MongoDB – Replace Documents Using MongoShell

In MongoDB, you are allowed to replace an existing document with a new document in the collection with the help of db.collection.replaceOne() method. This method will replace the existing document with the replacement document.

replaceOne() is a mongo shell method, which only replaces one document at a time. The replacement document may contain different fields as compared to the original document.

As we know that the _id field is immutable, so you can omit _id field in the replacement document. And if you want to add _id field in the replacement document, then the value of _id field is same as the current value and if you use a different value, then you will get an error.
The replacement document can only contain field-value pairs. It does not contain update operator expressions.
This method replaces the first document that satisfies the given condition in the collection with the replacement document. Or in other words, if multiple documents satisfy the given condition, then this method will replace the very first document with the replacement document that matches the given filter or condition.
This method can be used in the multi-document transactions.

Syntax:
db.collection.replaceOne(
   <filter>,
   <replacementDocument>,
   {
     upsert: <boolean>,
     writeConcern: <document>,
     collation: <document>,
     hint: <document|string>                   
   }
)
Parameters:

filter: First parameter of this method. It specifies the selection criteria for the update. The type of this parameter is document. If it contains empty document, i.e, {}, then this method will replace the first document of the collection with the replacement document.

replacementDocument: Second parameter of this method. It is a replacement document that will replace the original document. It does not contain update operations.

Optional Parameters:

upsert: The value of this parameter is either true or false. If the value of this parameter is true, then the method will replace the document that matches the given condition with the replacement document or if any of the documents in the collection does not match the given filter, then this method will insert a new document(i.e., replacementDocument) in the collection. The type of this parameter is a Boolean and the default value of this parameter is false.

writeConcern: It is only used when you do not want to use the default write concern. The type of this parameter is document.

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 document.

hint: It is a document or field that specifies the index to use to support the filter. It can take an index specification document or the index name string and if you specify an index that does not exist, then it will give an error.

Return: This method return a document that contain a boolean acknowledged as true (if the write concern is enabled) or false (if the write concern is disabled), matchedCount represents the total number of matched documents, modifiedCount represents the total number of modified documents, and upsertedId represents the _id of the upserted document. The upsertedId only appears in this document when the value of upsert parameter is set to true.

Examples:

In the following examples, we are working with:

Database: GeeksforGeeks
Collection: employee
Document: three documents that contain the details of the employees in the form of field-value pairs.

Replacing first Document:

In this example, we are going to replace the first document of the employee collection, i.e., {name: "Rohit", age: 20, branch: "CSE", department: "HR"} with the replacement document, i.e., {name: "Anu", age: 30, branch: "EEE", department: "HR", joiningYear: 2018} using the replaceOne() method.

db.collection.replaceOne({}, {replacement document})

Replacing single document that matches the filter:

In this example, we are replacing a document of the employee collection that matches the given condition or filter, i.e, name: "Sonu" with the replacement document, i.e., {name: "Sonu", age: 25, branch: "CSE", department: "Designing"} using the replaceOne() method. Or in other words, in this example we are replacing a document of an employee whose name is Sonu.

Replacing document:

In this example, we are replacing a document with a replacement document. Here, multiple documents match the filter, i.e., name: “Sonu”, so the replaceOne() method replaces the first document that matches the given condition among these documents as shown in the below images –

Before replacement:

After replacement:

Article Tags :

Computer Subject

MongoDB