- MongoDB CRUD Operations >
- Query Documents
Query Documents¶
On this page
Query Method¶
MongoDB provides the db.collection.find()
method to read
documents from a collection. The db.collection.find()
method
returns a cursor to the matching
documents.
For the db.collection.find()
method, you can specify the
following optional fields:
- a query filter to specify which documents to return.
- a query projection to specifies which fields from the matching documents to return. The projection limits the amount of data that MongoDB returns to the client over the network.
You can optionally add a cursor modifier to impose limits, skips, and
sort orders. The order of documents returned by a query is not defined
unless you specify a sort()
.
Example Collection¶
The examples on this page use the db.collection.find()
method
in the mongo
shell. In the mongo
shell, if the returned cursor is not assigned to a variable using the
var
keyword, then the cursor is automatically iterated up to 20
times [2] to print up to the first 20 documents in
the results.
To populate the users
collection referenced in the examples,
run the following in mongo
shell:
Note
If the users
collection already contains documents with the same
_id
values, you need to drop
the collection (db.users.drop()
) before inserting the example
documents.
Select All Documents in a Collection¶
An empty query filter document ({}
)
selects all documents in the collection:
Omitting a query filter document to the db.collection.find()
is equivalent to specifying an empty query document. As such, the
following operation is equivalent to the previous operation:
Specify Query Filter Conditions¶
Specify Equality Condition¶
A query filter document can specify
equality condition with <field>:<value>
expressions to select
all documents that contain the <field>
with the specified
<value>
:
The following example retrieves from the users
collection all
documents where the status
field has the value "A"
:
Specify Conditions Using Query Operators¶
A query filter document can use the query operators to specify conditions in the following form:
The following example retrieves all documents from the users
collection where status
equals either "P"
or
"D"
:
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 Query and Projection 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.
The following example retrieves all documents in the users
collection where the status
equals "A"
and age
is less than ($lt
) 30
:
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.
The following example retrieves all documents in the collection where
the status
equals "A"
or age
is less than
($lt
) 30
:
Note
Queries which use comparison operators are subject to Type Bracketing.
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``status`` equals "A"
and either age
is less than than ($lt
) 30
or
type
equals 1
:
Query on 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 exact 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
favorites
field is an embedded document that contains only the
fields artist
equal to "Picasso"
and food
equal to
"pizza"
, in that 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 favorites
field is an embedded
document that includes the field artist
equal to "Picasso"
and
may contain other fields:
Query on 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.
If you specify multiple conditions using the $elemMatch
operator, the array must contain at least one element that satisfies
all the conditions. See Single Element Satisfies the Criteria.
If you specify multiple conditions without using the
$elemMatch
operator, then some combination of the array
elements, not necessarily a single element, must satisfy all the
conditions; i.e. different elements in the array can satisfy different
parts of the conditions. See
Combination of Elements Satisfies the Criteria.
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.
The following example queries for all documents where the field
badges
is an array that holds exactly two elements, "blue"
,
and "black"
, in this order:
The query matches the following document:
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.
The following example queries for all documents where badges
is an
array that contains "black"
as one of its elements:
The query matches the following documents:
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 badges
is an array that contains
"black"
as the first element:
The operation returns the following document:
Specify Multiple Criteria for Array Elements¶
Single Element Satisfies the Criteria¶
Use $elemMatch
operator to specify multiple criteria on the
elements of an array such that at least one array element satisfies all
the specified criteria.
The following example queries for documents where the finished
array
contains at least one element that is greater than ($gt
) 15
and less than ($lt
) 20
:
The operation returns the following documents, whose finished
array
contains at least one element which meets both criteria:
Combination of Elements Satisfies the Criteria¶
The following example queries for documents where the finished
array
contains elements that in some combination satisfy the query
conditions; e.g., one element can satisfy the greater than 15
condition and another element can satisfy the less than 20
condition, or a single element can satisfy both:
The operation returns the following documents:
Array of Embedded 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 embedded document’s position using the dot notation.
The following example selects all documents where the points
contains an array whose first element (i.e. index is 0
) is a
document that contains the field points
whose value is less than
or equal to 55
:
The operation returns the following documents:
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 embedded document.
The following example selects all documents where the points
is an
array with at least one embedded document that contains the field
points
whose value is less than or equal to 55
:
The operation returns the following documents:
Specify Multiple Criteria for Array of Documents¶
Single Element Satisfies the Criteria¶
Use $elemMatch
operator to specify multiple criteria on an
array of embedded documents such that at least one embedded document
satisfies all the specified criteria.
The following example queries for documents where the points
array
has at least one embedded document that contains both the field
points
less than or equal to 70
and the field bonus
equal
to 20
:
The operation returns the following document:
Combination of Elements Satisfies the Criteria¶
The following example queries for documents where the points
array
contains elements that in some combination satisfy the query
conditions; e.g. one element satisfies the points
less than or
equal to 70
condition and another element satisfies the bonus
equal to 20
condition, or a single element satisfies both
criteria:
The query returns the following documents:
Additional Methods¶
The following methods can also read documents from a collection:
db.collection.findOne
[1]- In aggregation pipeline, the
$match
pipeline stage provides access to MongoDB queries.
[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. |
Read Isolation¶
New in version 3.2.
For reads to replica sets and replica set shards, read concern allows clients to choose a level of isolation for their reads.
For more information, see Read Concern.
[2] | You can use the DBQuery.shellBatchSize to
change the number of iteration from the default value 20 . See
Working with the mongo Shell for more information. |