cursor.max.txt

============
cursor.max()
============

.. default-domain:: mongodb

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

Definition
----------

.. method:: cursor.max()


   .. include:: /includes/fact-mongosh-shell-method.rst


   Specifies the *exclusive* upper bound for a specific index in order
   to constrain the results of
   :method:`~db.collection.find()`. :method:`~cursor.max()` provides a
   way to specify an upper bound on compound key indexes.

Parameters
~~~~~~~~~~

The :method:`~cursor.max()` method has the following parameter:


.. list-table::
   :header-rows: 1
   :widths: 20 20 80

   * - Parameter

     - Type

     - Description

   * - ``indexBounds``

     - document

     - The exclusive upper bound for the index keys.
          
          
   


The ``indexBounds`` parameter has the following prototype form:

.. code-block:: javascript

   { field1: <max value>, field2: <max value2> ... fieldN:<max valueN> }

The fields correspond to *all* the keys of a particular index *in
order*. 

.. include:: /includes/cursor-index-use

.. seealso::

   :method:`~cursor.min()`

:method:`~cursor.max()` exists primarily to support the
:binary:`~bin.mongos` (sharding) process.

Compatibility
-------------

This method is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-all.rst

.. include:: /includes/fact-environments-onprem-only.rst

Behavior
--------

Interaction with Index Selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Because :method:`~cursor.max()` requires an index on a field,
and forces the query to use this index, you may prefer the
:query:`$lt` operator for the query if possible. Consider the
following example:

.. code-block:: javascript

   db.products.find( { _id: { $in: [ 6, 7 ] } } ).max( { price: NumberDecimal("1.39") } ).hint( { price: 1 } )

The query will use the index on the ``price`` field, even if
the index on ``_id`` may be better.

Index Bounds
~~~~~~~~~~~~

If you use :method:`~cursor.max()` with :method:`~cursor.min()` to
specify a range:

- the index bounds specified in :method:`~cursor.min()` and
  :method:`~cursor.max()` must both refer to the keys of the same index.

- the bound specified by :method:`~cursor.max()` must be greater than
  the bound specified by :method:`~cursor.min()`.

``max()`` without ``min()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-query-min-max.rst

Example
-------

.. note::

   You must explicitly specify the particular index with the 
   :method:`~cursor.hint()` method to run :method:`~cursor.max()` with the 
   following exception: you do not need to hint if the 
   :method:`~db.collection.find()` query is an equality condition on the 
   ``_id`` field ``{ _id: <value> }``.

For the examples below, create a sample collection named ``products`` that holds the
following documents:

.. code-block:: javascript

   db.products.insertMany([
      { "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : NumberDecimal("1.99") },
      { "_id" : 2, "item" : "apple", "type" : "fuji", "price" : NumberDecimal("1.99") },
      { "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : NumberDecimal("1.29") },
      { "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : NumberDecimal("1.29") },
      { "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : NumberDecimal("1.29") },
      { "_id" : 6, "item" : "apple", "type" : "cortland", "price" : NumberDecimal("1.29") },
      { "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : NumberDecimal("2.99") },
      { "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : NumberDecimal("1.99") },
      { "_id" : 8, "item" : "orange", "type" : "valencia", "price" : NumberDecimal("0.99") },
      { "_id" : 10, "item" : "orange", "type" : "navel", "price" : NumberDecimal("1.39") }
   ])

Create the following indexes for the collection:

.. code-block:: javascript

   db.products.createIndexes( [
      { "item" : 1, "type" : 1 },
      { "item" : 1, "type" : -1 },
      { "price" : 1 } 
   ] )

- Using the ordering of ``{ item: 1, type: 1 }`` index,
  :method:`~cursor.max()` limits the query to the documents
  that are below the bound of ``item`` equal to ``apple`` and
  ``type`` equal to ``jonagold``:

  .. code-block:: javascript

     db.products.find().max( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )

  The query returns the following documents:

  .. code-block:: javascript

   { "_id" : 6, "item" : "apple", "type" : "cortland", "price" : NumberDecimal("1.29") }
   { "_id" : 2, "item" : "apple", "type" : "fuji", "price" : NumberDecimal("1.99") }
   { "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : NumberDecimal("1.99") }

- Using the ordering of the index ``{ price: 1 }``, :method:`~cursor.max()` 
  limits the query to the documents that are below
  the index key bound of ``price`` equal to ``NumberDecimal("1.99")`` and
  :method:`~cursor.min()` limits the query to the documents
  that are at or above the index key bound of ``price`` equal to
  ``NumberDecimal("1.39")``:

  .. note::

     The bound specified by :method:`~cursor.max()` must be greater than 
     the bound specified by :method:`~cursor.min()`.

  .. code-block:: javascript

     db.products.find().min( { price: NumberDecimal("1.39") } ).max( { price:  NumberDecimal("1.99") } ).hint( { price: 1 } )

  The query returns the following documents:

  .. code-block:: javascript

     { "_id" : 10, "item" : "orange", "type" : "navel", "price" : NumberDecimal("1.39") }