On this page
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.
Tip
Rather than run the
find
command directly, you can use thedb.collection.find()
helper provided in themongo
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.
|
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 |
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 |
readConcern |
document | Optional. Specifies the read concern. The readConcern option has the following syntax: Changed in version 3.6.
Possible read concern levels are:
For more formation on the read concern levels, see Read Concern Levels. For The |
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 For example, the following command replays documents from the
Changed in version 3.6: |
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 |
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. |
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