Docs Menu

Docs HomeMongoDB Manual

Project Fields to Return from Query

On this page

  • Return All Fields in Matching Documents
  • Return the Specified Fields and the _id Field Only
  • Suppress _id Field
  • Return All But the Excluded Fields
  • 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
  • Project Fields with Aggregation Expressions
  • Additional Considerations

Use the Select your language drop-down menu in the upper-right to set the language of the following examples.


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 to specify or restrict fields to return.

The following example returns all fields from all documents in the inventory collection where the status equals "A":

The operation corresponds to the following SQL statement:

SELECT * from inventory WHERE status = "A"

A projection can explicitly include several fields by setting the <field> to 1 in the projection document. The following operation returns all documents that match the query. In the result set, only the item, status and, by default, the _id fields return in the matching documents.

The operation corresponds to the following SQL statement:

SELECT _id, item, status from inventory WHERE status = "A"

You can remove the _id field from the results by setting it to 0 in the projection, as in the following example:

The operation corresponds to the following SQL statement:

SELECT item, status from inventory WHERE status = "A"

Note

With the exception of the _id field, you cannot combine inclusion and exclusion statements in projection documents.

Instead of listing the fields to return in the matching document, you can use a projection to exclude specific fields. The following example which returns all fields except for the status and the instock fields in the matching documents:

Note

With the exception of the _id field, you cannot combine inclusion and exclusion statements in projection documents.

You can return specific fields in an embedded document. Use the dot notation to refer to the embedded field and set to 1 in the projection document.

The following example returns:

  • The _id field (returned by default),

  • The item field,

  • The status field,

  • The uom field in the size document.

The uom field remains embedded in the size document.

Starting in MongoDB 4.4, you can also specify embedded fields using the nested form, e.g. { item: 1, status: 1, size: { uom: 1 } }.

You can suppress specific fields in an embedded document. Use the dot notation to refer to the embedded field in the projection document and set to 0.

The following example specifies a projection to exclude the uom field inside the size document. All other fields are returned in the matching documents:

Starting in MongoDB 4.4, you can also specify embedded fields using the nested form, e.g. { size: { uom: 0 } }.

Use dot notation to project specific fields inside documents embedded in an array.

The following example specifies a projection to return:

  • The _id field (returned by default),

  • The item field,

  • The status field,

  • The qty field in the documents embedded in the instock array.

You can specify aggregation expressions in a query projection. Aggregation expressions let you project new fields and modify the values of existing fields.

For example, the following operation uses aggregation expressions to override the value of the status field, and project new fields area and reportNumber.

Note

The following example uses MongoDB Shell syntax. For driver examples of projection with aggregation, see your driver documentation.

db.inventory.find(
{ },
{
_id: 0,
item: 1,
status: {
$switch: {
branches: [
{
case: { $eq: [ "$status", "A" ] },
then: "Available"
},
{
case: { $eq: [ "$status", "D" ] },
then: "Discontinued"
},
],
default: "No status found"
}
},
area: {
$concat: [
{ $toString: { $multiply: [ "$size.h", "$size.w" ] } },
" ",
"$size.uom"
]
},
reportNumber: { $literal: 1 }
}
)
[
{
item: 'journal',
status: 'Available',
area: '294 cm',
reportNumber: 1
},
{
item: 'planner',
status: 'Discontinued',
area: '685.5 cm',
reportNumber: 1
},
{
item: 'notebook',
status: 'Available',
area: '93.5 in',
reportNumber: 1
},
{
item: 'paper',
status: 'Discontinued',
area: '93.5 in',
reportNumber: 1
},
{
item: 'postcard',
status: 'Available',
area: '152.5 cm',
reportNumber: 1
}
]

Starting in MongoDB 4.4, MongoDB enforces additional restrictions with regards to projections. See Projection Restrictions for details.

Tip

See also:

←  Query an Array of Embedded DocumentsQuery for Null or Missing Fields →