Retrieve Data

Sample Data

The examples in this guide use the following Tea struct as a model for documents in the tea collection:

type Tea struct {
	Item        string    `bson:"item,omitempty"`
	Rating      int32     `bson:"rating,omitempty"`
	DateOrdered time.Time `bson:"date_ordered,omitempty"`
}

To run the examples in this guide, load these documents into the tea collection in the db database by using the following snippet:

coll := client.Database("db").Collection("tea")
docs := []interface{}{
	Tea{Item: "Masala", Rating: 10, DateOrdered: time.Date(2009, 11, 17, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Sencha", Rating: 7, DateOrdered: time.Date(2009, 11, 18, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Masala", Rating: 9, DateOrdered: time.Date(2009, 11, 12, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Masala", Rating: 8, DateOrdered: time.Date(2009, 12, 1, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Sencha", Rating: 10, DateOrdered: time.Date(2009, 12, 17, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Hibiscus", Rating: 4, DateOrdered: time.Date(2009, 12, 18, 0, 0, 0, 0, time.Local)},
}
result, err := coll.InsertMany(context.TODO(), docs)

Each document describes the tea variety a customer ordered, their rating, and the date of the order. These descriptions correspond to the item, rating, and date_ordered fields.

Find All Documents

The Find() method expects you to pass a Context type and a query filter. The method returns all documents that match the filter as a Cursor type.

For an example that uses the Find() method, see the Find Example section of this page. To learn how to access data by using a cursor, see the Access Data From a Cursor guide.

Find One Document

The FindOne() method expects you to pass a Context type and a query filter. The method returns the first document that matches the filter as a SingleResult type.

For an example that uses the FindOne() method, see the Find One Example section of this page. For an example that uses FindOne() and queries by using a specific ObjectId value, see the Find One by ObjectId Example section of this page.

To learn how to access data from a SingleResult type, see Unmarshalling in the BSON guide.

Modify Behavior

You can modify the behavior of Find() and FindOne() by passing in a FindOptions and FindOneOptions type respectively. If you don't specify any options, the driver uses the default values for each option.

You can configure the commonly used options in both types with the following methods:

filter := bson.D{
	{"$and",
		bson.A{
			bson.D{{"rating", bson.D{{"$gt", 5}}}},
			bson.D{{"rating", bson.D{{"$lt", 9}}}},
		}},
}
sort := bson.D{{"date_ordered", 1}}
opts := options.Find().SetSort(sort)
// Retrieves documents that match the filter and prints them as structs
cursor, err := coll.Find(context.TODO(), filter, opts)
if err != nil {
	panic(err)
}
var results []Tea
if err = cursor.All(context.TODO(), &results); err != nil {
	panic(err)
}
for _, result := range results {
	res, _ := bson.MarshalExtJSON(result, false, false)
	fmt.Println(string(res))
}

filter := bson.D{{"date_ordered", bson.D{{"$lte", time.Date(2009, 11, 30, 0, 0, 0, 0, time.Local)}}}}
opts := options.FindOne().SetSkip(2)
// Retrieves a document that matches the filter and prints it as
// a struct
var result Tea
err := coll.FindOne(context.TODO(), filter, opts).Decode(&result)
if err != nil {
	if err == mongo.ErrNoDocuments {
		fmt.Println("No documents found")
	} else {
		panic(err)
	}
}
res, _ := bson.MarshalExtJSON(result, false, false)
fmt.Println(string(res))

 {
     _id: ObjectId('65170b42b99efdd0b07d42de'),
     item: "Hibiscus",
     rating : 4,
     date_ordered : 2009-12-18T05:00:00.000+00:00
 }

id, err := primitive.ObjectIDFromHex("65170b42b99efdd0b07d42de")
if err != nil {
	panic(err)
}
//  Creates a filter to match a document that has the specified
//  "_id" value
filter := bson.D{{"_id", id}}
opts := options.FindOne().SetProjection(bson.D{{"item", 1}, {"rating", 1}})
// Retrieves a document that matches the filter and prints it as
// a struct
var result Tea
err = coll.FindOne(context.TODO(), filter, opts).Decode(&result)
if err != nil {
	if err == mongo.ErrNoDocuments {
		fmt.Println("No documents found")
	} else {
		panic(err)
	}
}
res, _ := bson.MarshalExtJSON(result, false, false)
fmt.Println(string(res))

Aggregation

The Aggregate() method expects you to pass a Context type and an aggregation pipeline. An aggregation pipeline defines how to transform data through stages. Some of the stages are matching documents, renaming fields, and grouping values.

The method returns the resulting documents in a Cursor type. If you omit the $match stage, the pipeline proceeds using all documents in the collection.

To learn how to access data in a cursor, see Access Data From a Cursor.

Modify Behavior

The Aggregate() method optionally takes an AggregateOptions type, which represents options you can use to modify its behavior. If you don't specify any options, the driver uses the default values for each option.

The AggregateOptions type allows you to configure options with the following methods:

groupStage := bson.D{
	{"$group", bson.D{
		{"_id", "$item"},
		{"average", bson.D{
			{"$avg", "$rating"},
		}},
	}}}
cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{groupStage})
if err != nil {
	panic(err)
}
// Prints the average "rating" for each item
var results []bson.M
if err = cursor.All(context.TODO(), &results); err != nil {
	panic(err)
}
for _, result := range results {
	fmt.Printf("%v had an average rating of %v \n", result["_id"], result["average"])
}

API Documentation

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

• FindOne()

• SingleResult

• Find()

• FindOptions

• FindOneOptions

• Cursor

• Aggregate()

• AggregateOptions