The $accumulator operator lets you write custom JavaScript inside $group when built-in accumulators like $sum or $avg are not enough—ideal for conditional totals, weighted math, or bespoke rollups.
Your own JS functions.
Start state, update per doc.
Combine parallel partial states.
Optional output transform.
Custom vs built-in speed.
JavaScript required today.
$accumulator is a MongoDB accumulator used in the $group stage. Instead of a fixed operation like addition or averaging, you supply JavaScript functions that define how state is initialized, updated for each document, merged across workers, and optionally finalized.
Think of $accumulator as a DIY reducer. init sets the starting value (like 0 for a sum). accumulate runs once per document and returns the new state. When MongoDB splits work across shards, merge combines two partial states into one.
Reach for built-in accumulators first—$sum, $avg, $push. Use $accumulator when your business rule needs JavaScript expressiveness that those operators cannot provide.
$accumulator takes an object with JavaScript function definitions:
{
$group: {
_id: <expression>,
<outputField>: {
$accumulator: {
init: <function>,
accumulate: <function>,
accumulateArgs: <array>,
merge: <function>,
finalize: <function>,
lang: <string>
}
}
}
}init — zero-argument function; returns the initial accumulator state for each group.accumulate — function (state, ...args); called once per document; must return updated state.accumulateArgs — array of expressions (usually field paths) passed as extra arguments after state.merge — function (state1, state2); combines partial states from parallel processing.finalize — optional; function (state); transforms state before output.lang — required; must be "js" (JavaScript).db.transactions.aggregate([
{
$group: {
_id: null,
totalAmount: {
$accumulator: {
init: function() { return 0; },
accumulate: function(state, amount) {
return state + amount;
},
accumulateArgs: ["$amount"],
merge: function(s1, s2) { return s1 + s2; },
lang: "js"
}
}
}
}
]);| Question | Answer |
|---|---|
| Stage | $group accumulator |
| Required keys | init, accumulate, accumulateArgs, merge, lang |
| Optional key | finalize |
| Language | lang: "js" |
| When to use | Logic that built-in accumulators cannot express |
| Prefer instead | $sum, $avg, $push when they fit |
init: function() {
return 0;
}Starting state per group
accumulate: function(
state, amount
) {
return state + amount;
}Update per document
merge: function(s1, s2) {
return s1 + s2;
}Combine partial states
finalize: function(state) {
return state;
}Optional last step
Each property in the $accumulator object plays a distinct role in the aggregation lifecycle:
init RequiredCalled once when a group starts. Return the initial state— a number, object, or array depending on your logic.
init: function() { return { sum: 0, count: 0 }; }accumulate RequiredFirst parameter is always the current state. Additional parameters come from accumulateArgs, in order.
accumulate: function(state, amt) {
return state + amt;
}accumulateArgs RequiredArray of aggregation expressions evaluated per document and passed to accumulate after state.
accumulateArgs: ["$amount"]
accumulateArgs: ["$price", "$qty"]merge RequiredCombines two states of the same shape. Must be associative with your accumulate logic so sharded results stay correct.
merge: function(a, b) {
return { sum: a.sum + b.sum, count: a.count + b.count };
}finalize OptionalRuns once after all documents in a group are processed. Return the value that appears in the output document.
finalize: function(s) {
return s.count ? s.sum / s.count : null;
}lang RequiredSpecifies the language for all functions. Currently only "js" is supported.
lang: "js"Transaction amounts—build a custom running total, compute average with internal state, and compare with native $sum.
Sample transactions and a minimal custom sum using $accumulator.
db.transactions.insertMany([
{ amount: 100, category: "food" },
{ amount: 150, category: "food" },
{ amount: 200, category: "travel" },
{ amount: 50, category: "food" }
]);Four transactions—three in food (100 + 150 + 50 = 300) and one in travel (200). Good data for per-category and global totals.
db.transactions.aggregate([
{
$group: {
_id: null,
totalAmount: {
$accumulator: {
init: function() { return 0; },
accumulate: function(state, amount) {
return state + amount;
},
accumulateArgs: ["$amount"],
merge: function(s1, s2) { return s1 + s2; },
finalize: function(state) { return state; },
lang: "js"
}
}
}
}
]);
/* Result:
[ { _id: null, totalAmount: 500 } ]
100 + 150 + 200 + 50 = 500 */
*/init starts at 0. Each document adds its amount via accumulate. merge adds partial totals if MongoDB parallelizes the group.
Custom averages, built-in comparisons, and multi-field logic.
Track both sum and count in state, then divide in finalize:
db.transactions.aggregate([
{
$group: {
_id: "$category",
avgAmount: {
$accumulator: {
init: function() {
return { sum: 0, count: 0 };
},
accumulate: function(state, amount) {
return {
sum: state.sum + amount,
count: state.count + 1
};
},
accumulateArgs: ["$amount"],
merge: function(a, b) {
return { sum: a.sum + b.sum, count: a.count + b.count };
},
finalize: function(state) {
return state.count === 0
? null
: state.sum / state.count;
},
lang: "js"
}
}
}
},
{ $sort: { _id: 1 } }
]);
/* food → avgAmount: 100 (300 / 3)
travel → avgAmount: 200 (200 / 1) */
*/State holds intermediate values; finalize produces the user-facing average. Built-in $avg does this natively—this pattern shows how state objects work.
db.transactions.aggregate([
{
$group: {
_id: null,
customTotal: {
$accumulator: {
init: function() { return 0; },
accumulate: function(s, a) { return s + a; },
accumulateArgs: ["$amount"],
merge: function(s1, s2) { return s1 + s2; },
lang: "js"
}
},
nativeTotal: { $sum: "$amount" }
}
}
]);
/* Both return 500 — use $sum for simple addition */
*/When both produce the same result, prefer $sum—less code, better performance, no JavaScript sandbox overhead.
Only add amounts above 75—a rule that needs custom logic:
db.transactions.aggregate([
{
$group: {
_id: null,
bigSpendsOnly: {
$accumulator: {
init: function() { return 0; },
accumulate: function(state, amount) {
if (amount > 75) {
return state + amount;
}
return state;
},
accumulateArgs: ["$amount"],
merge: function(s1, s2) { return s1 + s2; },
lang: "js"
}
}
}
}
]);
/* Skips 50; sums 100 + 150 + 200 = 450 */
*/Conditional logic inside accumulate is a common reason to choose $accumulator. You could also use $sum with a $cond expression—compare both approaches for readability.
$accumulator WorksMongoDB calls init() when a new _id bucket starts and stores the returned state.
For each document, evaluate accumulateArgs, then call accumulate(state, ...args).
If work is split across processes, merge folds partial states into one combined state.
Optional finalize(state) shapes the final value written to the group result document.
$accumulator runs JavaScript—expect higher overhead than native accumulators like $sum.merge is always required even on a standalone server; it defines how partial states combine.lang: "js" is mandatory; functions must be valid JavaScript.$sum with $cond) when they cover your rule without custom code.$accumulator is MongoDB’s escape hatch for custom group-level logic: you own initialization, per-document updates, merging, and optional final formatting through JavaScript.
Start with built-in accumulators whenever possible. When you truly need bespoke rollups, wire up init, accumulate, and merge carefully—then continue with $addToSet for unique value collection.
accumulate pure—return new state, avoid mutating external variablesmerge to match how accumulate combines valuesfinalize only for output shaping, not heavy per-document work$sum or $avg with $accumulator without a clear benefitmerge—pipelines fail or return wrong results on sharded clusters without itfinalize is required—it is optional$accumulatorUse these points when built-in accumulators are not enough.
Your group logic.
BasicsStarting state.
LifecyclePer-document update.
CoreCombine partial states.
Sharding$sum when possible.
PerformanceThe same custom-sum logic in $accumulator can often be written as { $sum: "$amount" } or { $sum: { $cond: [condition, "$amount", 0] } } without JavaScript—native operators compile to faster server code. Reserve $accumulator for state shapes and rules that expressions cannot express cleanly. See the official $accumulator docs.
Custom logic with $accumulator, then learn $addToSet for unique value arrays.
5 people found this page helpful