$unwind
Array Deconstruction

$unwind deconstructs an array field in each input document, outputting one document per array element. A document with an array of N elements produces N output documents, each containing one element in place of the original array.

Why Use $unwind?

• Group by array elements — e.g., count documents per tag, per item
• Filter individual elements — remove/select specific elements from each doc's array
• Flatten a $lookup result — convert 1-to-1 join array into an embedded object
• Per-element computation — apply expressions to each element before re-grouping

$unwind is a document fan-out operation. It multiplies documents flowing through the pipeline — one per array element. This is expected behavior but must be managed to avoid hitting memory limits.

// 1 document × 1,000-element array → 1,000 pipeline documents
// 10,000 documents × 100-element arrays → 1,000,000 pipeline documents

Pre-Unwind Optimization

db.articles.aggregate([

  // 1. Filter documents FIRST
  { $match: { status: "published", category: "tech" } },

  // 2. Drop unneeded fields BEFORE expanding
  { $project: { tags: 1, _id: 1 } },

  // 3. NOW expand — fewer docs, fewer fields per doc
  { $unwind: "$tags" },

  // 4. Aggregate on the reduced-and-expanded set
  { $group: { _id: "$tags", count: { $sum: 1 } } },
  { $sort: { count: -1 } }
])

// Simple form — most common
{ $unwind: "$arrayField" }

// Extended form — with options
{
  $unwind: {
    path:                       "$arrayField",
    includeArrayIndex:          "indexFieldName",  // optional
    preserveNullAndEmptyArrays: true               // optional, default: false
  }
}

Scalar (Non-Array) Field Behavior

// $unwind on a scalar field treats it as a 1-element array — no error
{ _id: 1, tag: "mongodb" }     // single string, not array
db.col.aggregate([{ $unwind: "$tag" }])
// Output: { _id:1, tag:"mongodb" }  — same doc, no multiplication

By default, $unwind silently drops any document where the target array field is null, missing, or an empty array. No error is thrown — documents simply disappear from the pipeline.

// Test data
{ _id: 1, tags: ["mongodb", "nosql"] }  // normal array
{ _id: 2, tags: [] }                     // empty array
{ _id: 3, tags: null }                   // null
{ _id: 4 }                              // field missing

// DEFAULT — docs 2, 3, 4 vanish silently!
db.col.aggregate([{ $unwind: "$tags" }])
// Returns only:
// { _id:1, tags:"mongodb" }
// { _id:1, tags:"nosql" }

// WITH preserveNullAndEmptyArrays:true
db.col.aggregate([{
  $unwind: {
    path: "$tags",
    preserveNullAndEmptyArrays: true
  }
}])
// Returns:
// { _id:1, tags:"mongodb" }
// { _id:1, tags:"nosql" }
// { _id:2 }              ← empty array doc kept (field absent)
// { _id:3, tags:null }   ← null doc kept
// { _id:4 }              ← missing field doc kept

After unwinding, the original position of each element within its parent array is lost. Use includeArrayIndex to store the zero-based index as a new field on each output document.

// Input: { _id:1, steps: ["Start", "Process", "End"] }

db.workflows.aggregate([{
  $unwind: {
    path: "$steps",
    includeArrayIndex: "stepIndex"
  }
}])

// Output:
// { _id:1, steps:"Start",   stepIndex: NumberLong(0) }
// { _id:1, steps:"Process", stepIndex: NumberLong(1) }
// { _id:1, steps:"End",     stepIndex: NumberLong(2) }

// Useful for: displaying step number, filtering by position, sorting after regroup

Filter by Position Using includeArrayIndex

// Retrieve only the first element of each document's array
db.col.aggregate([
  {
    $unwind: {
      path: "$items",
      includeArrayIndex: "pos"
    }
  },
  { $match: { pos: 0 } },              // keep only index 0 (first elements)
  { $project: { items: 1, pos: 0 } }  // hide the pos field in output
])

The unwind-rewind pattern uses $unwind to access individual elements, filters or transforms them, then uses $group with $push to reassemble a modified array.

// Remove "deprecated" tag from all articles' tags arrays
db.articles.aggregate([

  // Step 1: Expand — one doc per tag
  { $unwind: "$tags" },

  // Step 2: Filter — remove unwanted elements
  { $match: { tags: { $ne: "deprecated" } } },

  // Step 3: Rewind — rebuild the array from survivors
  //         Use $first to recover original scalar fields
  {
    $group: {
      _id:    "$_id",
      tags:   { $push: "$tags" },
      title:  { $first: "$title" },
      status: { $first: "$status" }
    }
  }
])

Transform Elements During Unwind-Rewind

// Uppercase all tags and rebuild
db.articles.aggregate([
  { $unwind: "$tags" },
  { $addFields: { tags: { $toUpper: "$tags" } } },  // transform each element
  {
    $group: {
      _id:   "$_id",
      tags:  { $push: "$tags" },
      title: { $first: "$title" }
    }
  }
])

Count Per Array Element (Tag Frequency)

// Count how many published articles have each tag
db.articles.aggregate([
  { $match: { status: "published" } },
  { $unwind: "$tags" },
  {
    $group: {
      _id:   "$tags",
      count: { $sum: 1 }
    }
  },
  { $sort: { count: -1 } },
  { $limit: 10 }
])

Default vs preserveNullAndEmptyArrays Behavior