Specify Which Fields to Return

On this page

Overview

Sample Data
Projection
Exclude a Field
Include a Field
Aggregation
Additional Information
API Documentation

Overview

In this guide, you can learn how to specify which fields to return in a document from read operations.

Sample Data

To run the examples in this guide, load these documents into the tea.ratings collection with the following snippet:

coll := client.Database("tea").Collection("ratings")
docs := []interface{}{
	bson.D{{"type", "Masala"}, {"rating", 10}},
	bson.D{{"type", "Assam"}, {"rating", 5}},
	bson.D{{"type", "Oolong"}, {"rating", 7}},
	bson.D{{"type", "Earl Grey"}, {"rating", 8}},
	bson.D{{"type", "English Breakfast"}, {"rating", 5}},
}
result, err := coll.InsertMany(context.TODO(), docs)
if err != nil {
	panic(err)
}
fmt.Printf("Number of documents inserted: %d\n", len(result.InsertedIDs))

Tip

Non-existent Databases and Collections

If the necessary database and collection don't exist when you perform a write operation, the server implicitly creates them.

Each document contains a rating for a type of tea that corresponds to the type and rating fields.

Note

Each example truncates the ObjectID value because the driver generates them uniquely.

Projection

A projection specifies which fields to return in matched documents. It contains field names followed by a 1 (to include) or 0 (to exclude). Projections can only include or exclude fields.

You can specify a projection by passing one to the SetProjection() method in the options of the following read operation methods:

Find()
FindOne()
FindOneAndDelete()
FindOneAndReplace()
FindOneAndUpdate()

Tip

If you don't specify a projection, the read operation returns all the fields in matched documents.

Exclude a Field

To exclude a field, pass the field you want to exclude and a 0 to the SetProjection() method. For all fields you don't explicitly list in the projection, the driver includes them.

Example

The following example excludes the rating from the matched documents from the Find() method:

opts := options.Find().SetProjection(bson.D{{"rating", 0}})
cursor, err := coll.Find(context.TODO(), bson.D{}, opts)
if err != nil {
   panic(err)
}
var results []bson.D
if err = cursor.All(context.TODO(), &results); err != nil {
   panic(err)
}
for _, result := range results {
   fmt.Println(result)
}

Include a Field

To include a field, pass the field you want to include and a 1 to the SetProjection() method. For all fields you don't explicitly list in the projection, the driver excludes them.

Important

You can exclude the _id field even if you specified to include certain fields. By default, the driver includes the _id field. You must explicitly exclude the _id field if you do not want it returned.

Example

The following example performs the following projection on the matched documents from the Find() method:

Include the type and rating field
Exclude the _id field

opts := options.Find().SetProjection(bson.D{{"type", 1}, {"rating", 1}, {"_id", 0}})
cursor, err := coll.Find(context.TODO(), bson.D{}, opts)
if err != nil {
   panic(err)
}
var results []bson.D
if err = cursor.All(context.TODO(), &results); err != nil {
   panic(err)
}
for _, result := range results {
   fmt.Println(result)
}

Aggregation

You can also include the $project stage to specify a projection in an aggregation pipeline.

Example

The following example performs the following projection on the matched documents from the Aggregate() method:

Include the type and rating field
Exclude the _id field

projectStage := bson.D{{"$project", bson.D{{"type", 1}, {"rating", 1}, {"_id", 0}}}}
cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{projectStage})
if err != nil {
   panic(err)
}
var results []bson.D
if err = cursor.All(context.TODO(), &results); err != nil {
   panic(err)
}
for _, result := range results {
   fmt.Println(result)
}

Additional Information

To learn more about the operations mentioned, see the following guides:

To learn about projecting text scores from your text search, see Search Text.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API Documentation:

← Limit the Number of Returned Results Search Text →