find¶

On this page

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.

The find command has the following form:

{
   "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>,
   "snapshot": <bool>,
   "tailable": <bool>,
   "oplogReplay": <bool>,
   "noCursorTimeout": <bool>,
   "awaitData": <bool>,
   "allowPartialResults": <bool>,
   "collation": <document>
}

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: `$` `$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.
`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 option has the following syntax: readConcern: { level: <value> } Possible read concern values are: `"local"`. This is the default read concern level. `"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.
`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.
`snapshot`	boolean	Optional. Prevents the cursor from returning a document more than once because of an intervening write operation.
`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. Internal use for replica sets. To use oplogReplay, you must include the following condition in the filter: { ts: { $gte: <timestamp> } }
`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, returns partial results from the `mongos` if some shards are unavailable instead of throwing an error.
`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.

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.

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",

you must start the mongod instances with the --enableMajorityReadConcern command line option (or the replication.enableMajorityReadConcern set to true if using a configuration file).
replica sets must use WiredTiger storage engine and election protocol version 1.

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:

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:

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.