Update Arrays in a Document
On this page
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