Replace Documents

On this page

Overview

Replace One Method
Replace Operation Parameters
Replace One Example

Overview

In this guide, you can learn how to replace documents in a MongoDB collection. A replace operation specifies the fields and values to replace a single document from your collection.

Replace One Method

A replace operation substitutes one document from your collection. The substitution occurs between a document your query filter matches and a replacement document.

The replaceOne() method removes all the existing fields and values in the matching document (except the _id field) and substitutes it with the replacement document.

You can call the replaceOne() method on a MongoCollection instance as follows:

collection.replaceOne(<query>, <replacement>);

Replace Operation Parameters

The replaceOne() method has the following parameters:

query specifies a query filter with the criteria to match a document to replace in your collection.
replacement specifies fields and values of a new Document object to replace the matched document.
(Optional) replaceOptions specifies options that you can set to customize how the driver performs the replace operation. To learn more about this type, see the API documentation for ReplaceOptions.

Replace One Example

In this example, a paint store sells five different colors of paint. The paint_inventory collection represents their current inventory:

{ "_id": 1, "color": "red", "qty": 5 }
{ "_id": 2, "color": "purple", "qty": 8 }
{ "_id": 3, "color": "yellow", "qty": 0 }
{ "_id": 4, "color": "green", "qty": 6 }
{ "_id": 5, "color": "pink", "qty": 0 }

The paint store realizes they must update their inventory again. What they thought was 20 cans of pink paint is actually 25 cans of orange paint.

To update the inventory, call the replaceOne() method specifying the following:

A query filter that matches documents where the color is "pink"
A replacement document where the color is "orange" and the qty is "25"

Bson filter = Filters.eq("color", "pink");
Document document = new Document("color", "orange").append("qty", 25);
// Replaces the first document that matches the filter with a new document
UpdateResult result = collection.replaceOne(filter, document);
// Prints the number of matched and modified documents
System.out.println("Matched document count: " + result.getMatchedCount());
System.out.println("Modified document count: " + result.getModifiedCount());

The output of the preceding code resembles the following:

 Matched document count: 1
 Modified document count: 1

The following shows the updated document:

 { "_id": 5, "color": "orange", "qty": 25 }

If multiple documents match the query filter specified in the replaceOne() method, it replaces the first result. You can specify a sort in a ReplaceOptions instance to apply an order to matched documents before the server performs the replace operation, as shown in the following code:

ReplaceOptions options = ReplaceOptions.sort(ascending("qty"));
UpdateResult result = collection.replaceOne(filter, document, options);

If zero documents match the query filter in the replace operation, replaceOne() makes no changes to documents in the collection. See our upsert guide to learn how to insert a new document instead of replacing one if no documents match.

Important

The replaceOne() method cannot make changes to a document that violate unique index constraints on the collection. For more information about constraints on unique indexes, see Unique Indexes in the MongoDB Server manual.

Back

Upsert

Delete Documents