$push

$push

Definition

$push
The $push operator appends a specified value to an array.

The $push operator has the form:

{ $push: { <field1>: <value1>, ... } }

To specify a <field> in an embedded document or in an array, usedot notation.

Behavior

If the field is absent in the document to update, $push addsthe array field with the value as its element.

If the field is not an array, the operation will fail.

If the value is an array, $push appends the whole array as asingle element. To add each element of the value separately, use the$each modifier with $push. For an example, seeAppend Multiple Values to an Array. For a list of modifiers available for$push, see Modifiers.

Modifiers

You can use the $push operator with the following modifiers:

Modifier	Description
`$each`	Appends multiple values to the array field.When used in conjunction with the other modifiers, the`$each` modifier no longer needs to be first.
`$slice`	Limits the number of array elements. Requires the use of the`$each` modifier.
`$sort`	Orders elements of the array. Requires the use of the`$each` modifier.
`$position`	Specifies the location in the array at which to insert the newelements. Requires the use of the `$each` modifier.Without the `$position` modifier, the `$push`appends the elements to the end of the array.

When used with modifiers, the $push operator has the form:

{ $push: { <field1>: { <modifier1>: <value1>, ... }, ... } }

The processing of the push operation with modifiers occurin the following order, regardless of the order in which the modifiersappear:

Update array to add elements in the correct position.
Apply sort, if specified.
Slice the array, if specified.
Store the array.

Examples

Append a Value to an Array

The following example appends 89 to the scores array:

db.students.update(
   { _id: 1 },
   { $push: { scores: 89 } }
)

Append Multiple Values to an Array

Use $push with the $each modifier to appendmultiple values to the array field.

The following example appends each element of [ 90, 92, 85 ] tothe scores array for the document where the name fieldequals joe:

db.students.update(
   { name: "joe" },
   { $push: { scores: { $each: [ 90, 92, 85 ] } } }
)

Use $push Operator with Multiple Modifiers

A collection students has the following document:

{
   "_id" : 5,
   "quizzes" : [
      { "wk": 1, "score" : 10 },
      { "wk": 2, "score" : 8 },
      { "wk": 3, "score" : 5 },
      { "wk": 4, "score" : 6 }
   ]
}

The following $push operation uses:

the $each modifier to add multiple documents to thequizzes array,
the $sort modifier to sort all the elements of themodified quizzes array by the score field in descendingorder, and
the $slice modifier to keep only the first threesorted elements of the quizzes array.

db.students.update(
   { _id: 5 },
   {
     $push: {
       quizzes: {
          $each: [ { wk: 5, score: 8 }, { wk: 6, score: 7 }, { wk: 7, score: 6 } ],
          $sort: { score: -1 },
          $slice: 3
       }
     }
   }
)

The result of the operation is keep only the three highest scoring quizzes:

{
  "_id" : 5,
  "quizzes" : [
     { "wk" : 1, "score" : 10 },
     { "wk" : 2, "score" : 8 },
     { "wk" : 5, "score" : 8 }
  ]
}