$position
On this page
Definition
$position
The
$position
modifier specifies the location in the array at which the$push
operator inserts elements. Without the$position
modifier, the$push
operator inserts elements to the end of the array. See $push modifiers for more information.To use the
$position
modifier, it must appear with the$each
modifier.{ $push: { <field>: { $each: [ <value1>, <value2>, ... ], $position: <num> } } } <num>
indicates the position in the array, based on a zero-based array index (position):A non-negative number corresponds to the position in the array, starting from the beginning of the array. If the value of
<num>
is greater or equal to the length of the array, the$position
modifier has no effect and$push
adds elements to the end of the array.A negative number corresponds to the position in the array, counting from (but not including) the last element of the array. For example,
-1
indicates the position just before the last element in the array. If you specify multiple elements in the$each
array, the last added element is in the specified position from the end. If the absolute value of<num>
is greater than or equal to the length of the array, the$push
adds elements to the beginning of the array.
Behavior
In MongoDB 4.4 and earlier, update operators process document fields in lexicographic order. See Update Operators Behavior for details.
Examples
Add Elements at the Start of the Array
Consider a collection students
that contains the following document:
{ "_id" : 1, "scores" : [ 100 ] }
The following operation updates the scores
field to add the
elements 50
, 60
and 70
to the beginning of the array:
db.students.update( { _id: 1 }, { $push: { scores: { $each: [ 50, 60, 70 ], $position: 0 } } } )
The operation results in the following updated document:
{ "_id" : 1, "scores" : [ 50, 60, 70, 100 ] }
Add Elements to the Middle of the Array
Consider a collection students
that contains the following document:
{ "_id" : 1, "scores" : [ 50, 60, 70, 100 ] }
The following operation updates the scores
field to add the
elements 20
and 30
at the array index (position) of 2
:
db.students.update( { _id: 1 }, { $push: { scores: { $each: [ 20, 30 ], $position: 2 } } } )
The operation results in the following updated document:
{ "_id" : 1, "scores" : [ 50, 60, 20, 30, 70, 100 ] }
Use a Negative Array Index (Position) to Add Elements to the Array
Changed in version 3.6: $position
can accept a negative array index (position)
value to indicate the position starting from the end, counting from
(but not including) the last element of the array. For example,
-1
indicates the position just before the last element in the
array.
Consider a collection students
that contains the following document:
{ "_id" : 1, "scores" : [ 50, 60, 20, 30, 70, 100 ] }
The following operation specifies -2
for the $position
to
add 90
at the position two places before the last element, and then
80
at the position two places before the last element.
Important
With a negative array index (position), if you specify multiple
elements in the $each
array, the last added element is in
the specified position from the end.
db.students.update( { _id: 1 }, { $push: { scores: { $each: [ 90, 80 ], $position: -2 } } } )
The operation results in the following updated document:
{ "_id" : 1, "scores" : [ 50, 60, 20, 30, 90, 80, 70, 100 ] }