find¶

On this page

Definition
Syntax
Behavior
Examples

Definition¶

find¶: New in version 3.2.

Executes a query and returns the first batch of results and the cursor id, from which the client can construct a cursor.

Tip

Rather than run the find command directly, you can use the db.collection.find() helper provided in the mongo shell or the equivalent helper in the drivers.

Syntax¶

Changed in version 4.4: MongoDB deprecates the oplogReplay option to the find command. The optimization enabled by this flag in previous versions now happens automatically for eligible queries on the oplog. Therefore, you don’t need to specify this flag. If specified, the server accepts the flag for backwards compatibility, but the flag has no effect.

The find command has the following syntax:

copy

db.runCommand(
   {
      "find": <string>,
      "filter": <document>,
      "sort": <document>,
      "projection": <document>,
      "hint": <document or string>,
      "skip": <int>,
      "limit": <int>,
      "batchSize": <int>,
      "singleBatch": <bool>,
      "comment": <any>,
      "maxTimeMS": <int>,
      "readConcern": <document>,
      "max": <document>,
      "min": <document>,
      "returnKey": <bool>,
      "showRecordId": <bool>,
      "tailable": <bool>,
      "oplogReplay": <bool>,
      "noCursorTimeout": <bool>,
      "awaitData": <bool>,
      "allowPartialResults": <bool>,
      "collation": <document>,
      "allowDiskUse" : <bool>
   }
)

Command Fields¶

The command accepts the following fields:

