- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.find()
db.collection.find()¶
On this page
Definition¶
-
db.collection.
find
(<criteria>, <projection>)¶ Selects documents in a collection and returns a cursor to the selected documents. [1]
Parameter Type Description criteria
document Optional. Specifies selection criteria using query operators. To return all documents in a collection, omit this parameter or pass an empty document ( {}
).projection
document Optional. Specifies the fields to return using projection operators. To return all fields in the matching document, omit this parameter. Returns: A cursor to the documents that match the query
criteria. When thefind()
method “returns documents,” the method is actually returning a cursor to the documents.If the
projection
argument is specified, the matching documents contain only theprojection
fields and the_id
field. You can optionally exclude the_id
field.Executing
find()
directly in themongo
shell automatically iterates the cursor to display up to the first 20 documents. Typeit
to continue iteration.To access the returned documents with a driver, use the appropriate cursor handling mechanism for the driver language.
The projection
parameter takes a document of the following form:
The <boolean>
value can be any of the following:
1
ortrue
to include the field. Thefind()
method always includes the _id field even if the field is not explicitly stated to return in the projection parameter.0
orfalse
to exclude the field.
A projection
cannot contain both include and exclude
specifications, except for the exclusion of the _id
field. In
projections that explicitly include fields, the _id
field is the
only field that you can explicitly exclude.
[1] | db.collection.find() is a
wrapper for the more formal query structure that uses the
$query operator. |
Examples¶
Find All Documents in a Collection¶
The find()
method with no parameters
returns all documents from a collection and returns all fields for the
documents. For example, the following operation returns all documents in
the bios collection:
Find Documents that Match Query Criteria¶
To find documents that match a set of selection criteria, call
find()
with the <criteria>
parameter. The following operation returns all the documents from the
collection products
where qty
is greater than 25
:
Query for Equality¶
The following operation returns documents in the bios collection where _id
equals 5
:
Query Using Operators¶
The following operation returns documents in the bios collection where _id
equals either 5
or ObjectId("507c35dd8fada716c89d0013")
:
Query for Ranges¶
Combine comparison operators to specify ranges. The following operation
returns documents with field
between value1
and value2
:
Query a Field that Contains an Array¶
If a field contains an array and your query has multiple conditional operators, the field as a whole will match if either a single array element meets the conditions or a combination of array elements meet the conditions.
Given a collection students
that contains the following documents:
The following query:
Matches the following documents:
In the document with _id
equal to 1
, the score: [ -1, 3 ]
meets the conditions because the element -1
meets the $lt: 2
condition and the element 3
meets the $gt: 0
condition.
In the document with _id
equal to 2
, the score: [ 1, 5 ]
meets the conditions because the element 1
meets both the $lt: 2
condition and the $gt: 0
condition.
Query Arrays¶
Query for an Array Element¶
The following operation returns documents in the bios collection where the array field contribs
contains the element "UNIX"
:
Query an Array of Documents¶
The following operation returns documents in the bios collection where awards
array contains a
subdocument element that contains the award
field equal to "Turing
Award"
and the year
field greater than 1980:
Query Subdocuments¶
Query Exact Matches on Subdocuments¶
The following operation returns documents in the bios collection where the subdocument name
is
exactly { first: "Yukihiro", last: "Matsumoto" }
, including the
order:
The name
field must match the sub-document exactly. The query does
not match documents with the following name
fields:
Query Fields of a Subdocument¶
The following operation returns documents in the bios collection where the subdocument name
contains a field first
with the value "Yukihiro"
and a field
last
with the value "Matsumoto"
. The query uses dot
notation to access fields in a subdocument:
The query matches the document where the name
field contains a
subdocument with the field first
with the value "Yukihiro"
and a
field last
with the value "Matsumoto"
. For instance, the query
would match documents with name
fields that held either of the
following values:
Projections¶
The projection
parameter specifies which fields to return. The
parameter contains either include or exclude specifications, not both,
unless the exclude is for the _id
field.
Specify the Fields to Return¶
The following operation returns all the documents from the products
collection where qty
is greater than 25
and returns only the
_id
, item
and qty
fields:
The operation returns the following:
The following operation finds all documents in the bios collection and returns only the name
field, contribs
field and _id
field:
Explicitly Excluded Fields¶
The following operation queries the bios collection and returns all fields except
the the first
field in the name
subdocument and the birth
field:
Explicitly Exclude the _id
Field¶
The following operation excludes the _id
and qty
fields from the
result set:
The documents in the result set contain all fields except the _id
and qty
fields:
The following operation finds documents in the bios collection and returns only the name
field and the contribs
field:
On Arrays and Subdocuments¶
The following operation queries the bios collection and returns the last
field in
the name
subdocument and the first two elements in the contribs
array:
Iterate the Returned Cursor¶
The find()
method returns a cursor to
the results. In the mongo
shell, if the returned cursor is
not assigned to a variable using the var
keyword, the cursor is
automatically iterated up to 20 times to access up to the first 20
documents that match the query. You can use the
DBQuery.shellBatchSize
to change the number of iterations. See
Flags and Cursor Behaviors. To iterate manually,
assign the returned cursor to a variable using the var
keyword.
With Variable Name¶
The following example uses the variable myCursor
to iterate over the
cursor and print the matching documents:
Modify the Cursor Behavior¶
The mongo
shell and the drivers provide several cursor methods that call on the
cursor returned by the find()
method to
modify its behavior.
Order Documents in the Result Set¶
The sort()
method orders the documents in the result
set. The following operation returns documents in the bios
collection sorted in ascending
order by the name
field:
sort()
corresponds to the ORDER BY
statement in SQL.
Limit the Number of Documents to Return¶
The limit()
method limits the number of documents in
the result set. The following operation returns at most 5
documents
in the bios collection:
limit()
corresponds to the LIMIT
statement in SQL.
Set the Starting Point of the Result Set¶
The skip()
method controls the starting point of the
results set. The following operation skips the first 5
documents in
the bios collection and
returns all remaining documents:
Combine Cursor Methods¶
The following example chains cursor methods:
Regardless of the order you chain the limit()
and the
sort()
, the request to the server has the structure
that treats the query and the sort()
modifier as a
single object. Therefore, the limit()
operation method
is always applied after the sort()
regardless of the
specified order of the operations in the chain. See the meta query
operators.