Updates Builders

Updates Builders
- Updates Builders
- Overview
- Field Updates
  - Set
  - Unset
  - Set On Insert
  - Increment
  - Multiply
  - Rename
  - Min
  - Max
  - Current Date
  - Current Timestamp
  - Bit
- Array Updates
  - Add to Set
  - Pop
  - Pull All
  - Pull
  - Push
- Combining Multiple Update Operators

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

Updates Builders

Overview

In this guide, you can learn how to specify updates by using [builders](https://www.mongodb.com/docs/languages/java/reactive-streams-driver/current/builders.md#std-label-java-rs-builders in the Java Reactive Streams driver.

The Updates builder provides helper methods to simplify the following tasks:

[Field Updates](https://www.mongodb.com/docs/languages/java/reactive-streams-driver/current/builders/updates.md#std-label-java-rs-field-updates: Updating or removing the value of a particular field
[Array Updates](https://www.mongodb.com/docs/languages/java/reactive-streams-driver/current/builders/updates.md#std-label-java-rs-array-updates: Updating values in an array-valued field
[Combining Multiple Update Operators](https://www.mongodb.com/docs/languages/java/reactive-streams-driver/current/builders/updates.md#std-label-java-rs-multiple-updates: Performing multiple updates at once, such as setting or changing more than one field

Some methods that expect update documents are:

updateOne()
updateMany()
bulkWrite()

The Updates class provides static factory methods for all the MongoDB update operators. Each method returns an instance of the BSON type, which you can pass to any method that expects an update argument.

Tip:

For brevity, you may choose to import the methods of the Updates and Filters class statically:

import static com.mongodb.client.model.Updates.*;
import static com.mongodb.client.model.Filters.*;

The following examples assume this static import.

The examples in this guide use the following document:

{
    "_id": 1,
    "color": "red",
    "qty": 5,
    "vendor": [ "A", "D", "M" ],
    "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Field Updates

Set

Use the [set()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#set(java.lang.String,TItem) method to assign the value of a field in an update operation.

The following example sets the value of the qty field to “11”:

Bson filter = eq("_id", 1);
Bson update = set("qty", 11);
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 11,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

The following example adds two new fields to the original document:

Bson filter = eq("_id", 1);
Bson update = combine(set("width", 6.5), set("height", 10));
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" },
   "width": 6.5,
   "height": 10
}

Unset

Use the [unset()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#unset(java.lang.String) method to delete the value of a field in an update operation.

The following example deletes the qty field:

Bson filter = eq("_id", 1);
Bson update = unset("qty");
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Set On Insert

Use the [setOnInsert()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#setOnInsert(java.lang.String,TItem) method to assign the value of a field in an update operation on an insert of a document.

The following example sets the value of the qty field to “7” if an upsert resulted in the insert of a document:

Bson filter = eq("_id", 1);
Bson update = setOnInsert("qty", 7);
Publisher<UpdateResult> result = collection.updateOne(filter, update, new UpdateOptions().upsert(true));
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 7,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Note:

If the document is not inserted, no change will occur.

Increment

Use the [inc()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#inc(java.lang.String,java.lang.Number) method to increment the value of a numeric field in an update operation.

The following example increments the value of the qty field by “3”:

Bson filter = eq("_id", 1);
Bson update = inc("qty", 3);
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 8,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Multiply

Use the [mul()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#mul(java.lang.String,java.lang.Number) method to multiply the value of a numeric field in an update operation.

The following example multiplies the value of the qty field by “2”:

Bson filter = eq("_id", 1);
Bson update = mul("qty", 2);
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 10,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Rename

Use the [rename()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#rename(java.lang.String,java.lang.String) method to rename the value of a field in an update operation.

The following example renames the qty field to “quantity”:

Bson filter = eq("_id", 1);
Bson update = rename("qty", "quantity");
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" },
   "quantity": 5
}

Min

Use the [min()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#min(java.lang.String,TItem) method to update the value of a field with the smaller number of the two specified in an update operation.

The following example sets the value of the qty field to the minimum of its current value and “2”:

Bson filter = eq("_id", 1);
Bson update = min("qty", 2);
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 2,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Max

Use the [max()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#max(java.lang.String,TItem) method to update the value of a field with the larger number of the two specified in an update operation.

The following example sets the value of the qty field to the maximum of its current value and “8”:

Bson filter = eq("_id", 1);
Bson update = max("qty", 8);
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 8,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Current Date

Use the [currentDate()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#currentDate(java.lang.String) method to assign the value of a field in an update operation to the current date as a [BSON date.](https://www.mongodb.com/docs/manual/reference/bson-types/#date

The following example sets the value of the lastModified field to the current date as a BSON date:

Bson filter = eq("_id", 1);
Bson update = currentDate("lastModified");
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-22T21:01:20.027Z" }
}

Current Timestamp

Use the [currentTimestamp()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#currentTimestamp(java.lang.String) method to assign the value of a field in an update operation to the current date as a [timestamp.](https://www.mongodb.com/docs/manual/reference/bson-types/#timestamps

The following example sets the value of the lastModified field to the current date as a BSON timestamp:

Bson filter = eq("_id", 1);
Bson update = currentTimestamp("lastModified");
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$timestamp": { "t": 1616446880, "i": 5 } }
}

Bit

Use the [bitwiseOr()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#bitwiseOr(java.lang.String,int), [bitwiseAnd()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#bitwiseAnd(java.lang.String,int), and [bitwiseXor()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#bitwiseXor(java.lang.String,int) methods to perform a bitwise update of the integer value of a field in an update operation.

The following example performs a bitwise OR between the number “10” and the integer value of the qty field:

Bson filter = eq("_id", 1);
Bson update = bitwiseOr("qty", 10);
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

The bitwise operation results in 15:

0101  // 5 in binary
1010  // 10 in binary
----
1111 // 15 in binary

The preceding example updates the original document to the following state:

{
   "_id": 1,
   "color": "red",
   "qty": 15,
   "vendor": [ "A", "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Array Updates

Add to Set

Use the [addToSet()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#addToSet(java.lang.String,TItem) method to append a value to an array if the value is not already present in an update operation.

The following example adds the value “C” to the array value of the vendor field:

Bson filter = eq("_id", 1);
Bson update = addToSet("vendor", "C");
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [ "A", "D", "M", "C" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Pop

Use the [popFirst()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#popFirst(java.lang.String) method to remove the first element of an array and the [popLast()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#popLast(java.lang.String) method to remove the last element of an array in an update operation.

The following example pops the first element off of the array value of the vendor field:

Bson filter = eq("_id", 1);
Bson update = popFirst("vendor");
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [ "D", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Pull All

Use the [pullAll()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#pullAll(java.lang.String,java.util.List) method to remove all instances of values from an existing array in an update operation.

The following example removes vendor “A” and “M” from the vendor array:

Bson filter = eq("_id", 1);
Bson update = pullAll("vendor", Arrays.asList("A", "M"));
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [ "D" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Pull

Use the [pull()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#pull(java.lang.String,TItem) method to remove all instances of a value from an existing array in an update operation.

The following example removes the value “D” from the vendor array:

Bson filter = eq("_id", 1);
Bson update = pull("vendor", "D");
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [ "A", "M" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Push

Use the [push()](https://mongodb.github.io/mongo-java-driver/5.13/apidocs/driver-core/com/mongodb/client/model/Updates.html#push(java.lang.String,TItem) method to append a value to an array in an update operation.

The following examples pushes “C” to the vendor array:

Bson filter = eq("_id", 1);
Bson update = push("vendor", "C");
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [ "A", "D", "M", "C" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Combining Multiple Update Operators

An application can update multiple fields of a single document by combining two or more of the update operators described in the preceding sections.

The following example increments the value of the qty field by “6”, sets the value of the color field to “purple”, and pushes “R” to the vendor field:

Bson filter = eq("_id", 1);
Bson update = combine(set("color", "purple"), inc("qty", 6), push("vendor", "R"));
Publisher<UpdateResult> result = collection.updateOne(filter, update);
Mono.from(result).block();

Output:

{
   "_id": 1,
   "color": "purple",
   "qty": 11,
   "vendor": [ "A", "D", "M", "R" ],
   "lastModified": { "$date": "2021-03-05T05:00:00Z" }
}

Stable API

Updates Builders