- MongoDB CRUD Operations >
- MongoDB CRUD Tutorials >
- Query Documents
Query Documents¶
On this page
In MongoDB, the db.collection.find()
method retrieves
documents from a collection. [1] The
db.collection.find()
method returns a cursor to the retrieved documents.
This tutorial provides examples of read operations using the
db.collection.find()
method in the mongo
shell. In
these examples, the retrieved documents contain all their fields. To
restrict the fields to return in the retrieved documents, see
Limit Fields to Return from a Query.
[1] | The db.collection.findOne() method also performs a read
operation to return a single document. Internally, the
db.collection.findOne() method is the
db.collection.find() method with a limit of 1. |
Select All Documents in a Collection¶
An empty query document ({}
) selects all documents in the
collection:
Not specifying a query document to the find()
is equivalent to specifying an empty query document. Therefore the
following operation is equivalent to the previous operation:
Specify Equality Condition¶
To specify equality condition, use the query document { <field>:
<value> }
to select all documents that contain the <field>
with
the specified <value>
.
The following example retrieves from the inventory
collection all
documents where the type
field has the value snacks
:
Specify Conditions Using Query Operators¶
A query document can use the query operators to specify conditions in a MongoDB query.
The following example selects all documents in the inventory
collection where the value of the type
field is either 'food'
or 'snacks'
:
Although you can express this query using the $or
operator,
use the $in
operator rather than the $or
operator when performing equality checks on the same field.
Refer to the Operators document for the complete list of query operators.
Specify AND
Conditions¶
A compound query can specify conditions for more than one field in the
collection’s documents. Implicitly, a logical AND
conjunction
connects the clauses of a compound query so that the query selects the
documents in the collection that match all the conditions.
In the following example, the query document specifies an equality
match on the field type
and a less than ($lt
)
comparison match on the field price
:
This query selects all documents where the type
field has the value
'food'
and the value of the price
field is less than
9.95
. See comparison operators
for other comparison operators.
Specify OR
Conditions¶
Using the $or
operator, you can specify a compound query
that joins each clause with a logical OR
conjunction so that the
query selects the documents in the collection that match at least one
condition.
In the following example, the query document selects all documents in
the collection where the field qty
has a value greater than
($gt
) 100
or the value of the price
field is
less than ($lt
) 9.95
:
Specify AND
as well as OR
Conditions¶
With additional clauses, you can specify precise conditions for matching documents.
In the following example, the compound query document selects all
documents in the collection where the value of the type
field is
'food'
and either the qty
has a value greater than
($gt
) 100
or the value of the price
field is less
than ($lt
) 9.95
:
Embedded Documents¶
When the field holds an embedded document, a query can either specify an exact match on the embedded document or specify a match by individual fields in the embedded document using the dot notation.
Exact Match on the Embedded Document¶
To specify an equality match on the whole embedded document, use the
query document { <field>: <value> }
where <value>
is the
document to match. Equality matches on an embedded document require an
exact match of the specified <value>
, including the field order.
In the following example, the query matches all documents where the
value of the field producer
is an embedded document that contains
only the field company
with the value 'ABC123'
and the field
address
with the value '123 Street'
, in the exact order:
Equality Match on Fields within an Embedded Document¶
Use the dot notation to match by specific fields in an embedded document. Equality matches for specific fields in an embedded document will select documents in the collection where the embedded document contains the specified fields with the specified values. The embedded document can contain additional fields.
In the following example, the query uses the dot notation to
match all documents where the value of the field producer
is an
embedded document that contains a field company
with the value
'ABC123'
and may contain other fields:
Arrays¶
When the field holds an array, you can query for an exact array match or for specific values in the array. If the array holds embedded documents, you can query for specific fields in the embedded documents using dot notation.
Exact Match on an Array¶
To specify equality match on an array, use the query document {
<field>: <value> }
where <value>
is the array to match. Equality
matches on the array require that the array field match exactly the
specified <value>
, including the element order.
In the following example, the query matches all documents where the
value of the field tags
is an array that holds exactly three
elements, 'fruit'
, 'food'
, and 'citrus'
, in this order:
Match an Array Element¶
Equality matches can specify a single element in the array to match. These specifications match if the array contains at least one element with the specified value.
In the following example, the query matches all documents where the
value of the field tags
is an array that contains 'fruit'
as
one of its elements:
Match a Specific Element of an Array¶
Equality matches can specify equality matches for an element at a particular index or position of the array using the dot notation.
In the following example, the query uses the dot notation to
match all documents where the value of the tags
field is an array
whose first element equals 'fruit'
:
Array of Embedded Documents¶
Consider that the inventory
collection includes the following
documents:
Match a Field in the Embedded Document Using the Array Index¶
If you know the array index of the embedded document, you can specify the document using the subdocument’s position using the dot notation.
The following example selects all documents where the memos
contains an array whose first element (i.e. index is 0
) is a
document that contains the field by
whose value is 'shipping'
:
The operation returns the following document:
Match a Field Without Specifying Array Index¶
If you do not know the index position of the document in the array,
concatenate the name of the field that contains the array, with a dot
(.
) and the name of the field in the subdocument.
The following example selects all documents where the memos
field
contains an array that contains at least one embedded document that
contains the field by
with the value 'shipping'
:
The operation returns the following documents:
Match Multiple Fields¶
To match by multiple fields in the embedded document, you can use
either dot notation or the $elemMatch
operator:
The following example uses dot notation to find documents where whose
memos
field is an array that contains at least one document that
contains the field memo
equal to 'on time'
and at least one
document that contains the field by
equal to 'shipping'
.
The embedded documents that satisfy the two conditions can be either the same document or separate documents; i.e. a single embedded document can, but does not need to, satisfy both conditions. The query returns the following documents:
The following example uses $elemMatch
to query for documents
where memos
field is an array that has at least one embedded
document that contains both the field memo
equal to 'on time'
and the field by
equal to 'shipping'
:
The operation returns the following document: