Docs Menu
Docs Home
/
Languages
/
Kotlin
/
Kotlin Coroutine

Update Arrays in a Document

On this page

  • Overview
  • Sample Document
  • Specifying an Update
  • Specifying Array Elements
  • The First Matching Array Element
  • Matching All Array Elements
  • Matching Multiple Array Elements

Overview

In this guide, you can learn how to update arrays in a document with the MongoDB Kotlin driver.

To update an array, you must do the following:

  • Specify the update you want to perform

  • Specify what array elements to apply your update to

  • Perform an update operation using these specifications

Sample Document

The following sections feature examples that update this sample document:

{ "_id": 1, "color": "green", "qty": [8, 12, 18] }

This data is modeled with the following Kotlin data class:

data class PaintOrder(
    @BsonId val id: Int,
    val qty: List<Int>,
    val color: String
)

The examples on this page use the findOneAndUpdate() method of the MongoCollection class to retrieve and update the document. Each example uses an instance of the FindOneAndUpdateOptions class to have MongoDB retrieve the document after the update occurs. For more information on the findOneAndUpdate() method, see our Compound Operations guide.

Specifying an Update

To specify an update, use the Updates builder. The Updates builder provides static utility methods to construct update specifications.

For more information on using the Updates builder with arrays, see our guide on the Updates builder.

The following example performs these actions:

  • Query for the sample document

  • Append "17" to the qty array in the document that matches the query filter

val filter = Filters.eq("_id", 1)
val update = Updates.push(PaintOrder::qty.name, 17)
val options = FindOneAndUpdateOptions()
    .returnDocument(ReturnDocument.AFTER)
val result = collection.findOneAndUpdate(filter, update, options)
print(result)
PaintOrder(id=1, qty=[8, 12, 18, 17], color=green)

Specifying Array Elements

You can specify which array elements to update using a positional operator. Positional operators can specify the first, all, or certain array elements to update.

To specify elements in an array with positional operators, use dot notation. Dot notation is a property access syntax for navigating BSON objects.

For additional information, see the Server Manual Entry on dot notation.

The First Matching Array Element

To update the first array element that matches your query filter, use the positional $ operator. The array field must appear as part of your query filter to use the positional $ operator.

Example

The following example performs these actions:

  • Query for a document with a qty field containing the value "18"

  • Decrement the first array value in the document that matches the query filter by "3"

val filter = Filters.eq(PaintOrder::qty.name, 18)
val update = Updates.inc("${PaintOrder::qty.name}.$", -3)
val options = FindOneAndUpdateOptions()
    .returnDocument(ReturnDocument.AFTER)
val result = collection.findOneAndUpdate(filter, update, options)
print(result)
PaintOrder(id=1, qty=[8, 12, 15], color=green)

For more information about the methods and operators mentioned in this section, see the following resources:

Matching All Array Elements

To update all elements in an array, use the all positional $[] operator.

Example

The following example performs these actions:

  • Query for the sample document

  • Multiply array elements matching the query filter by "2"

val filter = Filters.eq("_id", 1)
val update = Updates.mul("${PaintOrder::qty.name}.$[]", 2)
val options = FindOneAndUpdateOptions()
    .returnDocument(ReturnDocument.AFTER)
val result = collection.findOneAndUpdate(filter, update, options)
println(result)
PaintOrder(id=1, qty=[16, 24, 36], color=green)

For more information about the methods and operators mentioned in this section, see the following resources:

Matching Multiple Array Elements

To update array elements that match a filter, use the filtered positional $[<identifier>] operator. You must include an array filter in your update operation to specify which array elements to update.

The <identifier> is the name you give your array filter. This value must begin with a lowercase letter and contain only alphanumeric characters.

Example

The following example performs these actions:

  • Query for the sample document

  • Set an array filter to search for values less than "15"

  • Increment array elements matching the query filter by "5"

val filter = Filters.eq("_id", 1)
val smallerFilter = Filters.lt("smaller", 15)
val options = FindOneAndUpdateOptions()
    .returnDocument(ReturnDocument.AFTER)
    .arrayFilters(listOf(smallerFilter))
val update = Updates.inc("${PaintOrder::qty.name}.$[smaller]", 5)
val result = collection.findOneAndUpdate(filter, update, options)
println(result)
PaintOrder(id=1, qty=[13, 17, 18], color=green)

For more information about the methods and operators mentioned in this section, see the following resources:

Next

MongoDB Kotlin Driver