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
qtyarray 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
qtyfield 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