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:The command accepts the following fields:
Field Type Description find
string The name of the collection 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. 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. readConcern
document Optional. Specifies the read concern. The default level is
"local"
.To use a read concern level of
"majority"
, you must use the WiredTiger storage engine and start themongod
instances with the--enableMajorityReadConcern
command line option (or thereplication.enableMajorityReadConcern
setting if using a configuration file).Only replica sets using
protocol version 1
support"majority"
read concern. Replica sets running protocol version 0 do not support"majority"
read concern.To ensure that a single thread can read its own writes, use
"majority"
read concern and"majority"
write concern against the primary of the replica set.Note
The
getMore
command uses thereadConcern
level specified in the originatingfind
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:
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.
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.
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.
Note
To use a read concern level of
"majority"
, you must use the WiredTiger storage engine and start themongod
instances with the--enableMajorityReadConcern
command line option (or thereplication.enableMajorityReadConcern
setting if using a configuration file).Only replica sets using
protocol version 1
support"majority"
read concern. Replica sets running protocol version 0 do not support"majority"
read concern.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.
To ensure that a single thread can read its own writes, use
"majority"
read concern and "majority"
write concern against the primary of the replica set.
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:
See also