- MongoDB CRUD Operations >
- Query Documents >
- Project Fields to Return from Query
Project Fields to Return from Query¶
On this page
- Projection Document
- Example Collection
- Return All Fields in Matching Documents
- Return the Specified Fields and the
_id
Field Only - Return Specified Fields Only
- Return All But the Excluded Field
- Return Specific Fields in Embedded Documents
- Suppress Specific Fields in Embedded Documents
- Projection on Embedded Documents in an Array
- Project Specific Array Elements in the Returned Array
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:
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.
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 [1] 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.
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"
:
The matching documents includes all their fields:
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.
The operation returns the following documents:
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:
In the result set, only the name
and status
fields return in
the matching documents:
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:
In the result set, the favorites
and the points
fields do not
return in the matching documents:
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 food
field inside
the favorites
document; the food
field remains embedded in the
favorites
document.
The operation returns the following documents:
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:
The operation returns the following document:
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.
The operation returns the following documents:
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.
The operation returns the following documents:
$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.
See also
[1] | 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. |