$position

Definition

  • $position
  • The $position modifier specifies the location in thearray at which the $push operator inserts elements.Without the $position modifier, the $pushoperator inserts elements to the end of the array. See $pushmodifiers for more information.

To use the $position modifier, it must appear with the$each modifier.

  1. {
  2.   $push: {
  3.     <field>: {
  4.        $each: [ <value1>, <value2>, ... ],
  5.        $position: <num>
  6.     }
  7.   }
  8. }

Changed in version 3.6: $position can accept a negative array index value toindicate the position starting from the end, counting from (butnot including) the last element of the array.

<num> indicates the position in the array, based on a zero-based index:

  • 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 $pushadds 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 lastelement in the array. If you specify multiple elements in the$each array, the last added element is in the specifiedposition from the end. If the absolute value of <num> isgreater than or equal to the length of the array, the $pushadds elements to the beginning of the array.

Examples

Add Elements at the Start of the Array

Consider a collection students that contains the following document:

  1. { "_id" : 1, "scores" : [ 100 ] }

The following operation updates the scores field to add theelements 50, 60 and 70 to the beginning of the array:

  1. db.students.update(
  2.    { _id: 1 },
  3.    {
  4.      $push: {
  5.         scores: {
  6.            $each: [ 50, 60, 70 ],
  7.            $position: 0
  8.         }
  9.      }
  10.    }
  11. )

The operation results in the following updated document:

  1. { "_id" : 1, "scores" : [  50,  60,  70,  100 ] }

Add Elements to the Middle of the Array

Consider a collection students that contains the following document:

  1. { "_id" : 1, "scores" : [  50,  60,  70,  100 ] }

The following operation updates the scores field to add theelements 20 and 30 at the array index of 2:

  1. db.students.update(
  2.    { _id: 1 },
  3.    {
  4.      $push: {
  5.         scores: {
  6.            $each: [ 20, 30 ],
  7.            $position: 2
  8.         }
  9.      }
  10.    }
  11. )

The operation results in the following updated document:

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

Use a Negative Index to Add Elements to the Array

Changed in version 3.6: $position can accept a negative array index value toindicate the position starting from the end, counting from (but notincluding) the last element of the array. For example, -1indicates the position just before the last element in the array.

Consider a collection students that contains the following document:

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

The following operation specifies -2 for the $position toadd 90 at the position two places before the last element, and then80 at the position two places before the last element.

Important

With a negative index position, if you specify multiple elements inthe $each array, the last added element is in thespecified position from the end.

  1. db.students.update(
  2.    { _id: 1 },
  3.    {
  4.      $push: {
  5.         scores: {
  6.            $each: [ 90, 80 ],
  7.            $position: -2
  8.         }
  9.      }
  10.    }
  11. )

The operation results in the following updated document:

  1. { "_id" : 1, "scores" : [ 50, 60, 20, 30, 90, 80, 70, 100 ] }