Docs Menu
Docs Home
/ / /
C#/.NET
/

Aggregation

On this page

  • Overview
  • Analogy
  • Compare Aggregation and Find Operations
  • Server Limitations
  • Aggregation Example
  • LINQ Approach
  • Builders Approach
  • BsonDocument Approach
  • Additional Information
  • MongoDB Server Manual
  • API Documentation

In this guide, you can learn how to use the MongoDB .NET/C# Driver to perform aggregation operations.

Aggregation operations process data in your MongoDB collections and return computed results. The MongoDB Aggregation framework is modeled on the concept of data processing pipelines. Documents enter a pipeline comprised of one or more stages, and this pipeline transforms the documents into an aggregated result.

Aggregation operations function similarly to car factories with assembly lines. The assembly lines have stations with specialized tools to perform specific tasks. For example, when building a car, the assembly line begins with the frame. Then, as the car frame moves through the assembly line, each station assembles a separate part. The result is a transformed final product, the finished car.

The assembly line represents the aggregation pipeline, the individual stations represent the aggregation stages, the specialized tools represent the expression operators, and the finished product represents the aggregated result.

The following table lists the different tasks you can perform with find operations, compared to what you can achieve with aggregation operations. The aggregation framework provides expanded functionality that allows you to transform and manipulate your data.

Find Operations
Aggregation Operations
Select certain documents to return
Select which fields to return
Sort the results
Limit the results
Count the results
Select certain documents to return
Select which fields to return
Sort the results
Limit the results
Count the results
Group the results
Rename fields
Compute new fields
Summarize data
Connect and merge data sets

Consider the following limitations when performing aggregation operations:

  • Returned documents must not violate the BSON document size limit of 16 megabytes.

  • Pipeline stages have a memory limit of 100 megabytes by default. If required, you can exceed this limit by setting the AllowDiskUse property of the AggregateOptions object that you pass to the Aggregate() method.

  • The $graphLookup stage has a strict memory limit of 100 megabytes and ignores the AllowDiskUse property.

To perform an aggregation, pass a list of aggregation stages to the IMongoCollection<TDocument>.Aggregate() method.

Note

This example uses the sample_restaurants.restaurants collection from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see Quick Start.

The following code example produces a count of the number of bakeries in each borough of New York City. To do so, it uses an aggregation pipeline that contains the following stages:

  • A $match stage to filter for documents whose cuisine field contains the value "Bakery".

  • A $group stage to group the matching documents by the borough field, accumulating a count of documents for each distinct value of that field.

The following sections implement this example by using LINQ, Builders, and BsonDocument approaches to create and combine the aggregation stages used in the example pipeline.

// Defines a queryable collection object as a prerequisite to using LINQ
var queryableCollection = collection.AsQueryable();
// Defines the query with $match and $group stages
var query = queryableCollection
.Where(r => r.Cuisine == "Bakery")
.GroupBy(r => r.Borough)
.Select(g => new { _id = g.Key, Count = g.Count() });
// Executes the query and prints the aggregated results
foreach (var result in query.ToList())
{
Console.WriteLine(result);
}
{ _id = Bronx, Count = 71 }
{ _id = Brooklyn, Count = 173 }
{ _id = Staten Island, Count = 20 }
{ _id = Missing, Count = 2 }
{ _id = Manhattan, Count = 221 }
{ _id = Queens, Count = 204 }

To learn more about using LINQ to construct aggregation pipelines, see the LINQ guide.

// Defines the $match aggregation stage
var matchFilter = Builders<Restaurant>.Filter.Eq(r => r.Cuisine, "Bakery");
// Defines the aggregation pipeline with the $match and $group aggregation stages
var pipeline = new EmptyPipelineDefinition<Restaurant>()
.Match(matchFilter)
.Group(r => r.Borough,
g => new
{
_id = g.Key,
Count = g.Count()
}
);
// Executes the aggregation pipeline
var results = collection.Aggregate(pipeline).ToList();
// Prints the aggregated results
foreach (var result in results)
{
Console.WriteLine(result);
}
{ _id = Bronx, Count = 71 }
{ _id = Brooklyn, Count = 173 }
{ _id = Staten Island, Count = 20 }
{ _id = Missing, Count = 2 }
{ _id = Manhattan, Count = 221 }
{ _id = Queens, Count = 204 }

To learn more about using builders to construct aggregation pipelines, see the Build an Aggregation Pipeline section of the Operations with Builders guide.

// Defines the $match and $group aggregation stages
var matchStage = new BsonDocument
{
{
"$match",
new BsonDocument
{
{ "cuisine", "Bakery" }
}
}
};
var groupStage = new BsonDocument
{
{
"$group",
new BsonDocument
{
{ "_id", "$borough" },
{ "count", new BsonDocument("$sum", 1) }
}
}
};
// Executes the aggregation pipeline
var pipeline = new[] { matchStage, groupStage };
var results = collection.Aggregate<BsonDocument>(pipeline).ToList();
// Prints the aggregated results
foreach (BsonDocument result in results)
{
Console.WriteLine(result);
}
{ "_id" : "Brooklyn", "count" : 173 }
{ "_id" : "Manhattan", "count" : 221 }
{ "_id" : "Bronx", "count" : 71 }
{ "_id" : "Missing", "count" : 2 }
{ "_id" : "Staten Island", "count" : 20 }
{ "_id" : "Queens", "count" : 204 }

To view a full list of expression operators, see Aggregation Operators.

To learn more about assembling an aggregation pipeline and view examples, see Aggregation Pipeline.

To learn more about creating pipeline stages, see Aggregation Stages.

To learn about explaining MongoDB aggregation operations, see Explain Results and Query Plans.

For more information about the aggregation operations discussed in this guide, see the following API documentation:

Back

Enterprise Authentication Mechanisms