cursor.hint()¶

On this page

Definition
Behavior
Examples

Definition¶

cursor.hint(index)¶

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for a language-specific driver such as Node.js.

For MongoDB API drivers, refer to the language-specific :driver:`MongoDB driver documentation </>`.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

:v4.4:`mongo shell v4.4 </mongo>`
mongo shell v4.2

Call this method on a query to override MongoDB’s default index selection and query optimization process. Use db.collection.getIndexes() to return the list of current indexes on a collection.

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

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 index filter exists for the query shape, MongoDB ignores the hint().
You cannot use hint() if the query includes a $text query expression.
You cannot use hint() on a hidden index.
On a time series collections, you can only specify hints using the index name, not the index key pattern.

Examples¶

Specify an Index¶

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

copy

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

You can also specify the index using the index name:

copy

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

Force Collection Scans¶

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

copy

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

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

copy

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