Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
Operators
/
Update Operators
/
Array Update Operators

$[<identifier>]

On this page

  • Definition
  • Behavior
  • Restrictions
  • upsert
  • Nested Arrays
  • Examples
  • Update All Array Elements That Match arrayFilters
  • Update All Documents That Match arrayFilters in an Array
  • Update All Array Elements that Match Multiple Conditions
  • Update Array Elements Using a Negation Operator
  • Update Nested Arrays in Conjunction with $[]

Definition

$[<identifier>]

The filtered positional operator $[<identifier>] identifies the array elements that match the arrayFilters conditions for an update operation, e.g. db.collection.updateMany() and db.collection.findAndModify().

Used in conjunction with the arrayFilters option, the $[<identifier>] operator has the following form:

{ <update operator>: { "<array>.$[<identifier>]" : value } },
{ arrayFilters: [ { <identifier>: <condition> } ] }

Use in conjunction with the arrayFilters option to update all elements that match the arrayFilters conditions in the document or documents that match the query conditions. For example:

db.collection.updateMany(
   { <query conditions> },
   { <update operator>: { "<array>.$[<identifier>]" : value } },
   { arrayFilters: [ { <identifier>: <condition> } ] }
)

Note

The <identifier> must begin with a lowercase letter and contain only alphanumeric characters.

For an example, see Update All Array Elements That Match arrayFilters.

Behavior

Starting in MongoDB 5.0, update operators process document fields with string-based names in lexicographic order. Fields with numeric names are processed in numeric order. See Update Operators Behavior for details.

Restrictions

The arrayFilters option cannot include the following query operators:

  • $expr

  • $text

  • $where

upsert

If an upsert operation results in an insert, the query must include an exact equality match on the array field in order to use $[<identifier>] in the update statement.

For example, the following upsert operation, which uses $[<identifier>] in the update document, specifies an exact equality match condition on the array field:

db.collection.updateOne(
   { myArray: [ 0, 1 ] },
   { $set: { "myArray.$[element]": 2 } },
   { arrayFilters: [ { element: 0 } ], upsert: true }
)

If no such document exists, the operation would result in an insert of a document that resembles the following:

{ "_id" : ObjectId(...), "myArray" : [ 2, 1 ] }

If the upsert operation did not include an exact equality match and no matching documents were found to update, the upsert operation would error. For example, the following operations would error if no matching documents were found to update:

db.array.updateOne(
   { },
   { $set: { "myArray.$[element]": 10 } },
   { arrayFilters: [ { element: 9 } ], upsert: true }
)

The operation would return an error that resembles the following:

MongoServerError: The path 'myArray' must exist in the document in order to apply array updates.

Nested Arrays

The filtered positional operator $[<identifier>] can be used for queries which traverse more than one array and nested arrays.

For an example, see Update Nested Arrays in Conjunction with $[].

Examples

Update All Array Elements That Match arrayFilters

Create the students collection:

db.students.insertMany( [
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
] )

To update all elements that are greater than or equal to 100 in the grades array, use the filtered positional operator $[<identifier>] with the arrayFilters:

db.students.updateMany(
   { },
   { $set: { "grades.$[element]" : 100 } },
   { arrayFilters: [ { "element": { $gte: 100 } } ] }
)

The positional $[<identifier>] operator acts as a placeholder for all elements in the array field that match the conditions specified in arrayFilters.

After the operation, the students collection contains the following documents:

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }
{ "_id" : 3, "grades" : [ 95, 100, 100 ] }

Update All Documents That Match arrayFilters in an Array

The $[<identifier>] operator facilitates updates to arrays that contain embedded documents. To access the fields in the embedded documents, use the dot notation with the $[<identifier>].

db.collection.updateMany(
   { <query selector> },
   { <update operator>: { "array.$[<identifier>].field" : value } },
   { arrayFilters: [ { <identifier>: <condition> } } ] }
)

Create the students2 collection:

db.students2.insertMany( [
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
] )

To modify the value of the mean field for all elements in the grades array where the grade is greater than or equal to 85, use the positional $[<identifier>] operator and arrayFilters:

db.students2.updateMany(
   { },
   { $set: { "grades.$[elem].mean" : 100 } },
   { arrayFilters: [ { "elem.grade": { $gte: 85 } } ] }
)

