cursor.hint.txt

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

.. default-domain:: mongodb

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

Definition
----------

.. method:: cursor.hint(index)

   Call this method on a query to override MongoDB's default index
   selection and :doc:`query optimization process </core/query-plans>`.
   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.
          
          
   


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

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`
   - :operator:`$hint`