Docs Menu
Docs Home
/ / /
Java Sync Driver
/ / /

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

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

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.

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

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.

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.

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:

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

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:

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.

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:

← Modify Documents