Field	Type	Description
`find`	string	The name of the collection or view to query.
`filter`	document	Optional. The query predicate. If unspecified, then all documents in the collection will match the predicate.
sort	document	Optional. The sort specification for the ordering of the results.
`projection`	document	Optional. The projection specification to determine which fields to include in the returned documents. See Projection and Projection Operators. `find()` operations on views do not support the following projection operators: `$` `$elemMatch` `$slice` `$meta`
`hint`	string or document	Optional. Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index. Starting in MongoDB 4.2, with the following exception, `hint` is required if the command includes the `min` and/or `max` fields; `hint` is not required with `min` and/or `max` if the `filter` is an equality condition on the `_id` field `{ _id: <value> }`.
`skip`	Positive integer	Optional. Number of documents to skip. Defaults to 0.
`limit`	Non-negative integer	Optional. The maximum number of documents to return. If unspecified, then defaults to no limit. A limit of 0 is equivalent to setting no limit.
`batchSize`	non-negative integer	Optional. The number of documents to return in the first batch. Defaults to 101. A batchSize of 0 means that the cursor will be established, but no documents will be returned in the first batch. Unlike the previous wire protocol version, a batchSize of 1 for the `find` command does not close the cursor.
`singleBatch`	boolean	Optional. Determines whether to close the cursor after the first batch. Defaults to false.
`comment`	any	Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: mongod log messages, in the `attr.command.cursor.comment` field. Database profiler output, in the `command.comment` field. `currentOp` output, in the `command.comment` field. A comment can be any valid BSON type (string, integer, object, array, etc). Note Any comment set on a `find` command is inherited by any subsequent `getMore` commands run on the `find` cursor. Changed in version 4.4. Prior to 4.4, comments could only be strings.
`maxTimeMS`	positive integer	Optional. The cumulative time limit in milliseconds for processing operations on the cursor. MongoDB aborts the operation at the earliest following interrupt point. Tip When specifying `linearizable read concern`, always use `maxTimeMS` in case a majority of data bearing members are unavailable. `maxTimeMS` ensures that the operation does not block indefinitely and instead ensures that the operation returns an error if the read concern cannot be fulfilled.
`readConcern`	document	Optional. Specifies the read concern. Starting in MongoDB 3.6, the readConcern option has the following syntax: `readConcern: { level: <value> }` Possible read concern levels are: `"local"`. This is the default read concern level for read operations against primary and read operations against secondaries when associated with causally consistent sessions. `"available"`. This is the default for reads against secondaries when when not associated with causally consistent sessions. The query returns the instance’s most recent data. `"majority"`. Available for replica sets that use WiredTiger storage engine. `"linearizable"`. Available for read operations on the `primary` only. For more formation on the read concern levels, see Read Concern Levels. The `getMore` command uses the `readConcern` level specified in the originating `find` command.
`max`	document	Optional. The exclusive upper bound for a specific index. See `cursor.max()` for details. Starting in MongoDB 4.2, to use the `max` field, the command must also use `hint` unless the specified `filter` is an equality condition on the `_id` field `{ _id: <value> }`.
`min`	document	Optional. The inclusive lower bound for a specific index. See `cursor.min()` for details. Starting in MongoDB 4.2, to use the `min` field, the command must also use `hint` unless the specified `filter` is an equality condition on the `_id` field `{ _id: <value> }`.
`returnKey`	boolean	Optional. If true, returns only the index keys in the resulting documents. Default value is false. If returnKey is true and the `find` command does not use an index, the returned documents will be empty.
`showRecordId`	boolean	Optional. Determines whether to return the record identifier for each document. If true, adds a field $recordId to the returned documents.
`tailable`	boolean	Optional. Returns a tailable cursor for a capped collections.
`awaitData`	boolean	Optional. Use in conjunction with the tailable option to block a `getMore` command on the cursor temporarily if at the end of data rather than returning no data. After a timeout period, `find` returns as normal.
`oplogReplay`	boolean	Deprecated since version 4.4. Optional. An internal command for replaying a replica set’s oplog. To use `oplogReplay`, the `find` field must provide a `filter` option comparing the `ts` document field to a `timestamp` using one of the following comparison operators: `$gte` `$gt` `$eq` For example, the following command replays documents from the `data` capped collection with a timestamp later than or equal to January 1st, 2018 UTC: copy { find: "data", oplogReplay: true, filter: { ts: { $gte: new Timestamp(1514764800, 0) } } } Deprecated Changed in version 4.4. Starting in MongoDB 4.4, the `oplogReplay` field is deprecated. `find` fields that use the `$gte`, `$gt`, or `$eq` `filter` predicated on the `ts` field will automatically utilize the storage format of the replica set’s oplog to execute the command more efficiently. If specified, the server accepts the `oplogReplay` flag for backwards compatibility, but the flag has no effect.
`noCursorTimeout`	boolean	Optional. Prevents the server from timing out idle cursors after an inactivity period (10 minutes).
allowPartialResults	boolean	Optional. For queries against a sharded collection, allows the command (or subsequent `getMore` commands) to return partial results, rather than an error, if one or more queried shards are unavailable. Starting in MongoDB 4.4, if `find` (or subsequent `getMore` commands) returns partial results due to the unavailability of the queried shard(s), the output includes a `partialResultsReturned` indicator field. If the queried shards are initially available for the `find` command but one or more shards become unavailable in subsequent `getMore` commands, only the `getMore` commands run when a queried shard or shards are unavailable include the `partialResultsReturned` flag in the output.
`collation`	document	Optional. Specifies the collation to use for the operation. Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. The collation option has the following syntax: copy collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> } When specifying collation, the `locale` field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document. If the collation is unspecified but the collection has a default collation (see `db.createCollection()`), the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons. You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort. New in version 3.4.
allowDiskUse	boolean	Optional. Use `allowDiskUse` to allow MongoDB to use temporary files on disk to store data exceeding the 100 megabyte memory limit while processing a non-indexed (“blocking”) sort operation. If MongoDB requires using more than 100 megabytes of memory for a blocking sort operation, MongoDB returns an error unless the query specifies `allowDiskUse`. See Sort and Index Use for more information on blocking sort operations. `allowDiskUse` has no effect if MongoDB can satisfy the specified sort using an index, or if the blocking sort requires less than 100 megabytes of memory. For more complete documentation on `allowDiskUse`, see `cursor.allowDiskUse()`. For more information on memory restrictions for large blocking sorts, see Sort and Index Use. New in version 4.4.

Output¶

The command returns a document that contains the cursor information, including the cursor id and the first batch of documents. For example, the following document is returned when run against a sharded collection:

copy

{
   "cursor" : {
      "firstBatch" : [
         {
            "_id" : ObjectId("5e8e2ca217b5324fa9847435"),
            "zipcode" : "20001",
            "x" : 1
         },
         {
            "_id" : ObjectId("5e8e2ca517b5324fa9847436"),
            "zipcode" : "30001",
            "x" : 1
         }
      ],
      "partialResultsReturned" : true, // Starting in version 4.4
      "id" : NumberLong("668860441858272439"),
      "ns" : "test.contacts"
   },
   "ok" : 1,
   "operationTime" : Timestamp(1586380205, 1),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1586380225, 2),
      "signature" : {
         "hash" : BinData(0,"aI/jWsUVUSkMw8id+A+AVVTQh9Y="),
         "keyId" : NumberLong("6813364731999420435")
      }
   }
}

