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.
db.collection.find( <query filter>, <projection> )
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 mongoshell, if the returned cursor is not assigned to a variable using the var keyword, then the cursor is automatically iterated up to 20 times 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.
db.users.insertMany(
[
{
_id: 1,
name: "sue",
age: 19,
type: 1,
status: "P",
favorites: { artist: "Picasso", food: "pizza" },
finished: [ 17, 3 ],
badges: [ "blue", "black" ],
points: [
{ points: 85, bonus: 20 },
{ points: 85, bonus: 10 }
]
},
{
_id: 2,
name: "bob",
age: 42,
type: 1,
status: "A",
favorites: { artist: "Miro", food: "meringue" },
finished: [ 11, 25 ],
badges: [ "green" ],
points: [
{ points: 85, bonus: 20 },
{ points: 64, bonus: 12 }
]
},
{
_id: 3,
name: "ahn",
age: 22,
type: 2,
status: "A",
favorites: { artist: "Cassatt", food: "cake" },
finished: [ 6 ],
badges: [ "blue", "red" ],
points: [
{ points: 81, bonus: 8 },
{ points: 55, bonus: 20 }
]
},
{
_id: 4,
name: "xi",
age: 34,
type: 2,
status: "D",
favorites: { artist: "Chagall", food: "chocolate" },
finished: [ 5, 11 ],
badges: [ "red", "black" ],
points: [
{ points: 53, bonus: 15 },
{ points: 51, bonus: 15 }
]
},
{
_id: 5,
name: "xyz",
age: 23,
type: 2,
status: "D",
favorites: { artist: "Noguchi", food: "nougat" },
finished: [ 14, 6 ],
badges: [ "orange" ],
points: [
{ points: 71, bonus: 20 }
]
},
{
_id: 6,
name: "abc",
age: 43,
type: 1,
status: "A",
favorites: { food: "pizza", artist: "Picasso" },
finished: [ 18, 12 ],
badges: [ "black", "blue" ],
points: [
{ points: 78, bonus: 8 },
{ points: 57, bonus: 7 }
]
}
]
)
Select All Documents in a Collection
An empty query filter document ({}) selects all documents in the collection:
db.users.find( {} )
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:
db.users.find()
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>:
{ <field1>: <value1>, ... }
The following example retrieves from the users collection all documents where the status field has the value "A":
db.users.find( { status: "A" } )
Specify Conditions Using Query Operators
A query filter document can use the query operators to specify conditions in the following form:
{ <field1>: { <operator1>: <value1> }, ... }
The following example retrieves all documents from the users collection where status equals either "P"or "D":
db.users.find( { status: { $in: [ "P", "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:
db.users.find( { status: "A", age: { $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:
db.users.find(
{
$or: [ { status: "A" }, { age: { $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:
db.users.find(
{
status: "A",
$or: [ { age: { $lt: 30 } }, { type: 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:
db.users.find( { favorites: { artist: "Picasso", food: "pizza" } } )
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:
db.users.find( { "favorites.artist": "Picasso" } )
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:
db.users.find( { badges: [ "blue", "black" ] } )
The query matches the following document:
{
"_id" : 1,
"name" : "sue",
"age" : 19,
"type" : 1,
"status" : "P",
"favorites" : { "artist" : "Picasso", "food" : "pizza" },
"finished" : [ 17, 3 ]
"badges" : [ "blue", "black" ],
"points" : [ { "points" : 85, "bonus" : 20 }, { "points" : 85, "bonus" : 10 } ]
}
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:
db.users.find( { badges: "black" } )
The query matches the following documents:
{
"_id" : 1,
"name" : "sue",
"age" : 19,
"type" : 1,
"status" : "P",
"favorites" : { "artist" : "Picasso", "food" : "pizza" },
"finished" : [ 17, 3 ]
"badges" : [ "blue", "black" ],
"points" : [ { "points" : 85, "bonus" : 20 }, { "points" : 85, "bonus" : 10 } ]
}
{
"_id" : 4,
"name" : "xi",
"age" : 34,
"type" : 2,
"status" : "D",
"favorites" : { "artist" : "Chagall", "food" : "chocolate" },
"finished" : [ 5, 11 ],
"badges" : [ "red", "black" ],
"points" : [ { "points" : 53, "bonus" : 15 }, { "points" : 51, "bonus" : 15 } ]
}
{
"_id" : 6,
"name" : "abc",
"age" : 43,
"type" : 1,
"status" : "A",
"favorites" : { "food" : "pizza", "artist" : "Picasso" },
"finished" : [ 18, 12 ],
"badges" : [ "black", "blue" ],
"points" : [ { "points" : 78, "bonus" : 8 }, { "points" : 57, "bonus" : 7 } ]
}
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:
db.users.find( { "badges.0": "black" } )
The operation returns the following document:
{
"_id" : 6,
"name" : "abc",
"age" : 43,
"type" : 1,
"status" : "A",
"favorites" : { "food" : "pizza", "artist" : "Picasso" },
"finished" : [ 18, 12 ],
"badges" : [ "black", "blue" ],
"points" : [ { "points" : 78, "bonus" : 8 }, { "points" : 57, "bonus" : 7 } ]
}
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:
db.users.find( { finished: { $elemMatch: { $gt: 15, $lt: 20 } } } )
The operation returns the following documents, whose finished array contains at least one element which meets both criteria:
{
"_id" : 1,
"name" : "sue",
"age" : 19,
"type" : 1,
"status" : "P",
"favorites" : { "artist" : "Picasso", "food" : "pizza" },
"finished" : [ 17, 3 ]
"badges" : [ "blue", "black" ],
"points" : [ { "points" : 85, "bonus" : 20 }, { "points" : 85, "bonus" : 10 } ]
}
{
"_id" : 6,
"name" : "abc",
"age" : 43,
"type" : 1,
"status" : "A",
"favorites" : { "food" : "pizza", "artist" : "Picasso" },
"finished" : [ 18, 12 ],
"badges" : [ "black", "blue" ],
"points" : [ { "points" : 78, "bonus" : 8 }, { "points" : 57, "bonus" : 7 } ]
}
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:
db.users.find( { finished: { $gt: 15, $lt: 20 } } )
The operation returns the following documents:
{
"_id" : 1,
"name" : "sue",
"age" : 19,
"type" : 1,
"status" : "P",
"favorites" : { "artist" : "Picasso", "food" : "pizza" },
"finished" : [ 17, 3 ]
"badges" : [ "blue", "black" ],
"points" : [ { "points" : 85, "bonus" : 20 }, { "points" : 85, "bonus" : 10 } ]
}
{
"_id" : 2,
"name" : "bob",
"age" : 42,
"type" : 1,
"status" : "A",
"favorites" : { "artist" : "Miro", "food" : "meringue" },
"finished" : [ 11, 20 ],
"badges" : [ "green" ],
"points" : [ { "points" : 85, "bonus" : 20 }, { "points" : 64, "bonus" : 12 } ]
}
{
"_id" : 6,
"name" : "abc",
"age" : 43,
"type" : 1,
"status" : "A",
"favorites" : { "food" : "pizza", "artist" : "Picasso" },
"finished" : [ 18, 12 ],
"badges" : [ "black", "blue" ],
"points" : [ { "points" : 78, "bonus" : 8 }, { "points" : 57, "bonus" : 7 } ]
}
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:
db.users.find( { 'points.0.points': { $lte: 55 } } )
The operation returns the following documents:
{
"_id" : 4,
"name" : "xi",
"age" : 34,
"type" : 2,
"status" : "D",
"favorites" : { "artist" : "Chagall", "food" : "chocolate" },
"finished" : [ 5, 11 ],
"badges" : [ "red", "black" ],
"points" : [ { "points" : 53, "bonus" : 15 }, { "points" : 51, "bonus" : 15 } ]
}
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:
db.users.find( { 'points.points': { $lte: 55 } } )
The operation returns the following documents:
{
"_id" : 3,
"name" : "ahn",
"age" : 22,
"type" : 2,
"status" : "A",
"favorites" : { "artist" : "Cassatt", "food" : "cake" },
"finished" : [ 6 ],
"badges" : [ "blue", "red" ],
"points" : [ { "points" : 81, "bonus" : 8 }, { "points" : 55, "bonus" : 20 } ]
}
{
"_id" : 4,
"name" : "xi",
"age" : 34,
"type" : 2,
"status" : "D",
"favorites" : { "artist" : "Chagall", "food" : "chocolate" },
"finished" : [ 5, 11 ],
"badges" : [ "red", "black" ],
"points" : [ { "points" : 53, "bonus" : 15 }, { "points" : 51, "bonus" : 15 } ]
}
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:
db.users.find( { points: { $elemMatch: { points: { $lte: 70 }, bonus: 20 } } } )
The operation returns the following document:
{
"_id" : 3,
"name" : "ahn",
"age" : 22,
"type" : 2,
"status" : "A",
"favorites" : { "artist" : "Cassatt", "food" : "cake" },
"finished" : [ 6 ],
"badges" : [ "blue", "red" ],
"points" : [ { "points" : 81, "bonus" : 8 }, { "points" : 55, "bonus" : 20 } ]
}
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 70condition and another element satisfies the bonus equal to 20 condition, or a single element satisfies both criteria:
db.users.find( { "points.points": { $lte: 70 }, "points.bonus": 20 } )
The query returns the following documents:
{
"_id" : 2,
"name" : "bob",
"age" : 42,
"type" : 1,
"status" : "A",
"favorites" : { "artist" : "Miro", "food" : "meringue" },
"finished" : [ 11, 20 ],
"badges" : [ "green" ],
"points" : [ { "points" : 85, "bonus" : 20 }, { "points" : 64, "bonus" : 12 } ]
}
{
"_id" : 3,
"name" : "ahn",
"age" : 22,
"type" : 2,
"status" : "A",
"favorites" : { "artist" : "Cassatt", "food" : "cake" },
"finished" : [ 6 ],
"badges" : [ "blue", "red" ],
"points" : [ { "points" : 81, "bonus" : 8 }, { "points" : 55, "bonus" : 20 } ]
}
Additional Methods
The following methods can also read documents from a collection:
- db.collection.findOne
- In aggregation pipeline, the $match pipeline stage provides access to MongoDB queries.
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.