MongoDB Accumulators

What Are MongoDB Accumulators?

MongoDB accumulators are operators that compute one result per group. They live mainly inside the $group stage and roll many documents into totals, averages, arrays, or ranked picks.

You use accumulators to sum, average, collect, rank, and merge values across documents that share the same group key. Expression operators (like $add) work on one document at a time; accumulators work across a whole bucket.

Accumulator = rollup inside $group

Examples:
  $sum      → total (or count with $sum: 1)
  $avg      → mean of numeric values
  $push     → collect every value into an array
  $topN     → top N ranked documents per group

Browse every tutorial in the left sidebar.

How MongoDB Accumulators Work

Documents enter $group. MongoDB puts each document into a bucket based on _id. Every accumulator field updates its state for that bucket, then emits one value when the group finishes.

1. Optionally filter first with $match.
2. Choose a group key for _id (field, compound object, or null).
3. Add accumulator fields ($sum, $avg, …).
4. Each group emits one document with those computed fields.

// Total + count per store
db.orders.aggregate([
  {
    $group: {
      _id: "$storeId",
      revenue: { $sum: "$amount" },
      orders:  { $sum: 1 }
    }
  }
])

// Global average (one bucket)
db.orders.aggregate([
  { $group: { _id: null, avgAmount: { $avg: "$amount" } } }
])

How It Works

1. Bucket by store. _id: "$storeId" creates one group per store.
2. $sum: adds amount; $sum: 1 counts documents.
3. Global group. _id: null puts every document in one bucket for a single average.

MongoDB Accumulator Syntax

Accumulators appear as fields inside $group. The pattern is always: output field name → { $accumulator: <input> }.

{
  $group: {
    _id: <group key>,
    <outputField>: { $accumulatorName: <expression> }
  }
}

"$fieldName"  → value from the current document
$sum: 1       → count documents in the group

{ $sum: "$amount" }

{ $avg: "$score" }

{ $push: "$name" }

{ $topN: { n: 3, sortBy: { score: -1 }, output: "$$ROOT" } }

Tip: some names also exist as expression operators (for example $sum in $group vs expression form). Context decides which syntax MongoDB expects—check the individual tutorial when unsure.

Pseudocode

Use this mental model before you write a $group stage.

goal = what you need per group (total / mean / list / top record)

buckets = empty map

for each document:
    key = evaluate(_id expression)
    put document into buckets[key]
    update each accumulator state for that key

for each key in buckets:
    emit {
      _id: key,
      field1: finalize(accumulator1),
      field2: finalize(accumulator2),
      ...
    }

How It Works

1. Start from the business question (total sales? unique tags? top 3?).
2. Pick the accumulator family that answers that question.
3. Group documents, update state per document, then emit one result per bucket.

Accumulator Categories

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

For per-document math and conditionals, see the operators hub. For pipeline steps around $group, see aggregation stages.

Common MongoDB Accumulators

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

Worked Example

Small orders collection. We keep completed orders, then compute count, revenue, average, and unique customers per store.

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

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

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

[
  {
    _id: "A",
    orderCount: 2,
    revenue: 100,
    avgOrder: 50,
    customers: ["c1", "c2"]
  },
  {
    _id: "B",
    orderCount: 1,
    revenue: 25,
    avgOrder: 25,
    customers: ["c1"]
  }
]

Choosing the Right Accumulator

Match the business question to the family first; then pick a specific operator.

Performance Notes

Use explain() when a pipeline feels slow. Prefer selective filters and smaller working sets over micro-optimizing a single accumulator choice.

Key Takeaways