Field Description

cursor

Contains the cursor information, including the cursor id and the firstBatch of documents.

Starting in 4.4, if the operation against a sharded collection returns partial results due to the unavailability of the queried shard(s), the cursor document includes a partialResultsReturned field. To return partial results, rather than error, due to the unavailability of the queried shard(s), the find command must run with allowPartialResults set to true. See allowPartialResults.

If the queried shards are initially available for the find command but one or more shards become unavailable in subsequent getMore commands, only the getMore commands run when a queried shard or shards are unavailable include the partialResultsReturned flag in the output.

"ok" Indicates whether the command has succeeded (1) or failed (0).

In addition to the aforementioned find-specific fields, the db.runCommand() includes the following information for replica sets and sharded clusters:

$clusterTime
operationTime

See db.runCommand() Results for details.

Behavior¶

Sessions¶

New in version 4.0.

For cursors created inside a session, you cannot call getMore outside the session.

Similarly, for cursors created outside of a session, you cannot call getMore inside a session.

Session Idle Timeout¶

Starting in MongoDB 3.6, MongoDB drivers and the mongo shell associate all operations with a server session, with the exception of unacknowledged write operations. For operations not explicitly associated with a session (i.e. using Mongo.startSession()), MongoDB drivers and the mongo shell creates an implicit session and associates it with the operation.

If a session is idle for longer than 30 minutes, the MongoDB server marks that session as expired and may close it at any time. When the MongoDB server closes the session, it also kills any in-progress operations and open cursors associated with the session. This includes cursors configured with noCursorTimeout or a maxTimeMS greater than 30 minutes.

For operations that return a cursor, if the cursor may be idle for longer than 30 minutes, issue the operation within an explicit session using Session.startSession() and periodically refresh the session using the refreshSessions command. See Session Idle Timeout for more information.

Transactions¶

find can be used inside multi-document transactions.

For cursors created outside of a transaction, you cannot call getMore inside the transaction.
For cursors created in a transaction, you cannot call getMore outside the transaction.

Important

In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions.

For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.

Client Disconnection¶

Starting in MongoDB 4.2, if the client that issued the find disconnects before the operation completes, MongoDB marks the find for termination (i.e. killOp on the operation).

Examples¶

Specify a Sort and Limit¶

The following command runs the find command filtering on the rating field and the cuisine field. The command includes a projection to only return the following fields in the matching documents: _id, name, rating, and address fields.

The command sorts the documents in the result set by the name field and limits the result set to 5 documents.

copy

db.runCommand(
   {
     find: "restaurants",
     filter: { rating: { $gte: 9 }, cuisine: "italian" },
     projection: { name: 1, rating: 1, address: 1 },
     sort: { name: 1 },
     limit: 5
   }
)

Override Default Read Concern¶

To override the default read concern level of "local", use the readConcern option.

The following operation on a replica set specifies a read concern of "majority" to read the most recent copy of the data confirmed as having been written to a majority of the nodes.

To use read concern level of "majority", replica sets must use WiredTiger storage engine.

You can disable read concern "majority" for a deployment with a three-member primary-secondary-arbiter (PSA) architecture; however, this has implications for change streams (in MongoDB 4.0 and earlier only) and transactions on sharded clusters. For more information, see Disable Read Concern Majority.

copy

db.runCommand(
   {
     find: "restaurants",
     filter: { rating: { $lt: 5 } },
     readConcern: { level: "majority" }
   }
)

Regardless of the read concern level, the most recent data on a node may not reflect the most recent version of the data in the system.

The getMore command uses the readConcern level specified in the originating find command.

A readConcern can be specified for the mongo shell method db.collection.find() using the cursor.readConcern method:

copy

db.restaurants.find( { rating: { $lt: 5 } } ).readConcern("majority")

For more information on available read concerns, see Read Concern.

Specify Collation¶

New in version 3.4.

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

The following operation runs the find command with the collation specified:

copy

db.runCommand(
   {
     find: "myColl",
     filter: { category: "cafe", status: "a" },
     sort: { category: 1 },
     collation: { locale: "fr", strength: 1 }
   }
)

The mongo shell provides the cursor.collation() to specify collation for a db.collection.find() operation.