Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Docs Menu
Docs Home
/ /
Aggregation Stages
Docs Home
/
Development
/
Query Language
/
Aggregation Stages
Docs Home
/
Development
/
Query Language
/
Aggregation Stages

$count (aggregation stage)

Definition

$count

Passes a document to the next stage that contains a count of the number of documents input to the stage.

Note

Disambiguation

This page describes the $count aggregation pipeline stage. For the $count aggregation accumulator, see $count (aggregation accumulator).

Compatibility

You can use $count for deployments hosted in the following environments:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Syntax

$count has the following syntax:

{ $count: <string> }

<string> is the name of the output field which has the count as its value. <string> must be a non-empty string, must not start with $ and must not contain the . character.

Behavior

The return type is represented by the smallest type that can store the final value of count: integer → long → double

The $count stage is equivalent to the following $group and $project sequence:

db.collection.aggregate( [
   { $group: { _id: null, myCount: { $sum: 1 } } },
   { $project: { _id: 0 } }
] )

myCount is the output field that stores the count. You can specify another name for the output field.

If the input dataset is empty, $count doesn't return a result.

Tip

db.collection.countDocuments() wraps the $group aggregation stage with a $sum expression.

Examples

The examples on this page use data from the sample_mflix sample dataset. For details on how to load this dataset into your self-managed MongoDB deployment, see Load the sample dataset. If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

The following aggregation operation has two stages:

  1. The $match stage filters for documents where metacritic equals 100 to pass along only those documents to the next stage.

  2. The $count stage returns a count of the remaining documents in the aggregation pipeline and assigns the value to a field called perfect_score_count.

db.movies.aggregate( [
   { $match: { metacritic: { $eq: 100 } } },
   { $count: "perfect_score_count" }
] )
[ { perfect_score_count: 8 } ]

The C# examples on this page use the sample_mflix database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see Get Started in the MongoDB .NET/C# Driver documentation.

The following Movie class models the documents in the sample_mflix.movies collection:

[BsonIgnoreExtraElements]
public class Movie
{
    [BsonId]
    public ObjectId Id { get; set; }
    public string Title { get; set; } = null!;
    [BsonElement("metacritic")]
    public int Metacritic { get; set; }
}

To use the MongoDB .NET/C# driver to add a $count stage to an aggregation pipeline, call the Count() method on a PipelineDefinition object.

The following example creates a pipeline stage that returns a count of all documents in the movies collection where the metacritic field has the value 100:

var pipeline = new EmptyPipelineDefinition<Movie>()
    .Match(Builders<Movie>.Filter.Eq(m => m.Metacritic, 100))
    .Count();

The Node.js examples on this page use the sample_mflix database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see Get Started in the MongoDB Node.js driver documentation.

To use the MongoDB Node.js driver to add a $count stage to an aggregation pipeline, use the $count operator in a pipeline object.

The following example creates a pipeline stage that counts the number of input documents from the sample_mflix.movies collection and returns a document containing the count. The example then runs the aggregation pipeline:

const pipeline = [{ $count: "movies" }];
const cursor = collection.aggregate(pipeline);
return cursor;

Learn More

Back

$collStats

Next

$currentOp

On this page