MongoDB - Replace Documents Using MongoShell

MongoDB provides various methods to modify documents in a collection. One of the most important methods is replaceOne(), which allows you to replace an entire document with a new one based on a filter.

This article will provide an in-depth explanation of how to replace documents in MongoDB using MongoShell, focusing on the replaceOne() method, its syntax, parameters, and real-world examples.

MongoDB replaceOne() Method

The replaceOne() method in MongoDB is used to replace a single document that matches a given filter with a completely new document. Unlike the updateOne() method, which allows us to update specific fields within a document, replaceOne() replaces the entire document. This method ensures that the original document is completely replaced by the new one, including all fields.

The method can also be configured to perform an upsert (insert a new document if no matching document is found) and return either the original or the modified document.

Syntax:

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

Parameters

1. filter: This is a document that defines the selection criteria. MongoDB will replace the first document that matches this filter.
   
2. replacementDocument: This is the new document that will replace the matched document. The document must not contain update operators (such as $set, $inc, etc.).
   
3. Optional Parameters:
   • upsert: If set to true, MongoDB will insert a new document if no document matches the filter. The default is false.
   • writeConcern: Specifies the write concern, defining the level of acknowledgment requested from MongoDB for write operations.
   • collation: Used to specify language-specific rules for string comparison, such as lettercase and accent marks.
   • hint: Allows specifying which index to use when querying documents.

Return

By default, replaceOne() returns an object that contains:

• acknowledged: Whether the write was acknowledged by the database.
• matchedCount: The number of documents that matched the filter.
• modifiedCount: The number of documents that were modified (replaced).
• upsertedId: The _id of the newly inserted document, if the upsert option was set to true.

Examples of MongoDB replaceOne()

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.
  

Example 1: Replace the 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.

Query:

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

Output:

Explanation: This command replaces the first document in the employee collection with the new document { name: "Anu", age: 30, branch: "EEE", department: "HR", joiningYear: 2018 }. The {} filter matches any document, so the first document in the collection will be replaced.

Example 2: 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.

Query:

db.employee.replaceOne(
  { name: "Sonu" },
  { name: "Sonu", age: 25, branch: "CSE", department: "Designing" }
);

Output:

Explanation:

This command finds the first document in the employee collection where the name is "Sonu" and replaces it with the new document { name: "Sonu", age: 25, branch: "CSE", department: "Designing" }.

Example 3: Replace a Document and Return the New 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:

Conclusion

The replaceOne() method is a powerful tool in MongoDB for replacing documents in a collection. Whether we're performing a simple replacement or handling more complex scenarios with upsert, collation, or sorting, replaceOne() offers a robust mechanism to modify documents. Understanding its parameters, such as upsert, writeConcern, and collation, will help us fine-tune your document replacement operations for efficient data management.