Updates Builders

On this page

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

Overview

In this guide, you can learn how to specify updates by using builders in the MongoDB Kotlin Driver.

The Updates builder provides helper methods for the following types of updates:

Field Updates
Array Updates
Combining Multiple Update Operators

Some methods that expect updates 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 class:

import com.mongodb.client.model.Updates.*

The examples in this guide use the following document:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

This example is modeled by the following data class unless otherwise noted:

data class PaintOrder (
    @BsonId val id: Int,
    val color: String,
    val qty: Int?,
    val vendor: List<Vendor>?,
    val lastModified: LocalDateTime?
)
data class Vendor (
    val name: String,
)

Field Updates

Set

Use the set() method to assign the value of a field in an update operation.

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

val filter = Filters.eq("_id", 1)
val update = Updates.set(PaintOrder::qty.name, 11)
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 11,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Unset

Use the unset() method to delete the value of a field in an update operation.

The following example deletes the qty field:

val filter = Filters.eq("_id", 1)
val update = Updates.unset(PaintOrder::qty.name)
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Set On Insert

Use the setOnInsert() 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 color field to "pink" if the operation resulted in the insert of a document:

val filter = Filters.eq("_id", 1)
val update = Updates.setOnInsert(PaintOrder::color.name, "pink")
collection.updateOne(filter, update, UpdateOptions().upsert(true))

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

{
   "_id": 1,
   "color": "pink"
}

Note

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

Increment

Use the inc() method to increment the value of a numeric field in an update operation.

The following example increments the value of the qty field, which was 5, by 3:

val filter = Filters.eq("_id", 1)
val update = Updates.inc(PaintOrder::qty.name, 3)
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 8,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Multiply

Use the mul() method to multiply the value of a numeric field in an update operation.

The following example multiplies the value of the qty field, which was 5, by 2:

val filter = Filters.eq("_id", 1)
val update = Updates.mul(PaintOrder::qty.name, 2)
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 10,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Rename

Use the rename() method to rename the value of a field in an update operation.

The following example renames the qty field to quantity:

val filter = Filters.eq("_id", 1)
val update = Updates.rename(PaintOrder::qty.name, "quantity")
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" },
   "quantity": 5,
}

Min

Use the min() method to set the value of the field to the given value if the given value is less than the current value of the field.

The following example updates the qty field to 2 because 2 is less than the current value of the qty field (5):

val filter = Filters.eq("_id", 1)
val update = Updates.min(PaintOrder::qty.name, 2)
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 2,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Max

Use the max() method to update the value of a field with the larger number of the two specified in an update operation.

The following example updates the qty field to 8 because 8 is greater than the current value of the qty field (5):

val filter = Filters.eq("_id", 1)
val update = Updates.max(PaintOrder::qty.name, 8)
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 8,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Current Date

Use the currentDate() method to assign the value of a field in an update operation to the current date as a BSON date.

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

val filter = Filters.eq("_id", 1)
val update = Updates.currentDate(PaintOrder::lastModified.name)
collection.updateOne(filter, update)

Since we wrote this page on June 16, 2023, the preceding example updates the original document to the following state:

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "$date": "2023-06-16T17:13:06.373Z"
}

Current Timestamp

Use the currentTimestamp() method to assign the value of a field in an update operation to the current date as a timestamp.

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

// Create a new instance of the collection with the flexible `Document` type
// to allow for the changing of the `lastModified` field to a `BsonTimestamp`
// from a `LocalDateTime`.
val collection = database.getCollection<Document>("paint_orders")
val filter = Filters.eq("_id", 1)
val update = Updates.currentTimestamp(PaintOrder::lastModified.name)
collection.updateOne(filter, update)

Since we wrote this page on June 16, 2023, the preceding example updates the original document to the following state:

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

Bit

Use the bitwiseOr(), bitwiseAnd(), and bitwiseXor() 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 (5):

val filter = Filters.eq("_id", 1)
val update = Updates.bitwiseOr(PaintOrder::qty.name, 10)
collection.updateOne(filter, update)

The bitwise operation results in 15:

0101 // bit representation of 5
1010 // bit representation of 10
----
1111 // bit representation of 15

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

{
   "_id": 1,
   "color": "red",
   "qty": 15,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Array Updates

Add to Set

Use the addToSet() method to append a value to an array if the value is not already present in an update operation.

The following example adds a Vendor instance that has a name value of "C" to the vendor array:

val filter = Filters.eq("_id", 1)
val update = Updates.addToSet(PaintOrder::vendor.name, Vendor("C"))
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" },
      { "name": "C" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Pop

Use the popFirst() method to remove the first element of an array and the popLast() method to remove the last element of an array in an update operation.

The following example removes the first entry of the vendor array:

val filter = Filters.eq("_id", 1)
val update = Updates.popFirst(PaintOrder::vendor.name)
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Pull All

Use the pullAll() method to remove all instances of specified values from an existing array in an update operation.

The following example removes Vendor instances that have name values of "A" and "M" from the vendor array:

val filter = Filters.eq("_id", 1)
val update = Updates.pullAll(PaintOrder::vendor.name, listOf(Vendor("A"), Vendor("M")))
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "D" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Pull

Use the pull() method to remove all instances of a specified value from an existing array in an update operation.

The following example removes Vendor instances that have a name value of "D" from the vendor array:

val filter = Filters.eq("_id", 1)
val update = Updates.pull(PaintOrder::vendor.name, Vendor("D"))
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Push

Use the push() method to append a value to an array in an update operation.

The following example adds a Vendor instance that has a name value of "Q" to the vendor array:

val filter = Filters.eq("_id", 1)
val update = Updates.push(PaintOrder::vendor.name, Vendor("Q"))
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" },
      { "name": "Q" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

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 adds a Vendor instance that has a name value of "R" to the vendor field:

val filter = Filters.eq("_id", 1)
val update = Updates.combine(
    Updates.set(PaintOrder::color.name, "purple"),
    Updates.inc(PaintOrder::qty.name, 6),
    Updates.push(PaintOrder::vendor.name, Vendor("R"))
)
collection.updateOne(filter, update)

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

{
   "_id": 1,
   "color": "purple",
   "qty": 11,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" },
      { "name": "R" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Back

Sort

Aggregation