Docs Home → Develop Applications → MongoDB Manual
find![](/docs/v5.2/assets/link.svg)
On this page
Definition![](/docs/v5.2/assets/link.svg)
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 thedb.collection.find()
helper provided inmongosh
or the equivalent helper in the drivers.
Syntax![](/docs/v5.2/assets/link.svg)
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:
Changed in version 5.0.
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>, "let": <document> // Added in MongoDB 5.0 } )
Command Fields![](/docs/v5.2/assets/link.svg)
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. | ||||||||||
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.
| ||||||||||
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, | ||||||||||
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 | ||||||||||
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:
A comment can be any valid BSON type (string, integer, object, array, etc). NoteChanged 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. TipWhen specifying | ||||||||||
readConcern | document | Optional. Specifies the read concern. Starting in MongoDB 3.6, the readConcern option has the following
syntax: Possible read concern levels are:
For more formation on the read concern levels, see Read Concern Levels. The | ||||||||||
max | document | Optional. The exclusive upper bound for a specific index. See
Starting in MongoDB 4.2, to use the | ||||||||||
min | document | Optional. The inclusive lower bound for a specific index. See
Starting in MongoDB 4.2, to use the | ||||||||||
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 | |||||||||||
oplogReplay | boolean | Deprecated since version 4.4. Optional. An internal command for replaying a replica set's oplog. To use For example, the following command replays documents from the
NoteDeprecatedChanged in version 4.4. Starting in MongoDB 4.4, the | ||||||||||
noCursorTimeout | boolean | Optional. Prevents the server from timing out idle cursors after an inactivity
period (10 minutes). | ||||||||||
boolean | Optional. For queries against a sharded collection, allows the
command (or subsequent Starting in MongoDB 4.4, if If the queried shards are initially available for the
| |||||||||||
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:
When specifying collation, the If the collation is unspecified but the collection has a
default collation (see 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. | ||||||||||
boolean | Optional. Use
For more complete documentation on For more information on memory restrictions for large blocking sorts, see Sort and Index Use. New in version 4.4. | |||||||||||
document | Optional. Specifies a document with a list of variables. This allows you to improve command readability by separating the variables from the query text. The document syntax is:
The variable is set to the value returned by the expression, and cannot be changed afterwards. To access the value of a variable in the command, use the double
dollar sign prefix ( NoteTo use a variable to filter results, you must access the variable
within the For a complete example using New in version 5.0. |
Output![](/docs/v5.2/assets/link.svg)
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("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 Starting in 4.4, if the operation against a sharded collection
returns partial results due to the unavailability of the queried
shard(s), the If the queried shards are initially available for the
|
"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![](/docs/v5.2/assets/link.svg)
$regex
Find Queries No Longer Ignore Invalid Regex![](/docs/v5.2/assets/link.svg)
Starting in MongoDB 5.1, invalid $regex options
options are no longer ignored. This change makes
$regex options
more consistent with
the use of $regex
in the aggregate
command and
projection queries.
Sessions![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
Starting in MongoDB 3.6, MongoDB drivers and mongosh
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 mongosh
create an implicit session and associate 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 Mongo.startSession()
and periodically refresh the
session using the refreshSessions
command. See
Session Idle Timeout for more information.
Transactions![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
Starting in MongoDB 4.2, if the client that issued find
disconnects before the operation completes, MongoDB marks find
for termination using killOp
.
Stable API![](/docs/v5.2/assets/link.svg)
When using Stable API V1, the following
find
command fields are not supported:
awaitData
max
min
noCursorTimeout
oplogReplay
returnKey
showRecordId
tailable
Examples![](/docs/v5.2/assets/link.svg)
Specify a Sort and Limit![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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.
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 mongosh
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![](/docs/v5.2/assets/link.svg)
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 } } )
mongosh
provides the cursor.collation()
to
specify collation for a
db.collection.find()
operation.
Use Variables in let
![](/docs/v5.2/assets/link.svg)
New in version 5.0.
To define variables that you can access elsewhere in the command, use the let option.
Note
To filter results using a variable, you must access the variable
within the $expr
operator.
Create a collection cakeFlavors
:
db.cakeFlavors.insertMany( [ { _id: 1, flavor: "chocolate" }, { _id: 2, flavor: "strawberry" }, { _id: 3, flavor: "cherry" } ] )
The following example defines a targetFlavor
variable in let
and
uses the variable to retrieve the chocolate cake flavor:
db.cakeFlavors.runCommand( { find: db.cakeFlavors.getName(), filter: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } }, let : { targetFlavor: "chocolate" } } )