sort.txt

=====
$sort
=====

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. update:: $sort

   The :update:`$sort` modifier orders the elements of an array
   during a :update:`$push` operation.

   To use the :update:`$sort` modifier, it **must** appear with the
   :update:`$each` modifier. You can pass an empty array ``[]`` to the
   :update:`$each` modifier such that only the :update:`$sort` modifier
   has an effect.

   .. code-block:: javascript

      {
        $push: {
           <field>: {
             $each: [ <value1>, <value2>, ... ],
             $sort: <sort specification>
           }
        }
      }


   For ``<sort specification>``:

   - To sort array elements that are not documents, or if the array
     elements are documents, to sort by the whole documents, specify
     ``1`` for ascending or ``-1`` for descending.

   - If the array elements are documents, to sort by a field in the
     documents, specify a sort document with the field and the
     direction, i.e. ``{ field: 1 }`` or ``{ field: -1 }``. Do **not**
     reference the containing array field in the sort specification
     (e.g. ``{ "arrayField.field": 1 }`` is incorrect).

Behavior
--------

The :update:`$sort` modifier can sort array elements that are not
documents. In previous versions, the :update:`$sort` modifier required
the array elements be documents.

If the array elements are documents, the modifier can sort by either
the whole document or by a specific field in the documents. In previous
versions, the :update:`$sort` modifier can only sort by a specific
field in the documents.

Trying to use the :update:`$sort` modifier without the :update:`$each`
modifier results in an error. The :update:`$sort` no longer requires
the :update:`$slice` modifier. For a list of modifiers available for
:update:`$push`, see :ref:`push-modifiers`.

Examples
--------

.. _example-sort-by-field-in-documents:

Sort Array of Documents by a Field in the Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A collection ``students`` contains the following document:

.. code-block:: javascript

   {
     "_id": 1,
     "quizzes": [
       { "id" : 1, "score" : 6 },
       { "id" : 2, "score" : 9 }
     ]
   }

The following update appends additional documents to the ``quizzes``
array and then sorts all the elements of the array by the ascending
``score`` field:

.. code-block:: javascript

   db.students.update(
      { _id: 1 },
      {
        $push: {
          quizzes: {
            $each: [ { id: 3, score: 8 }, { id: 4, score: 7 }, { id: 5, score: 6 } ],
            $sort: { score: 1 }
          }
        }
      }
   )

.. important:: The sort document refers directly to the field in the
   documents and does not reference the containing array field
   ``quizzes``; i.e. ``{ score: 1 }`` and **not** ``{ "quizzes.score": 1}``

After the update, the array elements are in order of ascending
``score`` field.:

.. code-block:: javascript

   {
     "_id" : 1,
     "quizzes" : [
        { "id" : 1, "score" : 6 },
        { "id" : 5, "score" : 6 },
        { "id" : 4, "score" : 7 },
        { "id" : 3, "score" : 8 },
        { "id" : 2, "score" : 9 }
     ]
   }

Sort Array Elements That Are Not Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A collection ``students`` contains the following document:

.. code-block:: javascript

   { "_id" : 2, "tests" : [  89,  70,  89,  50 ] }

The following operation adds two more elements to the ``scores`` array
and sorts the elements:

.. code-block:: javascript

   db.students.update(
      { _id: 2 },
      { $push: { tests: { $each: [ 40, 60 ], $sort: 1 } } }
   )

The updated document has the elements of the ``scores`` array in
ascending order:

.. code-block:: javascript

   { "_id" : 2, "tests" : [  40,  50,  60,  70,  89,  89 ] }

Update Array Using Sort Only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A collection ``students`` contains the following document:

.. code-block:: javascript

   { "_id" : 3, "tests" : [  89,  70,  100,  20 ] }

To update the ``tests`` field to sort its elements in descending
order, specify the ``{ $sort: -1 }`` and specify an empty array ``[]``
for the :update:`$each` modifier, as in the following:

.. code-block:: javascript

   db.students.update(
      { _id: 3 },
      { $push: { tests: { $each: [ ], $sort: -1 } } }
   )

The result of the operation is to update the ``scores`` field to sort
its elements in descending order:

.. code-block:: javascript

   { "_id" : 3, "tests" : [ 100,  89,  70,  20 ] }

Use ``$sort`` with Other ``$push`` Modifiers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/example-push-with-multiple-modifiers.rst

The order of the modifiers is immaterial to the order in which the
modifiers are processed. See :ref:`push-modifiers` for details.