By default, queries in MongoDB return all fields in matching documents. To limit the amount of data that MongoDB sends to applications, you can include a projection document in the query operation.
Projection Document
The projection document limits the fields to return for all matching documents. The projection document can specify the inclusion of fields or the exclusion of field and has the following form:
{ field1: <value>, field2: <value> ... }
The <value> can be any of the following:
- 1 or true to include the field in the return documents.
- 0 or false to exclude the field.
- Expression using a Projection Operators.
NOTE: For the _id field, you do not have to explicitly specify _id: 1 to return the _id field. The db.collection.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.
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 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 }
]
}
]
)
Return All Fields in Matching Documents
If you specify no projection, the db.collection.find() method returns all fields of all documents that match the query.
The following example retrieves from the users collection all documents where the status equals "A":
db.users.find( { status: "A" } )
The matching documents includes all their fields:
{
"_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" : 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 } ]
}
Return the Specified Fields and the _id Field Only
A projection can explicitly include several fields. In the following operation, the db.collection.find()method returns all documents that match the query. In the result set, only the name, status and, by default, the _id fields return in the matching documents.
db.users.find( { status: "A" }, { name: 1, status: 1 } )
The operation returns the following documents:
{ "_id" : 2, "name" : "bob", "status" : "A" }
{ "_id" : 3, "name" : "ahn", "status" : "A" }
{ "_id" : 6, "name" : "abc", "status" : "A" }
Return Specified Fields Only
You can remove the _id field from the results by specifying its exclusion in the projection, as in the following example:
db.users.find( { status: "A" }, { name: 1, status: 1, _id: 0 } )
In the result set, only the name and status fields return in the matching documents:
{ "name" : "bob", "status" : "A" }
{ "name" : "ahn", "status" : "A" }
{ "name" : "abc", "status" : "A" }
Return All But the Excluded Field
To exclude a field or multiple fields, instead of listing the fields to include in the matching document, you can use a projection to exclude specific fields as in the following example:
db.users.find( { status: "A" }, { favorites: 0, points: 0 } )
In the result set, the favorites and the points fields do not return in the matching documents:
{
"_id" : 2,
"name" : "bob",
"age" : 42,
"type" : 1,
"status" : "A",
"finished" : [ 11, 25 ],
"badges" : [ "green" ]
}
{
"_id" : 3,
"name" : "ahn",
"age" : 22,
"type" : 2,
"status" : "A",
"finished" : [ 6 ],
"badges" : [ "blue", "red" ]
}
{
"_id" : 6,
"name" : "abc",
"age" : 43,
"type" : 1,
"status" : "A",
"finished" : [ 18, 12 ],
"badges" : [ "black", "blue" ]
}
With the exception of the _id field you cannot combine inclusion and exclusion statements in projection documents.
Return Specific Fields in Embedded Documents
Use the dot notation to return specific fields in an embedded document.
The following example specifies a projection to return: the _id field, name field, status field, and the foodfield inside the favorites document; the food field remains embedded in the favorites document.
db.users.find(
{ status: "A" },
{ name: 1, status: 1, "favorites.food": 1 }
)
The operation returns the following documents:
{ "_id" : 2, "name" : "bob", "status" : "A", "favorites" : { "food" : "meringue" } }
{ "_id" : 3, "name" : "ahn", "status" : "A", "favorites" : { "food" : "cake" } }
{ "_id" : 6, "name" : "abc", "status" : "A", "favorites" : { "food" : "pizza" } }
Suppress Specific Fields in Embedded Documents
Use dot notation to suppress specific fields of an embedded document using a 0 instead of 1.
The following example specifies a projection to exclude the food field inside the favorites document. All other fields are returned in the matching documents:
db.users.find(
{ status: "A" },
{ "favorites.food": 0 }
)
The operation returns the following document:
{
"_id" : 2,
"name" : "bob",
"age" : 42,
"type" : 1,
"status" : "A",
"favorites" : { "artist" : "Miro" },
"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" },
"finished" : [ 6 ],
"badges" : [ "blue", "red" ],
"points" : [ { "points" : 81, "bonus" : 8 }, { "points" : 55, "bonus" : 20 } ]
}
{
"_id" : 6,
"name" : "abc",
"age" : 43,
"type" : 1,
"status" : "A",
"favorites" : { "artist" : "Picasso" },
"finished" : [ 18, 12 ],
"badges" : [ "black", "blue" ],
"points" : [ { "points" : 78, "bonus" : 8 }, { "points" : 57, "bonus" : 7 } ]
}
Projection on Embedded Documents in an Array
Use dot notation to project specific fields inside documents embedded in an array.
The following example specifies a projection to return the name field, status field, and just the bonus field in the documents in the points array. The _id field is returned by default.
db.users.find( { status: "A" }, { name: 1, status: 1, "points.bonus": 1 } )
The operation returns the following documents:
{ "_id" : 2, "name" : "bob", "status" : "A", "points" : [ { "bonus" : 20 }, { "bonus" : 12 } ] }
{ "_id" : 3, "name" : "ahn", "status" : "A", "points" : [ { "bonus" : 8 }, { "bonus" : 20 } ] }
{ "_id" : 6, "name" : "abc", "status" : "A", "points" : [ { "bonus" : 8 }, { "bonus" : 7 } ] }
Project Specific Array Elements in the Returned Array
For fields that contain arrays, MongoDB provides the following projection operators: $elemMatch, $slice, and $.
The following example uses the $slice projection operator to return just the last element in the scores array.
db.users.find( { status: "A" }, { name: 1, status: 1, points: { $slice: -1 } } )
The operation returns the following documents:
{ "_id" : 2, "name" : "bob", "status" : "A", "points" : [ { "points" : 64, "bonus" : 12 } ] }
{ "_id" : 3, "name" : "ahn", "status" : "A", "points" : [ { "points" : 55, "bonus" : 20 } ] }
{ "_id" : 6, "name" : "abc", "status" : "A", "points" : [ { "points" : 57, "bonus" : 7 } ] }
$elemMatch, $slice, and $ are the only way to project specific elements to include in the returned array. For instance, you cannot project specific array elements using the array index; e.g. { "ratings.0": 1 } projection will not project the array with the first element.