We might encounter situations where we need to delete a document and immediately replace it with another one. We could achieve this by running two separate methods, .deleteOne(), then .insertOne(). Fortunately, MongoDB provides us with a single method, .replaceOne(), that can both delete and insert all at once!

The .replaceOne() method replaces the first document in a collection that matches the given filter. The syntax for this method looks as follows:

db.<collection>.replaceOne( <filter>, <replacement>, <options> );

Note in the syntax above that the .replaceOne() method takes three arguments:

  • filter: A document that provides selection criteria for the document to replace.
  • replacement: The replacement document.
  • options: A document where we can include optional fields to provide more specifications to our operation, such as upsert.

The replacement document can contain a subset of fields of the original document or entirely unique fields. To see it in action, consider a collection named employees with the following documents:

{ _id: ObjectId(...), name: "Rohit Kohli", department: "Customer Analytics" position: "Senior Software Engineer" }, { _id: ObjectId(...), name: "Rin Paterson", department: "People Operations", position: "Head of People Operations" }

Imagine "Rohit Kohli" leaves the company. We still want to store their name, and update their position to "N/A" but no longer need a department field and value. We’d then need to replace Rohit’s current document with a new document that only contains two fields: name, and position. We can accomplish this with .replaceOne():

db.employees.replaceOne( { name: "Rhoit Kohli" }, { name: "Rohit Kohli", position: "N/A" } );

If successful, this would produce the following output:

{ acknowledged: true, insertedId: null, matchedCount: 1, modifiedCount: 1, upsertedCount: 0 }

After running this command, we’d be left with the following collection:

{ _id: ObjectId(...), name: "Rohit Kohli", position: "N/A" }, { _id: ObjectId(...), name: "Gary Paterson", department: "HR", position: "Head of Human Resources" }

Notice how the other fields were completely removed. This is the key difference between .replaceOne() and .updateOne(). Whereas .updateOne() updates specific fields based on the update modifiers provided, .replaceOne() replaces the entire document and will only include fields specified in the <replacement> parameter.

Now let’s practice what we’ve learned about .replaceOne() with the following exercises.



Connect to the restaurants database. Then, using the listingsAndReviews collection, query for all the documents with the name "Tasty House".


Unfortunately the restaurant has recently shut down. Replace the document with the following information:

{ name: "Tasty House", shut_down: true }

Query the listingsAndReviews collection again for all the documents with the name "Tasty House" to confirm our document changed and the restaurant was successfully marked as shut down.

Take this course for free

Mini Info Outline Icon
By signing up for Codecademy, you agree to Codecademy's Terms of Service & Privacy Policy.

Or sign up using:

Already have an account?