> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# cursor.hint() (mongosh method)

## Definition

**Important: mongosh Method**

This page documents a [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.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 [MongoDB driver documentation.](https://www.mongodb.com/docs/drivers/)

Call this method on a query to override MongoDB's default index selection and [query optimization process](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-read-operations-query-optimization). Use [`db.collection.getIndexes()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.getindexes.md#mongodb-method-db.collection.getIndexes) to return the list of current indexes on a collection.

The [`cursor.hint()`](https://www.mongodb.com/docs/manual/reference/method/cursor.hint.md#mongodb-method-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. |

## Compatibility

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

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

**Note:**

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Behavior

- When an [index filter](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-index-filters) exists for the query shape, MongoDB ignores the [`hint()`.](https://www.mongodb.com/docs/manual/reference/method/cursor.hint.md#mongodb-method-cursor.hint)

- If a query includes a `$text` expression, you cannot use [`hint()`](https://www.mongodb.com/docs/manual/reference/method/cursor.hint.md#mongodb-method-cursor.hint) to specify which index to use for the query.

- If you use [`hint()`](https://www.mongodb.com/docs/manual/reference/method/cursor.hint.md#mongodb-method-cursor.hint) on a [hidden index](https://www.mongodb.com/docs/manual/core/index-hidden.md) or an index that doesn't exist, the operation returns an error.

- On a [time series collections](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-time-series-collection), you can only specify hints using the index name, not the index key pattern.

- Cluster query settings take precedence over query settings or index hints passed as a command field. MongoDB ignores index hints in command fields if a matching query setting already contains index hints.

  Index hints don't affect [query shape.](https://www.mongodb.com/docs/manual/core/query-shapes.md#std-label-query-shapes)

  For more information about hints and query settings, see [Query Settings Syntax.](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#std-label-setQuerySettings-syntax)

### $natural

Use `$natural` in conjunction with `cursor.hint()` to perform a collection scan to return documents in [natural order.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-natural-order)

For usage, see [Force Collection Scans.](https://www.mongodb.com/docs/manual/reference/method/cursor.hint.md#std-label-hint-collection-scans)

**Note:**

Prior to MongoDB 7.0, [`$natural`](https://www.mongodb.com/docs/manual/reference/method/cursor.hint.md#mongodb-operator-metaOp.-natural) accepts incorrect type values, such as `0`, `NaN`, "X", and `-0.01`. After MongoDB 7.0, if you pass any value other than `1` and `-1` to [`$natural`](https://www.mongodb.com/docs/manual/reference/method/cursor.hint.md#mongodb-operator-metaOp.-natural), MongoDB returns an error.

## Examples

### Specify an Index

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

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

You can also specify the index using the index name:

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

### Force Collection Scans

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

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

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

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

**See also:**

- [Indexes](https://www.mongodb.com/docs/manual/indexes.md#std-label-indexes)

- [Query Plans](https://www.mongodb.com/docs/manual/core/query-plans.md)

- [Index Filters](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-index-filters)