- Reference >
- Operators >
- Update Operators >
- Array Update Operators >
- $push
Definition¶
$push
¶The $push
operator appends a specified value to an array.
The
$push
operator has the form:
{ $push: { : , ... } }
To specify a in an embedded document or in an array, use dot notation.
Behavior¶
If the field is absent in the document to update, $push
adds the 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 a single element. To add each element of the value separately, use the $each
modifier with
$push
. For an example, see Append a Value to Arrays in Multiple Documents. For a list of modifiers available for $push
,
see Modifiers.
Modifiers¶
You can use the $push
operator with the
following modifiers:
$each
| Appends multiple values to the array field. |
$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 new elements. 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: { : { : , ... }, ... } }
The processing of the push
operation with modifiers occur in the following order, regardless of the order in which the modifiers appear:
- 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 a Value to Arrays in Multiple Documents¶
Add the following documents to the students
collection:
db.students.insertMany[ [ { _id: 2, scores: [ 45, 78, 38, 80, 89 ] } , { _id: 3, scores: [ 46, 78, 38, 80, 89 ] } , { _id: 4, scores: [ 47, 78, 38, 80, 89 ] } ] ]
The following
$push
operation appends 95
to the scores
array in each document:
db.students.updateMany[ { }, { $push: { scores: 95 } } ]
To confirm that each scores
array includes 95
, run the following operation:
The operation returns the following results:
[ { _id: 1, scores: [ 44, 78, 38, 80, 89, 95 ] }, { _id: 2, scores: [ 45, 78, 38, 80, 89, 95 ] }, { _id: 3, scores: [ 46, 78, 38, 80, 89, 95 ] }, { _id: 4, scores: [ 47, 78, 38, 80, 89, 95 ] } ]
Append Multiple Values to an Array¶
Use $push
with the $each
modifier to append multiple values to the
array field.
The following example appends each element of [ 90, 92, 85 ]
to the scores
array for the document where the name
field equals 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 the modifiedquizzes
array by thescore
field in descending order, and - the
$slice
modifier to keep only the first three sorted elements of thequizzes
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 } ] }