Docs Menu
Docs Home
/
MongoDB 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
  • Project Fields to Return from a Query with MongoDB Atlas
  • Additional Considerations

You can query embedded documents in MongoDB by using the following methods:

  • Your programming language's driver.

  • The MongoDB Atlas UI. To learn more, see Project Fields to Return from a Query with MongoDB Atlas.

  • MongoDB Compass.


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


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.

You can also specify embedded fields using the nested form. For example, { 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:

You can also specify embedded fields using the nested form. For example, { 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
}
]

The example in this section uses the sample movies dataset. To learn how to load the sample dataset into your MongoDB Atlas deployment, see Load Sample Data.

To project fields to return from a query in MongoDB Atlas, follow these steps:

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

2
  1. For the cluster that contains the sample data, click Browse Collections.

  2. In the left navigation pane, select the sample_mflix database.

  3. Select the movies collection.

3
  1. Click More Options on the right side of the Filter field.

  2. Specify the query filter.

    Specify the query filter document in the Filter field. A query filter document uses query operators to specify search conditions.

    Copy the following query filter document into the Filter search bar:

    { year: 1924 }
4

Specify the field(s) to return in the query results.

Copy the following project document into the Project bar:

{ title: 1, plot: 1 }
5

This query filter returns the following fields for all documents in the sample_mflix.movies collection where the year field matches 1924:

  • _id

  • title

  • plot

MongoDB Atlas returns the _id field by default. To omit the _id field, copy the following project document into the Project bar and click Apply:

{ title: 1, plot: 1, _id: 0 }

MongoDB enforces additional restrictions with regards to projections. See Projection Restrictions for details.

Tip

See also:

← Query an Array of Embedded Documents