- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.find()
db.collection.find()¶
On this page
Definition¶
-
db.collection.
find
(query, projection)¶ Selects documents in a collection or view and returns a cursor to the selected documents.
Parameter Type Description query
document Optional. Specifies selection filter 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 in the documents that match the query filter. To return all fields in the matching documents, omit this parameter. For details, see Projection. 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.
Behavior¶
Projection¶
The projection
parameter determines which fields are returned in
the matching documents. The projection
parameter takes a document
of the following form:
The <value>
can be any of the following:
1
ortrue
to include the field in the return documents.0
orfalse
to exclude the field.Expression using a Projection Operators.
find()
operations on views do not support the following projection operators:
Note
For the _id
field, you do not have to explicitly specify _id:
1
to return the _id
field. The find()
method always returns the _id field
unless you specify _id: 0
to suppress 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.
Cursor Handling¶
Executing db.collection.find()
in the mongo
shell
automatically iterates the cursor to display up to the first 20
documents. Type it
to continue iteration.
To access the returned documents with a driver, use the appropriate cursor handling mechanism for the driver language.
Read Concern¶
To specify the read concern for
db.collection.find()
, use the cursor.readConcern()
method.
Type Bracketing¶
MongoDB treats some data types as equivalent for comparison purposes. For instance, numeric types undergo conversion before comparison. For most data types, however, comparison operators only perform comparisons on documents where the BSON type of the target field matches the type of the query operand. Consider the following collection:
The following query uses $gt
to return documents where the
value of qty
is greater than 4
.
The query returns the following documents:
The document with _id
equal to "avocados"
is not
returned because its qty
value is of type string
while the
$gt
operand is of type integer
.
The document with _id
equal to "oranges"
is not returned
because its qty
value is of type object
.
Note
To enforce data types in a collection, use Schema Validation.
Session Idle Timeout¶
Starting in MongoDB 3.6, MongoDB drivers and the mongo
shell 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 the mongo
shell creates an implicit session and associates 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 may be idle for longer than 30 minutes, associate
the operation with an explicit session using
Session.startSession()
and periodically refresh the session
using the refreshSessions
command. See
Session Idle Timeout
for more information.
Examples¶
The examples in this section use documents from the bios collection where the documents generally have the form:
To create and populate the bios
collection, see
The bios Example Collection.
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¶
Query for Equality¶
The following operation returns documents in the bios collection where
_id
equals5
:The following operation returns documents in the bios collection where the field
last
in thename
embedded document equals"Hopper"
:Note
To access fields in an embedded document, use dot notation (
"<embedded document>.<field>"
).
Query Using Operators¶
To find documents that match a set of selection criteria, call
find()
with the <criteria>
parameter.
MongoDB provides various query operators to specify the criteria.
The following operation uses the
$in
operator to return documents in the bios collection where_id
equals either5
orObjectId("507c35dd8fada716c89d0013")
:The following operation uses the
$gt
operator returns all the documents from thebios
collection wherebirth
is greater thannew Date('1950-01-01')
:The following operation uses the
$regex
operator to return documents in the bios collection wherename.last
field starts with the letterN
(or is"LIKE N%"
)
For a list of the query operators, see Query Selectors.
Query for Ranges¶
Combine comparison operators to specify ranges for a field. The
following operation returns from the bios collection documents where birth
is
between new Date('1940-01-01')
and new Date('1960-01-01')
(exclusive):
For a list of the query operators, see Query Selectors.
Query for Multiple Conditions¶
The following operation returns all the documents from the bios
collection where birth
field
is greater than
new Date('1950-01-01')
and death
field does not exists:
For a list of the query operators, see Query Selectors.
Query Embedded Documents¶
The following examples query the name
embedded field in the
bios collection.
Query Exact Matches on Embedded Documents¶
The following operation returns documents in the bios collection where the embedded document name
is
exactly { first: "Yukihiro", last: "Matsumoto" }
, including the
order:
The name
field must match the embedded document exactly. The query does
not match documents with the following name
fields:
Query Fields of an Embedded Document¶
The following operation returns documents in the bios collection where the embedded document 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 an embedded document:
The query matches the document where the name
field contains an
embedded document 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:
For more information and examples, see also Query on Embedded/Nested Documents.
Query Arrays¶
Query for an Array Element¶
The following examples query the contribs
array in the bios
collection.
The following operation returns documents in the bios collection where the array field
contribs
contains the element"UNIX"
:The following operation returns documents in the bios collection where the array field
contribs
contains the element"ALGOL"
or"Lisp"
:The following operation use the
$all
query operator to return documents in the bios collection where the array fieldcontribs
contains both the elements"ALGOL"
and"Lisp"
:For more examples, see
$all
. See also$elemMatch
.The following operation uses the
$size
operator to return documents in the bios collection where the array size ofcontribs
is 4:
For more information and examples of querying an array, see:
For a list of array specific query operators, see Array.
Query an Array of Documents¶
The following examples query the awards
array in the bios
collection.
The following operation returns documents in the bios collection where the
awards
array contains an element withaward
field equals"Turing Award"
:The following operation returns documents in the bios collection where the
awards
array contains at least one element with both theaward
field equals"Turing Award"
and theyear
field greater than 1980:Use the
$elemMatch
operator to specify multiple criteria on an array element.
For more information and examples of querying an array, see:
For a list of array specific query operators, see Array.
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.
Note
Unless the _id
field is explicitly excluded in the projection
document _id: 0
, the _id
field is returned.
Specify the Fields to Return¶
The following operation finds all documents in the bios collection and returns only the name
field, contribs
field and _id
field:
Note
Unless the _id
field is explicitly excluded in the projection
document _id: 0
, the _id
field is returned.
Explicitly Excluded Fields¶
The following operation queries the bios collection and returns all fields except
the first
field in the name
embedded document and the birth
field:
Explicitly Exclude the _id
Field¶
Note
Unless the _id
field is explicitly excluded in the projection
document _id: 0
, the _id
field is returned.
The following operation finds documents in the bios collection and returns only the name
field and the contribs
field:
On Arrays and Embedded Documents¶
The following operation queries the bios collection and returns the last
field in
the name
embedded document and the first two elements in the contribs
array:
See also
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 to
access up to the first 20 documents that match the query. You can set the
DBQuery.shellBatchSize
variable to change the number of automatically
iterated documents.
To manually iterate over the results, assign the returned cursor to a variable
with the var
keyword, as shown in the following sections.
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:
Specify Collation¶
Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.
The collation()
method specifies the collation for the db.collection.find()
operation.
Combine Cursor Methods¶
The following statements chain cursor methods limit()
and sort()
:
The two statements are equivalent; i.e. the order in which you chain
the limit()
and the sort()
methods
is not significant. Both statements return the first five documents, as
determined by the ascending sort order on ‘name’.