Docs Menu

Specify Which Fields to Return

On this page

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

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

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

The server implicitly creates the necessary database and collection when you perform a write operation against them if they don't already exist.

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.

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.

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.

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)
}

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.

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)
}

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

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)
}

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

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

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

←  Limit the Number of Returned ResultsSearch Text →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.