Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

$position

On this page

  • Definition
  • Behavior
  • Examples
$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.

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.

Create the students collection:

db.students.insertOne( { "_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.updateOne(
{ _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 a document to the students collection:

db.students.insertOne( { "_id" : 2, "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.updateOne(
{ _id: 2 },
{
$push: {
scores: {
$each: [ 20, 30 ],
$position: 2
}
}
}
)

The operation results in the following updated document:

{ "_id" : 2, "scores" : [ 50, 60, 20, 30, 70, 100 ] }

$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.

Add the following document to the students collection:

db.students.insertOne(
{ "_id" : 3, "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.updateOne(
{ _id: 3 },
{
$push: {
scores: {
$each: [ 90, 80 ],
$position: -2
}
}
}
)

The operation results in the following updated document:

{ "_id" : 3, "scores" : [ 50, 60, 20, 30, 90, 80, 70, 100 ] }
←  $each$slice →