Count Documents

On this page

Overview

Accurate Count
Aggregation
Estimated Count
Additional Information

Overview

In this guide, you can learn how to get an accurate and estimated count of the number of documents in your collection.

Sample Data

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

type Tea struct {
	Type   string
	Rating int32
}

To run the examples in this guide, load the sample data into the tea collection in the db database with the following snippet:

coll := client.Database("db").Collection("tea")
docs := []interface{}{
	Tea{Type: "Masala", Rating: 10},
	Tea{Type: "Matcha", Rating: 7},
	Tea{Type: "Assam", Rating: 4},
	Tea{Type: "Oolong", Rating: 9},
	Tea{Type: "Chrysanthemum", Rating: 5},
	Tea{Type: "Earl Grey", Rating: 8},
	Tea{Type: "Jasmine", Rating: 3},
	Tea{Type: "English Breakfast", Rating: 6},
	Tea{Type: "White Peony", Rating: 4},
}
result, err := coll.InsertMany(context.TODO(), docs)

Tip

Nonexistent 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 describes a tea type and its rating. These items correspond to the type and rating fields.

Accurate Count

To count the number of documents that match your query filter, use the CountDocuments() method. If you pass an empty query filter, this method returns the total number of documents in the collection.

Tip

When you use CountDocuments() to return the total number of documents in a collection, MongoDB performs a collection scan. You can avoid a collection scan and improve the performance of this method by using a hint to take advantage of the built-in index on the _id field. Use this technique only when calling CountDocuments() with an empty query parameter.

opts := options.Count().SetHint("_id_")
count, err := coll.CountDocuments(context.TODO(), bson.D{}, opts)
if err != nil {
     panic(err)
}

Modify Behavior

You can modify the behavior of CountDocuments() by passing in a CountOptions type. If you don't specify any options, the driver uses its default values.

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

Method	Description
`SetCollation()`	The type of language collation to use when sorting results. Default: `nil`
`SetHint()`	The index to use to scan for documents to count. Default: `nil`
`SetLimit()`	The maximum number of documents to count. Default: `0`
`SetMaxTime()`	The maximum amount of time that the query can run on the server. Default: `nil`
`SetSkip()`	The number of documents to skip before counting. Default: `0`

Example

The following example counts the number of documents where the rating is less than 6:

filter := bson.D{{"rating", bson.D{{"$lt", 6}}}}
count, err := coll.CountDocuments(context.TODO(), filter)
if err != nil {
    panic(err)
}
fmt.Printf("Number of documents with a rating less than six: %d\n", count)

Number of documents with a rating less than six: 4

Aggregation

You can also include the $count stage to count the number of documents in an aggregation pipeline.

Example

The following example performs the following actions:

Counts the number of documents in which the value of the rating field is greater than 5
Assigns the count to the counted_documents field

matchStage := bson.D{{"$match", bson.D{{"rating", bson.D{{"$gt", 5}}}}}}
countStage := bson.D{{"$count", "counted_documents"}}
cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{matchStage, countStage})
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)
}

[{counted_documents 5}]

Estimated Count

To estimate the number of documents in your collection, use the EstimatedDocumentCount() method.

Note

The EstimatedDocumentCount() method is quicker than the CountDocuments() method because it uses the collection's metadata rather than scanning the entire collection.

Modify Behavior

You can modify the behavior of EstimatedDocumentCount() by passing in an EstimatedDocumentCountOptions type. If you don't specify any options, the driver uses its default values.

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

Method	Description
`SetMaxTime()`	The maximum amount of time that the query can run on the server. Default: `nil`

Example

The following example estimates the number of documents in the tea collection:

count, err := coll.EstimatedDocumentCount(context.TODO())
if err != nil {
   panic(err)
}
fmt.Printf("Estimated number of documents in the tea collection: %d\n", count)

Estimated number of documents in the tea collection: 9

Additional Information

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

API Documentation

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

Back

Specify a Query

Retrieve Data