max.txt

====
$max
====

.. default-domain:: mongodb

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

Definition
----------

.. update:: $max

   The :update:`$max` operator updates the value of the field to a
   specified value *if* the specified value is **greater than** the
   current value of the field. The :update:`$max` operator can compare
   values of different types, using the :ref:`BSON comparison order
   <faq-dev-compare-order-for-BSON-types>`.

   The :update:`$max` operator expression has the form:

   .. code-block:: javascript

      { $max: { <field1>: <value1>, ... } }

   .. include:: /includes/use-dot-notation.rst

Behavior
--------

.. include:: /includes/fact-update-operator-lexicographic-order.rst

If the field does not exists, the :update:`$max` operator sets the
field to the specified value.

Examples
--------

Use ``$max`` to Compare Numbers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Consider the following document in the collection ``scores``:

.. code-block:: javascript

   { _id: 1, highScore: 800, lowScore: 200 }

The ``highScore`` for the document currently has the value
``800``. The following operation uses :operator:`$max` to compare
the ``800`` and the specified value ``950`` and updates the value
of ``highScore`` to ``950`` since ``950`` is greater than ``800``:

.. code-block:: javascript

   db.scores.update( { _id: 1 }, { $max: { highScore: 950 } } )

The ``scores`` collection now contains the following modified document:

.. code-block:: javascript

   { _id: 1, highScore: 950, lowScore: 200 }

The next operation has no effect since the current value of the
field ``highScore``, i.e. ``950``, is greater than ``870``:

.. code-block:: javascript

   db.scores.update( { _id: 1 }, { $max: { highScore: 870 } } )

The document remains unchanged in the ``scores`` collection:

.. code-block:: javascript

   { _id: 1, highScore: 950, lowScore: 200 }

Use ``$max`` to Compare Dates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Consider the following document in the collection ``tags``:

.. code-block:: javascript

   {
     _id: 1,
     desc: "crafts",
     dateEntered: ISODate("2013-10-01T05:00:00Z"),
     dateExpired: ISODate("2013-10-01T16:38:16.163Z")
   }

The following operation compares the current value of the
``dateExpired`` field, i.e.
``ISODate("2013-10-01T16:38:16.163Z")``, with the specified date
``new Date("2013-09-30")`` to determine whether to update the
field:

.. code-block:: javascript

   db.tags.update(
      { _id: 1 },
      { $max: { dateExpired: new Date("2013-09-30") } }
   )

The operation does *not* update the ``dateExpired`` field:

.. code-block:: javascript
   :emphasize-lines: 5

   {
      _id: 1,
      desc: "decorative arts",
      dateEntered: ISODate("2013-10-01T05:00:00Z"),
      dateExpired: ISODate("2013-10-01T16:38:16.163Z")
   }

.. seealso:: :method:`db.collection.update()`,
   :method:`db.collection.findAndModify()`