find

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

The find command has the following syntax:

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

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 Project Fields to Return from Query and Projection Operators.

find() operations on views do not support the following projection operators:

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.
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 string Optional. A comment to attach to the query to help interpret and trace query profile data.
maxScan positive integer Optional. Maximum number of documents or index keys to scan when executing the query.
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.

The readConcern option has the following syntax:

Changed in version 3.6.

readConcern: { level: <value> }

Possible read concern levels are:

For more formation on the read concern levels, see Read Concern Levels.

For "local" (default) or "majority" read concern level, you can specify the afterClusterTime option to have the read operation return data that meets the level requirement and the specified after cluster time requirement. For more information, see Read Operations and Causally Consistent Sessions.

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.
min document Optional. The inclusive lower bound for a specific index. See cursor.min() for details.
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

Optional. An internal command for replaying a replica set’s oplog.

To use oplogReplay, the find field must refer to a capped collection and you must provide a filter option comparing the ts document field to a timestamp using one of the following comparison operators:

For example, the following command replays documents from the data capped collection with a timestamp later than or equal to January 1st, 2018 UTC:

{ find: "data",
  oplogReplay: true,
  filter: { ts: { $gte: new Timestamp(1514764800, 0) } } }

Changed in version 3.6: $eq is now supported.

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.

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:

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.

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:

{
   "cursor" : {
      "firstBatch" : [
         {
            "_id" : ObjectId("5e8e2ca217b5324fa9847435"),
            "zipcode" : "20001",
            "x" : 1
         },
         {
            "_id" : ObjectId