Compound Operations

Find and Update

To find and update one document, use the findOneAndUpdate() method of the MongoCollection class. The findOneAndUpdate() method returns your found document or null if no documents match your query.

// <MongoCollection set up code here>
// Creates a projection to exclude the "_id" field from the retrieved documents
Bson projection = Projections.excludeId();
// Creates a filter to match documents with a "color" value of "green"
Bson filter = Filters.eq("color", "green");
// Creates an update document to set the value of "food" to "pizza"
Bson update = Updates.set("food", "pizza");
// Defines options that specify projected fields, permit an upsert and limit execution time
FindOneAndUpdateOptions options = new FindOneAndUpdateOptions().
        projection(projection).
        upsert(true).
        maxTime(5, TimeUnit.SECONDS);
// Updates the first matching document with the content of the update document, applying the specified options
Document result = collection.findOneAndUpdate(filter, update, options);
// Prints the matched document in its state before the operation
System.out.println(result.toJson());

{"food": "pizza", "color": "green"}

Find and Replace

To find and replace one document, use the findOneAndReplace() method of the MongoCollection class. The findOneAndReplace() method returns your found document or null if no documents match your query.

{"music": "classical", "color": "green"}

// <MongoCollection set up code here>
// Creates instructions to replace the matching document with a new document
Bson filter = Filters.eq("color", "green");
Document replace = new Document("music", "classical").append("color", "green");
// Defines options specifying that the operation should return a document in its post-operation state
FindOneAndReplaceOptions options = new FindOneAndReplaceOptions().
        returnDocument(ReturnDocument.AFTER);
// Atomically finds and replaces the matching document and prints the replacement document
Document result = collection.findOneAndReplace(filter, replace, options);
System.out.println(result.toJson());

{"_id": 1, "music": "classical", "color": "green"}

Find and Delete

To find and delete one document, use the findOneAndDelete() method of the MongoCollection class. The findOneAndDelete() method returns your found document or null if no documents match your query.

// <MongoCollection set up code here>
Bson sort = Sorts.descending("_id");
// Creates an empty filter to match all documents in the collection
Bson filter = Filters.empty();
// Defines options that specify a descending sort on the "_id" field
FindOneAndDeleteOptions options = new FindOneAndDeleteOptions().
        sort(sort);
// Deletes the document containing the highest "_id" value and prints the deleted document
Document result = collection.findOneAndDelete(filter, options);
System.out.println(result.toJson());

{"_id": 2, "food": "pear", "color": "yellow"}

Example With Race Condition

Let's say our app uses this bookARoom method to checkout our room to a guest:

public void bookARoom() {
    // Creates a filter to match documents representing available rooms
    Bson filter = Filters.eq("reserved", false);
    // Retrieves a document that represents the first available room
    Document myRoom = this.collection.find(filter).first();
    // Prints a message if no documents representing available rooms are found
    if (myRoom == null){
        System.out.println("Sorry, we are booked " + this.guest);
        return;
    }
    String myRoomName = myRoom.getString("room");
    // Prints a message that guest that successfully booked the room
    System.out.println("You got the " + myRoomName + " " + this.guest);
    // Creates an update document to mark a room as reserved
    Bson update = Updates.combine(Updates.set("reserved", true), Updates.set("guest", guest));
    
    // Creates a filter that matches the "_id" field of the first available room
    Bson roomFilter = Filters.eq("_id", myRoom.get("_id", Integer.class));
    // Updates the first matching document to mark it as reserved
    this.collection.updateOne(roomFilter, update);
}

Imagine two separate guests, Jan and Pat, try to book the room with this method at the same time.

Jan sees this output:

You got the Blue Room Jan

And Pat sees this output:

You got the Blue Room Pat

When we look at our database, we see the following:

 {"_id": 1, "guest": "Jan", "room": "Blue Room", "reserved": true}

Pat will be unhappy. When Pat shows up to our hotel, Jan will be occupying her room. What went wrong?

Here is the sequence of events that happened from the perspective of our MongoDB instance:

• Find and return an empty room for Jan

• Find and return an empty room for Pat

• Update the room to booked for Pat

• Update the room to booked for Jan

Notice that for a brief moment Pat had reserved the room, but as Jan's update operation was the last to execute our document has "Jan" as the guest.

Example Without Race Condition

Let's use a compound operation to avoid the race condition and always give our users the correct message.

public void bookARoom(){
    // Creates an update document to mark a room as reserved
    Bson update = Updates.combine(Updates.set("reserved", true), Updates.set("guest", guest));
    
    // Creates a filter to match a document representing an available room
    Bson filter = Filters.eq("reserved", false);
    // Updates the first document that matches the filter to mark it as reserved
    Document myRoom = this.collection.findOneAndUpdate(filter, update);
   
    // Prints a message when there are no available rooms
    if (myRoom == null){
        System.out.println("Sorry, we are booked " + this.guest);
        return;
    }
    // Prints the name of the guest that successfully booked the room
    String myRoomName = myRoom.getString("room");
    System.out.println("You got the " + myRoomName + " " + this.guest);
}

Imagine two separate guests, Jan and Pat, try to book the room with this method at the same time.

Jan sees this output:

You got the Blue Room Jan

And Pat sees this output:

Sorry, we are booked Pat

When we look at our database, we see the following:

 {"_id":1, "guest":"Jan", "room":"Blue Room", "reserved":true}

Pat got the correct message. While she might be sad she didn't get the reservation, at least she knows not to travel to our hotel.

Here is the sequence of events that happened from the perspective of our MongoDB instance:

• Find an empty room for Jan and reserve it.

• Try to find an empty room for Pat and reserve it. As there are not any rooms left, return null.

For information on the Updates class, see our guide on the Updates builder.

For more information of the Filters class, see our guide on the Filters builder.

For more information on the findOneAndUpdate() method, see the API Documentation for the MongoCollection class.