Specify Which Fields to Return

Overview

Use a projection to control which fields appear in the documents returned by read operations. Many requests only require certain fields, so projections can help you limit unnecessary network bandwidth usage. Projections work in two ways:

• Explicitly include fields with a value of 1. This has the side-effect of implicitly excluding all unspecified fields.

• Implicitly exclude fields with a value of 0. This has the side-effect of implicitly including all unspecified fields.

These two methods of projection are mutually exclusive: if you explicitly include fields, you cannot explicitly exclude fields, and vice versa.

const myDB = client.db("myDB");
const myColl = myDB.collection("fruits");
await myColl.insertMany([
  { "_id": 1, "name": "apples", "qty": 5, "rating": 3 },
  { "_id": 2, "name": "bananas", "qty": 7, "rating": 1 },
  { "_id": 3, "name": "oranges", "qty": 6, "rating": 2 },
  { "_id": 4, "name": "avocados", "qty": 3, "rating": 5 },
]);

Single Field

In the following query, pass the projection to only return the name field of each document:

// return only* the name field
const projection = { name: 1 };
const cursor = myColl.find().project(projection);
for await (const doc of cursor) {
  console.dir(doc);
}

The projection document specifies a value of 1 for name. This instructs the operation to include the name field of each returned document in the results and exclude the qty and rating fields. Passing this projection to find() with an empty query document and no sort document yields the following results:

{ "_id": 1, "name": "apples" }
{ "_id": 2, "name": "bananas" }
{ "_id": 3, "name": "oranges" }
{ "_id": 4, "name": "avocados" }

Despite the fact that this projection only explicitly included the name field, the query returned the _id field as well!

This happens because the _id field is a special case: it is always included in every query unless explicitly specified otherwise. That's because _id is a unique identifier for each document, a property that can be very useful when constructing queries. The movies collection is a good example of why this property is useful: because remakes and even separate works can sometimes reuse movie titles, you need a unique _id value to refer to any specific movie. _id is the only exception to the mutually exclusive include-exclude behavior in projections: you can explicitly exclude _id even when explicitly including other fields if you do not want _id to be present in returned documents.

// return only the name field
const projection = { _id: 0, name: 1 };
const cursor = myColl.find().project(projection);
for await (const doc of cursor) {
  console.dir(doc);
}

The projection document specifies a value of 1 for name and 0 for _id. This instructs the operation to include the name field of each returned document in the results and exclude the _id, qty, and rating fields. Passing this projection to find() with an empty query document and no sort document yields the following results:

{ "name": "apples" }
{ "name": "bananas" }
{ "name": "oranges" }
{ "name": "avocados" }

Multiple Fields

You can also specify multiple fields to include in your projection. Note: the order in which you specify the fields in the projection does not alter the order in which they are returned.

const projection = { _id: 0, rating: 1, name: 1 };
const cursor = myColl.find().project(projection);
for await (const doc of cursor) {
  console.dir(doc);
}

This example that identifies two fields to include in the projection yields the following results:

  { "name": "apples", "rating": 3 }
  { "name": "bananas", "rating": 1 }
  { "name": "oranges", "rating": 2 }
  { "name": "avocados", "rating": 5 }

For additional projection examples, see the MongoDB Manual page on Project Fields to Return from Query.