MongoDB $addToSet Accumulator

What You’ll Learn

The $addToSet accumulator builds an array of unique values while MongoDB groups documents. It is the aggregation-friendly way to answer “what distinct values appeared in this group?”

Definition and Usage

$addToSet is a MongoDB accumulator used inside the $group stage. For each group, it evaluates an expression on every input document and adds the result to an output array—but only if that exact value is not already in the array.

Typical reports include unique cities per department, distinct product categories sold per store, or a set of user IDs who performed an action. Pair with $match and $sort before grouping for cleaner results.

📝 Syntax

$addToSet appears as a field accumulator in $group:

{
  $group: {
    _id: <expression>,
    <outputField>: { $addToSet: <expression> }
  }
}

Syntax Rules

• Stage — used only as an accumulator in $group (not in $match filters).
• Expression — usually "$fieldName" or any valid aggregation expression.
• Output — an array of unique values per group (empty array if no documents match).
• Equality — deduplication uses BSON value comparison (same rules as $eq).
• Array fields — without $unwind, the whole array is one value added to the set.

db.orders.aggregate([
  {
    $group: {
      _id: "$storeId",
      productIds: { $addToSet: "$productId" }
    }
  }
]);

Examples Gallery

Sample employee orders data, then group by department to collect unique cities and compare $addToSet with $push.

db.sales.insertMany([
  { department: "Engineering", city: "Austin",  productId: "P1" },
  { department: "Engineering", city: "Seattle", productId: "P2" },
  { department: "Engineering", city: "Austin",  productId: "P3" },
  { department: "Marketing",   city: "Boston",  productId: "P1" },
  { department: "Marketing",   city: "Boston",  productId: "P4" }
]);

db.sales.aggregate([
  {
    $group: {
      _id: "$department",
      uniqueCities: { $addToSet: "$city" }
    }
  },
  { $sort: { _id: 1 } }
]);

/* Result:
[
  { _id: "Engineering", uniqueCities: ["Austin", "Seattle"] },
  { _id: "Marketing",   uniqueCities: ["Boston"] }
]
*/

Engineering → ["Austin", "Seattle"]
Marketing   → ["Boston"]

db.articles.aggregate([
  { $unwind: "$tags" },
  {
    $group: {
      _id: "$author",
      uniqueTags: { $addToSet: "$tags" }
    }
  }
]);

// Without $unwind, { $addToSet: "$tags" } would store
// whole arrays as set members—not individual tag strings.

$unwind → one doc per tag → $addToSet collects unique tag strings

db.sales.aggregate([
  {
    $group: {
      _id: "$department",
      allCities:   { $push: "$city" },
      uniqueCities: { $addToSet: "$city" }
    }
  },
  { $match: { _id: "Engineering" } }
]);

/* Engineering result:
{
  _id: "Engineering",
  allCities: ["Austin", "Seattle", "Austin"],
  uniqueCities: ["Austin", "Seattle"]
}
*/

$push:     ["Austin", "Seattle", "Austin"]
$addToSet: ["Austin", "Seattle"]

db.sales.aggregate([
  {
    $group: {
      _id: "$department",
      productIds: { $addToSet: "$productId" }
    }
  },
  {
    $project: {
      _id: 0,
      department: "$_id",
      productIds: 1,
      productCount: { $size: "$productIds" }
    }
  }
]);

{ department: "Engineering", productIds: ["P1","P2","P3"], productCount: 3 }

📝 Notes

• $addToSet is an accumulator—it belongs inside $group, not in $match.
• For array fields, $unwind first unless you intentionally want unique whole-array values.
• Result arrays are best treated as sets, not sorted lists—use $sortArray in a later stage if order matters.
• null may appear once in the set if the expression evaluates to null—filter early with $match when needed.
• Do not confuse with update operator $addToSet on updateOne—same name, different context (document updates vs aggregation).
• Next in the series: $avg for numeric averages per group.

💡 Best Practices