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 Java 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] }

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 about 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

Bson filter = Filters.eq("_id", 1);
Bson update = Updates.push("qty", 17);
// Defines options that configure the operation to return a document in its post-operation state
FindOneAndUpdateOptions options = new FindOneAndUpdateOptions()
                                    .returnDocument(ReturnDocument.AFTER);
 // Updates the first document that matches the filter and prints the updated document as JSON                                    
Document result = collection.findOneAndUpdate(filter, update, options);
System.out.println(result.toJson());

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

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

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"

Bson filter = Filters.eq("qty", 18);
Bson update = Updates.inc("qty.$", -3);
// Defines options that configure the operation to return a document in its post-operation state
FindOneAndUpdateOptions options = new FindOneAndUpdateOptions()
                                    .returnDocument(ReturnDocument.AFTER);
// Updates the first document that matches the filter and prints the updated document as JSON 
Document result = collection.findOneAndUpdate(filter, update, options);
System.out.println(result.toJson());

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

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

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

Positional $ Operator Server Manual Entry
inc() API Documentation

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"

Bson filter = Filters.eq("_id", 1);
Bson update = Updates.mul("qty.$[]", 2);
// Defines options that configure the operation to return a document in its post-operation state
FindOneAndUpdateOptions options = new FindOneAndUpdateOptions()
                                    .returnDocument(ReturnDocument.AFTER);
// Updates the first document that matches the filter and prints the updated document as JSON                                    
Document result = collection.findOneAndUpdate(filter, update, options);
System.out.println(result.toJson());

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

{ "_id": 1, "color": "green", "qty": [16, 24, 36] }

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

All Positional $[] Operator Server Manual Entry
mul() API Documentation

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"

Bson filter = Filters.eq("_id", 1);
Bson smallerFilter = Filters.lt("smaller", 15);
// Defines options that configure the document's return state and apply the array value filter
FindOneAndUpdateOptions options = new FindOneAndUpdateOptions()
                                    .returnDocument(ReturnDocument.AFTER)
                                    .arrayFilters(Arrays.asList(smallerFilter));
// Creates an update document to increase the matched array values by "5"
Bson update = Updates.inc("qty.$[smaller]", 5);
 // Updates the first document that matches the filter and prints the updated document as JSON
Document result = collection.findOneAndUpdate(filter, update, options);
System.out.println(result.toJson());

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

{ "_id": 1, "color": "green", "qty": [13, 17, 18] }

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

Filtered Positional $[<identifier>] Operator Server Manual Entry
inc() API Documentation

Back

Modify

Upsert