cursor.hint.txt

.. _cursor-hint:

=============
cursor.hint()
=============

.. default-domain:: mongodb

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

Definition
----------

.. method:: cursor.hint(index)


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


   Call this method on a query to override MongoDB's default index
   selection and :ref:`query optimization process <read-operations-query-optimization>`.
   Use :method:`db.collection.getIndexes()` to return the list of
   current indexes on a collection.

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


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

      * - Parameter

        - Type

        - Description

      * - ``index``

        - string or document

        - The index to "hint" or force MongoDB to use when performing the query.
          Specify the index either by the index name or by the index
          specification document.

          You can also specify ``{ $natural : 1 }`` to force the query to perform a 
          forwards collection scan, or ``{ $natural : -1 }`` for a reverse 
          collection scan.

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
--------

- When an :ref:`index filter <index-filters>` exists for the query
  shape, MongoDB ignores the :method:`~cursor.hint()`.

- .. include:: /includes/fact-hint-text-query-restriction.rst

- If you use :method:`~cursor.hint()` on a :doc:`hidden index
  </core/index-hidden>` or an index that doesn't exist, the operation
  returns an error.

- On a :term:`time series collections <time series collection>`, you
  can only specify hints using the index name, not the index key
  pattern.

$natural
~~~~~~~~

.. operator:: $natural

Use ``$natural`` in conjunction with ``cursor.hint()`` to perform a
collection scan to return documents in :term:`natural order`.

For usage, see :ref:`hint-collection-scans`.

Examples
--------

Specify an Index
~~~~~~~~~~~~~~~~

The following example returns all documents in the collection named
``users`` using the index on the ``age`` field.

.. code-block:: javascript

   db.users.find().hint( { age: 1 } )

You can also specify the index using the index name:

.. code-block:: javascript

   db.users.find().hint( "age_1" )

.. _hint-collection-scans:

Force Collection Scans
~~~~~~~~~~~~~~~~~~~~~~

You can specify ``{ $natural : 1 }`` to force the query to perform a forwards
collection scan:

.. code-block:: javascript

   db.users.find().hint( { $natural : 1 } )

You can also specify ``{ $natural : -1 }`` to force the query to perform a 
reverse collection scan:

.. code-block:: javascript

   db.users.find().hint( { $natural : -1 } )

.. seealso::

   - :doc:`/indexes`
   - :doc:`/core/query-plans`
   - :ref:`index-filters`