diff --git a/source/reference/operator/each.txt b/source/reference/operator/each.txt index 4059ee395e4..eb49524be40 100644 --- a/source/reference/operator/each.txt +++ b/source/reference/operator/each.txt @@ -2,21 +2,44 @@ $each ===== +.. default-domain:: mongodb + .. note:: - The :mongodb:operator:`$each` operator is only used with the - :mongodb:operator:`$addToSet` see the documentation of - :doc:`/reference/operator/addToSet` for more information. - -.. default-domain:: mongodb + The :operator:`$each` modifier is only used with the + :operator:`$addToSet` operator and the :operator:`$push` operator. + See the documentation of :operator:`$addToSet` and :operator:`$push` + for more information. .. operator:: $each - The :operator:`$each` operator is available within the - :operator:`$addToSet`, which allows you to add multiple values - to the array if they do not exist in the ``field`` array in a - single operation. Consider the following prototype: + The :operator:`$each` modifier is available for use with the + :operator:`$addToSet` operator and the :operator:`$addToSet` + operator. + + - Use the :operator:`$each` modifier with the :operator:`$addToSet` + operator to add multiple values to an array ```` if the + values do not exist in the ````. + + .. code-block:: javascript + + db.collection.update( , + { + $addToSet: { : { $each: [ , ... ] } } + } + ) + + - Use the :operator:`$each` modifier with the :operator:`$push` + operator to append multiple values to an array ````. + + .. code-block:: javascript - .. code-block:: javascript + db.collection.update( , + { + $push: { : { $each: [ , ... ] } } + } + ) - db.collection.update( { field: value }, { $addToSet: { field: { $each : [ value1, value2, value3 ] } } } ); + .. versionchanged:: 2.4 + Before MongoDB 2.4, :operator:`$each` modifier was not available for + use with the :operator:`$push` operator. diff --git a/source/reference/operator/push.txt b/source/reference/operator/push.txt index ceb4e875d5e..93f69b551c1 100644 --- a/source/reference/operator/push.txt +++ b/source/reference/operator/push.txt @@ -6,26 +6,87 @@ $push .. operator:: $push - The :operator:`$push` operator appends a specified value to an array. For - example: + The :operator:`$push` operator appends a specified value to an array. .. code-block:: javascript - db.collection.update( { field: value }, { $push: { field: value1 } } ); + db.collection.update( , + { $push: { : } } + ) - Here, :operator:`$push` appends ``value1`` to the array identified by - ``value`` in ``field``. Be aware of the following behaviors: + The following example appends ``89`` to the ``scores`` array for the + first document where the ``name`` field equals ``joe``: - - If the field specified in the :operator:`$push` statement - (e.g. ``{ $push: { field: value1 } }``) does not exist in the - matched document, the operation adds a new array with the - specified field and value (e.g. ``value1``) to the matched - document. + .. code-block:: javascript + + db.students.update( + { name: "joe" }, + { $push: { scores: 89 } } + ) + + .. note:: + + - If the field is absent in the document to update, the + operation 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, :operator:`$push` appends the whole + array as a *single* element. To add each element of the value + separately, use :operator:`$push` with the :operator:`$each` + modifier. + + The following example appends each element of ``[ 90, 92, 85 ]`` to + the ``scores`` array for the document where the ``name`` field + equals ``joe``: + + .. code-block:: javascript + + db.students.update( + { name: "joe" }, + { $push: { scores: { $each: [ 90, 92, 85 ] } } } + ) + + .. versionchanged:: 2.4 + Before MongoDB 2.4, :operator:`$each` modifier was + unavailable for use with :operator:`$push`. + Instead, you would use the :operator:`$pushAll` operator to + add each element separately. - - The operation will fail if the field specified in the - :operator:`$push` statement is *not* an array. :operator:`$push` - does not fail when pushing a value to a non-existent field. + .. versionchanged:: 2.4 + You can use the :operator:`$push` operator with the following + modifiers: + + - :operator:`$each` to append multiple values to the array field, + + - :operator:`$slice` to limit the number of array elements and + which must be used with :operator:`$each`, and + + - :operator:`$sort` to order the array elements, and which must be + used with :operator:`$slice`, and can **only** sort arrays that + contain documents. + + The following example uses: + + - the :operator:`$each` modifier to append documents to the + ``quizzes`` array, + + - the :operator:`$sort` modifier to sort all the elements of the + modified ``quizzes`` array by the ascending ``score`` field, and + + - the :operator:`$slice` modifier to keep only the **last** five + sorted elements of the ``quizzes`` array. + + .. code-block:: javascript - - If ``value1`` is an array itself, :operator:`$push` appends the whole array as an - element in the identified array. To add multiple items to an - array, use :operator:`$pushAll`. + db.students.update( { name: "joe" }, + { $push: { quizzes: { $each: [ { id: 3, score: 8 }, + { id: 4, score: 7 }, + { id: 5, score: 6 } ], + $sort: { score: 1 }, + $slice: -5 + } + } + } + ) diff --git a/source/reference/operator/pushAll.txt b/source/reference/operator/pushAll.txt index 584ba4fb88f..c44a1568415 100644 --- a/source/reference/operator/pushAll.txt +++ b/source/reference/operator/pushAll.txt @@ -6,6 +6,9 @@ $pushAll .. operator:: $pushAll + .. deprecated:: 2.4 + Use the :operator:`$push` operator with :operator:`$each` instead. + The :operator:`$pushAll` operator is similar to the :operator:`$push` but adds the ability to append several values to an array at once. diff --git a/source/reference/operator/slice.txt b/source/reference/operator/slice.txt new file mode 100644 index 00000000000..4ace29636a8 --- /dev/null +++ b/source/reference/operator/slice.txt @@ -0,0 +1,52 @@ +====== +$slice +====== + +.. default-domain:: mongodb + +.. operator:: $slice + + .. versionadded:: 2.4 + + The :operator:`$slice` modifier limits the number of array + elements during a :operator:`$push` operation. To project, or return, + a specified number of array elements from a read operation, see the + :projection:`$slice` projection operator instead. + + To use the :operator:`$slice` modifier, it must appear with the + :operator:`$each` modifier, *and* the :operator:`$each` modifier must + be the first modifier for the :operator:`$push` operation. + + .. code-block:: javascript + + db.collection.update( , + { $push: { + : { + $each: [ , , ... ], + $slice: + } + } + } + ) + + The ```` is either a **negative** number or **zero** + [#future-num-values]_: + + - If ```` is **negative**, the array ```` contains only + the last ```` elements. + + - If ```` is **zero**, the array ```` is an empty array. + + .. code-block:: javascript + + db.students.update( { _id: 2 }, + { $push: { grades: { + $each: [ 80, 78, 86 ], + $slice: -5 + } + } + } + ) + + .. [#future-num-values] In future releases, ```` will accept + positive numbers as well as negative numbers and zero. diff --git a/source/reference/operator/sort.txt b/source/reference/operator/sort.txt new file mode 100644 index 00000000000..fe3c6281beb --- /dev/null +++ b/source/reference/operator/sort.txt @@ -0,0 +1,91 @@ +===== +$sort +===== + +.. default-domain:: mongodb + +.. operator:: $sort + + .. versionadded:: 2.4 + + The :operator:`$sort` modifier orders the elements of an array + during a :operator:`$push` operation. The elements of the array + **must** be documents [#future-arrary-elements]_. + + To apply the :operator:`$sort` modifier, it must appear **with** the + :operator:`$each` and :operator:`$slice` modifiers, *and* the + :operator:`$each` modifier must be the first modifier for the + :operator:`$push` operation. + + .. code-block:: javascript + + db.collection.update( , + { $push: { + : { + $each: [ , + , + ... + ], + $slice: , + $sort: , + } + } + } + ) + + .. important:: + + The ```` only accesses the fields from the + elements in the array and does **not** refer to the array + ````. + + Consider the following example where the collection ``students`` + contain the following document: + + .. code-block:: javascript + + { "_id": 3, + "name": "joe", + "quizzes": [ + { "id" : 1, "score" : 6 }, + { "id" : 2, "score" : 9 } + ] + } + + The following update appends additional documents to the ``quizzes`` + array, sorts all the elements of the array by ascending ``score`` + field, and slices the array to keep the last five elements: + + .. code-block:: javascript + + db.students.update( { name: "joe" }, + { $push: { quizzes: { $each: [ { id: 3, score: 8 }, + { id: 4, score: 7 }, + { id: 5, score: 6 } ], + $sort: { score: 1 }, + $slice: -5 + } + } + } + ) + + After the update, the array elements are in order of ascending + ``score`` field.: + + .. code-block:: javascript + + { + "_id" : 3, + "name" : "joe", + "quizzes" : [ + { "id" : 1, "score" : 6 }, + { "id" : 5, "score" : 6 }, + { "id" : 4, "score" : 7 }, + { "id" : 3, "score" : 8 }, + { "id" : 2, "score" : 9 } + ] + } + + .. [#future-arrary-elements] In future releases, the + :operator:`$sort` modifier will be able to sort elements of + other types, not just documents. diff --git a/source/reference/operators.txt b/source/reference/operators.txt index a41c99d1c8f..915c1eaead7 100644 --- a/source/reference/operators.txt +++ b/source/reference/operators.txt @@ -156,6 +156,12 @@ Array - :operator:`$pushAll` - :operator:`$push` + - :operator:`$each` modifier + + - :operator:`$slice` modifier + + - :operator:`$sort` modifier + Bitwise ~~~~~~~ diff --git a/source/reference/projection/slice.txt b/source/reference/projection/slice.txt index e7d3f561c7c..e96f43763fc 100644 --- a/source/reference/projection/slice.txt +++ b/source/reference/projection/slice.txt @@ -6,8 +6,12 @@ $slice (projection) .. projection:: $slice - The :projection:`$slice` operator controls the number of items of an array - that a query returns. Consider the following prototype query: + The :projection:`$slice` operator controls the number of items of an + array that a query returns. For information on limiting the size of + an array during an update with :operator:`$push`, see the + :operator:`$slice` modifier instead. + + Consider the following prototype query: .. code-block:: javascript diff --git a/source/release-notes/2.4.txt b/source/release-notes/2.4.txt index 75b656cbef8..10bc3452d9b 100644 --- a/source/release-notes/2.4.txt +++ b/source/release-notes/2.4.txt @@ -1371,6 +1371,21 @@ performs an insert, use the :operator:`$setOnInsert` operator with the update and for :method:`updates ` when the ``upsert`` option is ``false``. +``$each``, ``$slice``, and ``$sort`` Available for Use with ``$push`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can now use the :operator:`$push` operator with the following +modifiers: + +- :operator:`$each` to append multiple values to the array field, + +- :operator:`$slice` to restrict the number of array elements and which + must be used with :operator:`$each`, and + +- :operator:`$sort` to order the elements of the array, which + must be used with :operator:`$slice` and can **only** sort + arrays that contain documents. + ``--setParameter`` Option Available on the ``mongos`` and ``mongod`` Command Line ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~