After the operation, the collection has the following documents:

{
   "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 6 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 6 }
   ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 100, "std" : 6 },
      { "grade" : 87, "mean" : 100, "std" : 3 },
      { "grade" : 85, "mean" : 100, "std" : 4 }
   ]
}

Update All Array Elements that Match Multiple Conditions

Create the students3 collection:

db.students3.insertMany( [
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 100, "std" : 4 },
         { "grade" : 85, "mean" : 100, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 100, "std" : 6 },
         { "grade" : 87, "mean" : 100, "std" : 3 },
         { "grade" : 85, "mean" : 100, "std" : 4 }
      ]
   }
] )

To modify the value of the std field for all elements in the grades array where both the grade is greater than or equal to 80 and the std is greater than or equal to 5, use the positional $[<identifier>] operator and arrayFilters:

db.students3.updateMany(
   { },
   { $inc: { "grades.$[elem].std" : -1 } },
   { arrayFilters: [ { "elem.grade": { $gte: 80 }, "elem.std": { $gte: 5 } } ] }
)

After the operation, the collection has the following documents:

{  "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 5 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 5 }
   ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 100, "std" : 5 },
      { "grade" : 87, "mean" : 100, "std" : 3 },
      { "grade" : 85, "mean" : 100, "std" : 4 }
   ]
}

Update Array Elements Using a Negation Operator

Create the alumni collection:

db.alumni.insertMany( [
   {
      "_id": 1,
      "name": "Christine Franklin",
      "degrees": [
         { "level": "Master" },
         { "level": "Bachelor" }
      ],
  },
   {
      "_id": 2,
      "name": "Reyansh Sengupta",
      "degrees": [ { "level": "Bachelor" } ],
   }
] )

To modify all elements in the degrees array that do not have "level": "Bachelor", use the positional $[<identifier>] operation with the $ne query operator:

db.alumni.updateMany(
   { },
   { $set : { "degrees.$[degree].gradcampaign" : 1 } },
   { arrayFilters : [ {"degree.level" : { $ne: "Bachelor" } } ] }
)

After the operation, the collection has the following documents:

 {
  _id: 1,
  name: 'Christine Franklin',
  degrees: [
     { level: 'Master', gradcampaign: 1 },
     { level: 'Bachelor' }
  ]
},
{
  _id: 2,
  name: 'Reyansh Sengupta',
  degrees: [ { level: 'Bachelor' } ]
}

Update Nested Arrays in Conjunction with $[]

The $[<identifier>] filtered positional operator, in conjunction with the $[] all positional operator, can be used to update nested arrays.

Create a collection students4 with the following document:

db.students4.insertOne(
   { "_id" : 1,
      "grades" : [
        { type: "quiz", questions: [ 10, 8, 5 ] },
        { type: "quiz", questions: [ 8, 9, 6 ] },
        { type: "hw", questions: [ 5, 4, 3 ] },
        { type: "exam", questions: [ 25, 10, 23, 0 ] },
      ]
   }
)

The following updates the values that are greater than or equal to 8 in the nested grades.questions array if the associated grades.type field is quiz.

db.students4.updateMany(
   {},
   { $inc: { "grades.$[t].questions.$[score]": 2 } },
   { arrayFilters: [ { "t.type": "quiz" }, { "score": { $gte: 8 } } ] }
)
.. note::
   The spacing is significant in the array identifier. If you write
   the identifier as ``grades.$[ t ].questions.$[ score ]``, the
   operation will fail.

After the operation, the collection has the following document:

{
   "_id" : 1,
   "grades" : [
      { "type" : "quiz", "questions" : [ 12, 10, 5 ] },
      { "type" : "quiz", "questions" : [ 10, 11, 6 ] },
      { "type" : "hw", "questions" : [ 5, 4, 3 ] },
      { "type" : "exam", "questions" : [ 25, 10, 23, 0 ] }
   ]
}

To update all values that are greater than or equal to 8 in the nested grades.questions array, regardless of type:

db.students4.updateMany(
   {},
   { $inc: { "grades.$[].questions.$[score]": 2 } },
   { arrayFilters: [  { "score": { $gte: 8 } } ] }
)

Tip

See also:

Back

$[]