Replace a Document
You can replace a single document using the replaceOne() method on
a MongoCollection object. This method removes all the existing fields
and values from a document (except the _id field) and substitutes it
with your replacement document.
The replaceOne() method accepts a query filter that matches the
document you want to replace and a replacement document that contains the
data you want to save in place of the matched document. The replaceOne()
method only replaces the first document that matches the filter.
You can optionally pass an instance of ReplaceOptions to the replaceOne() method in
order to specify the method's behavior. For example, if you set the upsert
field of the ReplaceOptions object to true, the operation inserts
a new document from the fields in the replacement document if no documents
match the query filter. See the link to the ReplaceOptions API
documentation at the bottom of this page for more information.
Upon successful execution, the replaceOne() method returns an instance
of UpdateResult. You can retrieve information such as the number of
documents modified by calling the getModifiedCount() method. You can also
retrieve the value of the document's _id field by calling the
getUpsertedId() method if you set upsert(true) in the
ReplaceOptions instance and the operation resulted in the insertion of a new document.
If your replacement operation fails, the driver raises an exception.
For example, if you try to specify a value for the immutable field
_id in your replacement document that differs from the original
document, the method throws a MongoWriteException with the message:
After applying the update, the (immutable) field '_id' was found to have been altered to _id: ObjectId('...)
If your replacement document contains a change that violates unique index
rules, the method throws a MongoWriteException with an error
message that resembles the following:
E11000 duplicate key error collection: ...
For more information about the types of exceptions raised under specific
conditions, see the API documentation for replaceOne(), linked at the
bottom of this page.
Example
In this example, we replace the first match of our query filter in the
movies collection of the sample_mflix database with a replacement
document. All the fields except for the _id field are deleted from the
original document and are substituted by the replacement document.
Before the replaceOne() operation runs, the original document contains
several fields describing the movie. After the operation runs, the resulting
document contains only the fields specified by the replacement document
(title and fullplot) and the _id field.
The following snippet uses the following objects and methods:
A query filter that is passed to the
replaceOne()method. Theeqfilter matches only movies with the title exactly matching the text'Music of the Heart'.A replacement document that contains the document that replaces the matching document if it exists.
A ReplaceOptions object with the
upsertoption set totrue. This option specifies that the method should insert the data contained in the replacement document if the query filter does not match any documents.
Note
This example connects to an instance of MongoDB using a connection URI. To learn more about connecting to your MongoDB instance, see the connection guide.
// Replaces the first document that matches a filter by using the Java driver package usage.examples; import static com.mongodb.client.model.Filters.eq; import org.bson.Document; import org.bson.conversions.Bson; import com.mongodb.MongoException; import com.mongodb.client.MongoClient; import com.mongodb.client.MongoClients; import com.mongodb.client.MongoCollection; import com.mongodb.client.MongoDatabase; import com.mongodb.client.model.ReplaceOptions; import com.mongodb.client.result.UpdateResult; public class ReplaceOne { public static void main(String[] args) { // Replace the uri string with your MongoDB deployment's connection string String uri = "<connection string uri>"; try (MongoClient mongoClient = MongoClients.create(uri)) { MongoDatabase database = mongoClient.getDatabase("sample_mflix"); MongoCollection<Document> collection = database.getCollection("movies"); Bson query = eq("title", "Music of the Heart"); // Creates a new document containing "title" and "fullplot" fields Document replaceDocument = new Document(). append("title", "50 Violins"). append("fullplot", " A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music"); // Instructs the driver to insert a new document if none match the query ReplaceOptions opts = new ReplaceOptions().upsert(true); // Replaces the first document that matches the filter with a new document UpdateResult result = collection.replaceOne(query, replaceDocument, opts); // Prints the number of modified documents and the upserted document ID, if an upsert was performed System.out.println("Modified document count: " + result.getModifiedCount()); System.out.println("Upserted id: " + result.getUpsertedId()); // Prints a message if any exceptions occur during the operation } catch (MongoException me) { System.err.println("Unable to replace due to an error: " + me); } } }
After you run the example, you should see output that looks something like this:
Modified document count: 1 Upserted id: null
Or if the example resulted in an upsert:
Modified document count: 0 Upserted id: BsonObjectId{value=...}
If you query the replaced document, the output resembles the following:
Document { { _id=..., title=50 Violins, fullplot=A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music } }
Tip
Legacy API
If you are using the legacy API, see our FAQ page to learn what changes you need to make to this code example.
For additional information on the classes and methods mentioned on this page, see the following API Documentation: