Replace Documents

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Replace Documents

Overview

In this guide, you can learn how to use the Java Reactive Streams driver to replace a document in a MongoDB collection by performing a replace operation.

A replace operation replaces one document in a MongoDB collection with new fields and values that you specify. You can perform a replace operation by using the replaceOne() method.

Sample Data

The examples in this guide use the sample_restaurants.restaurants collection from the Atlas sample datasets.

To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the [Get Started](https://www.mongodb.com/docs/languages/java/reactive-streams-driver/current/getting-started.md#std-label-java-rs-getting-started tutorial.

Important: Project Reactor Library

This guide uses the Project Reactor library to consume Publisher instances returned by the Java Reactive Streams driver methods. To learn more about the Project Reactor library and how to use it, see [Getting Started](https://projectreactor.io/docs/core/release/reference/#getting-started in the Reactor documentation. To learn more about how we use Project Reactor library methods in this guide, see the [Write Data to MongoDB](https://www.mongodb.com/docs/languages/java/reactive-streams-driver/current/crud.md#std-label-write-data-reactor-overview guide.

Replace Operation

You can perform a replace operation by using the replaceOne() method on a MongoCollection instance. This method removes all fields except the _id field from the first document that matches the search criteria, then adds the fields and values you specify to the empty document.

Required Parameters

The replaceOne() method requires the following parameters:

• Query filter document, which determines which documents to replace. For more information about query filters, see the [Specify a Query](https://www.mongodb.com/docs/languages/java/reactive-streams-driver/current/crud/query-documents/specify-a-query.md#std-label-java-rs-specify-query guide.

• Replace document, which specifies the fields and values to insert in the new document.

Replace Example

To replace a single document in a MongoDB collection, call the replaceOne() method and pass the query filter document and the replace document as parameters. Then, pass the replaceOne() result to the static Mono.from() method from Mono. Mono is a class from the Project Reactor library. In Java Reactive Streams, the driver methods return cold Publisher instances, which means that the corresponding operation does not happen unless you subscribe to the returned Publisher. This guide uses the Project Reactor library to consume them. To learn more about Mono, see [Mono](https://projectreactor.io/docs/core/release/reference/#mono in the Project Reactor documentation.

The following example uses the replaceOne() method to replace the fields and values of a document with a name field value of “Pizza Town”. The replaceOne() method replaces the original document with a document that has a name field value of “Mongo's Pizza” and a cuisine field value of “Pizza”.

 Publisher<UpdateResult> replacePublisher = restaurants.replaceOne(
         eq("name", "Pizza Town"),
         new Document().append("name", "Mongo's Pizza")
                 .append("cuisine", "Pizza"));
 Mono.from(replacePublisher).block();

Modify Replace Behavior

You can optionally modify the behavior of the replaceOne() method by calling an options method. The ReplaceOptions class provides methods that modify the behavior of the replaceOne() method. To use the ReplaceOptions class, construct a new instance of the class, then call one or more of its methods to modify the replace operation. You can chain these method calls together. To modify the behavior of the replace operation, pass the class instance and chained method calls as the last argument to the replaceOne() method.

You can use the following methods in the ReplaceOptions class to modify the replaceOne() method.

Modify Replace Example

The following code uses the replaceOne() method to replace a document in the restaurants collection. It also sets the upsert(true) option so that the driver inserts a new document if the query filter doesn't match any existing documents.

Publisher<UpdateResult> replacePublisher = restaurants.replaceOne(
        eq("name", "Food Town"),
        new Document().append("name", "Food World")
                .append("cuisine", "Mixed"),
        new ReplaceOptions().upsert(true));
Mono.from(replacePublisher).block();

Return Value

The replaceOne() method returns an UpdateResult object. Use the following methods from the UpdateResult type to access the corresponding information:

Additional Information

For runnable code examples of replacing documents with the Java Reactive Streams driver, see the [CRUD Operations](https://www.mongodb.com/docs/languages/java/reactive-streams-driver/current/crud.md#std-label-java-rs-write guide.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

• [replaceOne()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-reactive-streams/com/mongodb/reactivestreams/client/MongoCollection.html#replaceOne(org.bson.conversions.Bson,TDocument)

• ReplaceOptions

• UpdateResult

• BsonValue