MongoDB Replace Documents Using MongoShell (original) (raw)

Last Updated : 05 Mar, 2025

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(
,
,
{
upsert: ,
writeConcern: ,
collation: ,
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.