Mongoose aggregation pipelines let you transform MongoDB documents into focused API responses, reports, dashboards, and operational summaries. This guide provides a reusable checklist for choosing stages, composing expressions, adding facets and joins, inspecting pipeline results, and diagnosing the type, ordering, and shape errors that commonly make an aggregation difficult to trust.
Overview
A MongoDB aggregation pipeline is an ordered array of stages. Each stage receives the documents produced by the previous stage and returns a new stream of documents. Mongoose exposes this capability through Model.aggregate():
const pipeline = [
{ $match: { status: 'paid' } },
{ $group: { _id: '$customerId', total: { $sum: '$amount' } } },
{ $sort: { total: -1 } }
];
const results = await Order.aggregate(pipeline);
Unlike a normal document query, an aggregation result does not have to match the model's schema. It may contain grouped records, calculated fields, nested arrays, or a completely new shape. Treat the pipeline's output as a deliberate data contract for the endpoint, job, or report that consumes it.
A dependable workflow starts with a small question: what should one output document represent? For example, one output document might represent one customer, one day, one product category, or one page of search results. Once that grain is clear, choose the stages that move source documents toward it.
MongoDB aggregation stages at a glance
| Stage | Typical purpose | Checklist question |
|---|---|---|
$match | Filter source documents | Can this filter run early and use an appropriate index? |
$project or $set | Select, rename, or calculate fields | Which fields are required by later stages? |
$unwind | Turn array elements into documents | What should happen when the array is empty? |
$group | Aggregate by a key | What does one grouped result represent? |
$lookup | Join related collections | Are the local and foreign fields the same type? |
$sort | Order results | Is the ordering stable when values tie? |
$skip and $limit | Offset-based pagination | Is the sort applied before pagination? |
$facet | Run multiple result branches | Can one database request provide both rows and metadata? |
Checklist by scenario
Filtering and shaping an API response
- Define the request filters and normalize input before constructing the pipeline.
- Place a selective
$matchnear the beginning when later stages do not need the excluded documents. - Use
$projectto return only fields required by the response contract. - Use
$setor$addFieldsfor calculated values, and give calculated fields names that explain their meaning. - Add a deterministic
$sortbefore$skipand$limit. Include a tie-breaker such as a unique identifier when equal sort values are possible.
const pipeline = [
{ $match: { tenantId, status: 'active' } },
{ $project: { name: 1, updatedAt: 1, score: 1 } },
{ $sort: { updatedAt: -1, _id: 1 } },
{ $skip: offset },
{ $limit: pageSize }
];
Grouping for totals and reports
- Decide whether missing or null values belong in a group or should be filtered out.
- Convert values to the intended numeric or date type before calculating totals.
- Use accumulator expressions such as
$sum,$avg,$min,$max, or$pushaccording to the report's needs. - Follow
$groupwith a projection that makes the result readable, especially when the group key is stored in_id.
const pipeline = [
{ $match: { createdAt: { $gte: start, $lt: end } } },
{
$group: {
_id: '$category',
orderCount: { $sum: 1 },
revenue: { $sum: '$total' }
}
},
{ $project: { _id: 0, category: '$_id', orderCount: 1, revenue: 1 } },
{ $sort: { revenue: -1 } }
];
Joining related data with $lookup
Use $lookup when the response needs fields from another collection. Verify the collection name and the exact field types first. A string identifier in one collection will not necessarily match an ObjectId in another. If the join returns an array but the endpoint expects one related record, decide whether to use $unwind, preserve missing relationships, or keep the array.
const pipeline = [
{ $match: { status: 'open' } },
{
$lookup: {
from: 'users',
localField: 'assigneeId',
foreignField: '_id',
as: 'assignee'
}
},
{ $unwind: { path: '$assignee', preserveNullAndEmptyArrays: true } },
{ $project: { title: 1, 'assignee.name': 1 } }
];
Combining rows and counts with $facet
A facet can produce multiple outputs from the same filtered input. This is useful for a paginated endpoint that needs both page rows and a count, or for a report that returns several summaries together.
const pipeline = [
{ $match: { tenantId, status: 'active' } },
{
$facet: {
rows: [
{ $sort: { createdAt: -1, _id: 1 } },
{ $skip: offset },
{ $limit: pageSize }
],
metadata: [
{ $count: 'total' }
]
}
}
];
What to double-check
Types and casting
Do not assume every value inside an aggregation pipeline will be cast exactly as it would be in a standard Mongoose query. Make identifier types explicit when constructing the pipeline, particularly for $match, $lookup, and expression comparisons. If a route receives an identifier as text, validate it and convert it to the intended MongoDB type before use.
Stage order
Stage order changes both meaning and cost. Filtering before grouping usually avoids unnecessary work. Projecting away a field before a later stage needs it causes missing values. Sorting after limiting sorts only the limited subset, not the complete result set. Write down the document shape after each major stage when a pipeline becomes difficult to reason about.
Expressions and null behavior
Expressions such as $add, $cond, $ifNull, $map, and $dateToString operate on values that may be absent, null, or of an unexpected type. Decide how those cases should behave. A report should not silently turn missing amounts into misleading totals, and a date grouping should use an explicitly chosen timezone when that distinction matters to the business result.
Result shape
Inspect the actual result rather than relying on the source schema. Aggregation commonly returns plain JavaScript objects with renamed fields and computed values. Define a response type or serializer for important endpoints so that a future pipeline change does not accidentally expose internal fields or break clients.
Common mistakes
- Filtering after an expanding stage: Running
$unwindor$lookupbefore a filter can create more intermediate documents than necessary. Move safe filters earlier where the logic permits. - Paginating without a stable sort: Without an explicit and deterministic order, records can appear on more than one page or be skipped between requests.
- Using the wrong collection name: The
fromvalue in$lookuprefers to the MongoDB collection, not necessarily the Mongoose model name. Confirm it from the deployed schema and database conventions. - Confusing field paths with literal values: In expressions,
'$amount'refers to a field path, while'amount'is a literal string. Review every expression where a value is compared or calculated. - Debugging the whole pipeline at once: Temporarily run the first stage, then add one stage at a time. Return a small sample with a projection to see precisely where the shape changes.
- Skipping tests for empty data: Test no matches, missing relationships, null fields, duplicate sort values, and boundary dates alongside the normal case.
For repeatable verification, keep representative fixtures and integration tests around important pipelines. The Mongoose testing guide covers fixtures, database cleanup, and test structure. When an aggregation fails because of a cast, validation boundary, or database operation, the Mongoose error handling guide can help separate application errors from query construction errors.
When to revisit
Revisit an aggregation pipeline whenever its inputs, output contract, or operational context changes. Before a seasonal planning or reporting cycle, test the date boundaries, expected volume, null cases, and index assumptions with representative data. When a workflow or tool changes, confirm that the installed Mongoose and MongoDB versions still support the stages and expressions the pipeline uses, and recheck any behavior your application depends on.
Use this short review checklist before shipping a change:
- State what one output document represents.
- Validate incoming identifiers, dates, enums, and numeric limits.
- Inspect the shape after
$match,$lookup,$unwind, and$group. - Confirm field types, collection names, null handling, and timezone assumptions.
- Apply stable sorting before pagination and test boundary pages.
- Compare the result with fixtures that include empty, missing, and unusual values.
- Review performance with the data volume and indexes expected in the target environment.
Keep the pipeline readable by building it from named stages or small helper functions when it has several optional branches. If its behavior is part of a critical report or API, document the intended result shape next to the code. For surrounding concerns such as connection limits, graceful shutdown, schema design, middleware, or migrations, consult the relevant Mongoose guides in your project documentation. A pipeline is easier to maintain when its query logic, data contract, and operational assumptions are reviewed together.