MongoDB Stages

What Are MongoDB Stages?

MongoDB aggregation stages are the steps in a pipeline. Each stage starts with $ and does one job: filter, reshape, group, sort, join, or write results.

You pass an ordered array of stages to db.collection.aggregate([ ... ]). Documents flow through each stage in order—like an assembly line for analytics and reports.

Stage = one pipeline step that starts with $

Examples:
  $match   → filter documents
  $project → reshape fields
  $group   → summarize with accumulators
  $lookup  → join another collection

Browse every tutorial in the left sidebar.

How MongoDB Stages Work

A pipeline is an array. MongoDB runs stage 1 on the collection, feeds its output into stage 2, and so on until the final result cursor.

1. Start from a collection with aggregate([ ... ]).
2. Add stages in the order you want work done.
3. Each stage transforms the document stream and passes it forward.
4. Read the final cursor (or write with $out / $merge).

// Filter → group → sort
db.orders.aggregate([
  { $match: { status: "completed" } },
  { $group: { _id: "$storeId", revenue: { $sum: "$amount" } } },
  { $sort: { revenue: -1 } }
])

// Add a computed field without dropping others
db.orders.aggregate([
  { $addFields: { total: { $multiply: ["$qty", "$price"] } } }
])

How It Works

1. $match. Keeps only completed orders.
2. $group. Totals amount per storeId.
3. $sort. Highest revenue first.
4. $addFields. Adds total while keeping existing fields.

MongoDB Stage Syntax

Almost every stage uses the { $stageName: <spec> } form inside an aggregation array. The $ prefix marks a reserved stage name.

db.collection.aggregate([
  { $stageName: <specification> },
  { $anotherStage: <specification> }
])

// Field path inside expressions:
"$fieldName"  → value of that field on the current document

{ $match: { city: "Chennai" } }

{ $project: { name: 1, total: { $add: ["$a", "$b"] } } }

{ $group: { _id: "$cat", n: { $sum: 1 } } }

{ $lookup: { from: "users", localField: "userId", foreignField: "_id", as: "user" } }

Pseudocode

Use this mental model before you build a pipeline.

goal = report / join / reshape / write results

stream = all documents in collection

for each stage in pipeline (in order):
    if stage is $match:
        stream = keep only matching docs
    else if stage is $project / $addFields:
        stream = reshape each document
    else if stage is $group:
        stream = one doc per bucket + accumulators
    else if stage is $sort / $limit:
        stream = ordered / trimmed stream
    else:
        stream = apply that stage's rule

return stream

How It Works

1. Start from the goal, not from a random stage name.
2. Filter early, then reshape or group, then sort/limit for the final view.
3. Each stage only sees what the previous stage emitted.

Stage Categories

Major families below. The left sidebar lists every tutorial—this section only explains when each family is useful.

For rollups inside $group, see the accumulators hub. For per-document expressions, see the operators hub.

Common MongoDB Stages

A short starter set. Open any name for a full tutorial; use the sidebar for the complete catalog.

Worked Example

Small orders collection. We filter completed orders, group by store, then sort by revenue.

db.orders.insertMany([
  { _id: 1, storeId: "A", amount: 40, status: "completed" },
  { _id: 2, storeId: "A", amount: 60, status: "completed" },
  { _id: 3, storeId: "B", amount: 25, status: "completed" },
  { _id: 4, storeId: "A", amount: 15, status: "cancelled" }
]);

[
  { _id: 1, storeId: "A", amount: 40, status: "completed" },
  { _id: 2, storeId: "A", amount: 60, status: "completed" },
  { _id: 3, storeId: "B", amount: 25, status: "completed" },
  { _id: 4, storeId: "A", amount: 15, status: "cancelled" }
]

db.orders.aggregate([
  { $match: { status: "completed" } },
  {
    $group: {
      _id: "$storeId",
      revenue: { $sum: "$amount" },
      orders:  { $sum: 1 }
    }
  },
  { $sort: { revenue: -1 } }
]);

[
  { _id: "A", revenue: 100, orders: 2 },
  { _id: "B", revenue: 25, orders: 1 }
]

Choosing the Right Stage

Match the job to the family first; then pick a specific stage.

Performance Notes

Use explain() when a pipeline feels slow. Prefer selective filters and smaller working sets over rearranging stages without a clear reason.

Key Takeaways