MongoDB $unwind Stage

Beginner

⏱️ 11 min read

📚 Updated: Jul 2026

🎯 5 Examples

Aggregation

Overview

What You’ll Learn

The $unwind stage splits array fields into one document per element—essential for tag analytics, order line items, flattening $lookup results, and any pipeline that must treat array items as rows.

Array → rows

One per item.

path

Field to split.

preserve null

Keep empty.

Array index

Position.

+ $group

Count tags.

+ $lookup

Flatten join.

Fundamentals

Definition and Usage

$unwind is an aggregation stage that takes an array field and outputs one document per array element. All other fields on the parent document are copied into each output row—the array field is replaced by a single scalar (or sub-document) value per row.

💡

Beginner tip

Before: { title: "Post A", tags: ["mongo", "api"] } — one document.
After { $unwind: "$tags" }: two documents — tags: "mongo" and tags: "api".
Same title on both rows; tags split for filtering or grouping.

Use $unwind whenever array elements need individual treatment: count tags with $group, sum line-item prices, match on one skill in a list, or flatten $lookup join arrays into readable rows.

Foundation

📝 Syntax

$unwind supports a shorthand string path or an extended options document:

mongosh

// Shorthand
{ $unwind: <string path> }

// Extended
{
  $unwind: {
    path: <string path>,
    includeArrayIndex: <string>,       // optional
    preserveNullAndEmptyArrays: <boolean>  // optional, default false
  }
}

Syntax Rules

path — required. Prefixed with $: "$tags", "$items", "$lookupResult".
Default behavior — documents with missing, null, or empty arrays are excluded from output.
preserveNullAndEmptyArrays: true — keeps those documents; array field becomes null in output.
includeArrayIndex — adds a new field with the zero-based index of the element in the original array.
Non-array values — if the field holds a single value (not an array), MongoDB treats it as a one-element array.
Document count — multiplies rows: N elements → N output documents (per input document).

mongosh

db.articles.aggregate([
  { $unwind: "$tags" }
])

Cheat Sheet

⚡ Quick Reference

Question	Answer
What it does	One output document per array element
Shorthand	`{ $unwind: "$arrayField" }`
Empty array default	Document dropped from output
Keep empty/null	`preserveNullAndEmptyArrays: true`
Element index	`includeArrayIndex: "fieldName"`
Common next stage	`$group`, `$match`, `$sortByCount`

Basic

{ $unwind:
  "$tags"
}

Split tags

Preserve

preserveNullAndEmpty
Arrays: true

Keep empty

Index

includeArrayIndex:
"lineIdx"

Position

Pattern

$unwind →
$group

Tag counts

Reference

🧰 `$unwind` Options

Extended syntax gives control over empty arrays and element position:

path Required

Array field to deconstruct. Must be a string starting with $. Can be nested: "$order.items".

{ $unwind: "$skills" }
{ $unwind: { path: "$items" } }

preserveNullAndEmptyArrays Optional

Default false. When true, documents with missing, null, or empty arrays still appear in output once.

{ $unwind: {
  path: "$tags",
  preserveNullAndEmptyArrays: true
}}

includeArrayIndex Optional

String name for a new field holding the element’s zero-based index—useful for line numbers and ordered lists.

{ $unwind: {
  path: "$items",
  includeArrayIndex: "lineIndex"
}}

After $lookup Pattern

Join results arrive in an array. Unwind to flatten—one parent row per matched foreign document.

{ $lookup: { ... } },
{ $unwind: "$customerData" }

Hands-On

Examples Gallery

Articles and orders—basic tag split, optional tags with preserve, line items with index, tag frequency via $group, and flattening lookup-style arrays.

📚 Getting Started

Articles with tags and orders with line items.

Example 1 — Articles and orders collections

mongosh

db.articles.drop()
db.orders.drop()

db.articles.insertMany([
  { title: "MongoDB Basics",    tags: ["mongodb", "database"] },
  { title: "REST API Guide",    tags: ["nodejs", "api"]       },
  { title: "Draft Notes",       tags: []                      },
  { title: "Untagged Post",     tags: null                    }
])

db.orders.insertMany([
  {
    orderId: "O-1001",
    customer: "Ana",
    items: [
      { product: "Widget", qty: 2, price: 25 },
      { product: "Cable",  qty: 1, price: 9  }
    ]
  },
  {
    orderId: "O-1002",
    customer: "Ben",
    items: [
      { product: "Gadget", qty: 1, price: 80 }
    ]
  }
])

How It Works

Articles include normal tags, an empty array, and null—perfect for demonstrating default vs preserve behavior. Orders have nested item arrays for index examples.

Example 2 — Unwind tags (basic shorthand)

mongosh

db.articles.aggregate([
  { $unwind: "$tags" },
  {
    $project: {
      _id: 0,
      title: 1,
      tag: "$tags"
    }
  }
])

// "MongoDB Basics" (2 tags) → 2 rows
// "REST API Guide" (2 tags)  → 2 rows
// "Draft Notes" (empty)      → DROPPED (default)
// "Untagged Post" (null)     → DROPPED (default)
// Total: 4 output documents

How It Works

The shorthand { $unwind: "$tags" } is the most common form. Each tag becomes its own row while title repeats on every row from the same article.

Example 3 — Keep articles with no tags (preserveNullAndEmptyArrays)

mongosh

db.articles.aggregate([
  {
    $unwind: {
      path: "$tags",
      preserveNullAndEmptyArrays: true
    }
  },
  {
    $project: {
      _id: 0,
      title: 1,
      tag: "$tags"
    }
  }
])

// Same 4 tagged rows as Example 2, PLUS:
// "Draft Notes"   → tag: null (empty array preserved)
// "Untagged Post" → tag: null (null array preserved)
// Total: 6 output documents

How It Works

Use preserveNullAndEmptyArrays: true when untagged or empty-list documents must still appear—optional categories, incomplete records, or left-outer-join semantics after lookup.

📈 Practical Patterns

Line indexes, tag analytics, and lookup flattening.

Example 4 — Order line items with array index

mongosh

db.orders.aggregate([
  {
    $unwind: {
      path: "$items",
      includeArrayIndex: "lineIndex"
    }
  },
  {
    $project: {
      _id: 0,
      orderId: 1,
      customer: 1,
      lineIndex: 1,
      product: "$items.product",
      qty: "$items.qty",
      price: "$items.price",
      lineTotal: {
        $multiply: ["$items.qty", "$items.price"]
      }
    }
  }
])

// O-1001 → 2 rows: lineIndex 0 (Widget), lineIndex 1 (Cable)
// O-1002 → 1 row:  lineIndex 0 (Gadget)

How It Works

includeArrayIndex preserves position—line 1, line 2 on invoices—or lets you sort items in original order after unwind.

Example 5 — Tag frequency ($unwind + $group)

mongosh

// Count how many articles use each tag
db.articles.aggregate([
  { $match: { tags: { $exists: true, $ne: null, $not: { $size: 0 } } } },
  { $unwind: "$tags" },
  {
    $group: {
      _id: "$tags",
      articleCount: { $sum: 1 }
    }
  },
  { $sort: { articleCount: -1 } },
  {
    $project: {
      _id: 0,
      tag: "$_id",
      articleCount: 1
    }
  }
])

// mongodb & database: 1 each (MongoDB Basics)
// nodejs & api: 1 each (REST API Guide)
// Shortcut alternative: $unwind then { $sortByCount: "$tags" }

How It Works

The classic analytics chain: unwind array elements into rows, then group and count. Same pattern powers tag clouds, skill inventories, and category breakdowns. For count-only output, $sortByCount after unwind is a one-stage shortcut.

Compare

📋 `$unwind` vs related array stages

Stage / tool	Behavior	Best for
`$unwind`	One doc per array element	Flatten tags, items, lookup arrays
`$group`	Collapse many docs into buckets	After unwind—count or sum per element
`$sortByCount`	Group + count + sort (no unwind needed for scalar field)	After unwind on tags for frequency list
`$lookup`	Join foreign docs into array field	Often followed by `$unwind` to flatten
`$project` (array ops)	Map/filter arrays in place	Transform arrays without row multiplication

🧠 How `$unwind` Works

Read array field

MongoDB reads the field at path on each input document.

Input

Emit one row per element

Each array item becomes a separate document; sibling fields are copied into every row.

Split

Apply options

Empty/null arrays drop or preserve per preserveNullAndEmptyArrays; index added if requested.

Options

Flattened stream

Downstream stages see scalar array values—ready for $match, $group, or joins.

Important

📝 Notes

$unwind multiplies document count—large arrays increase pipeline volume.
Empty or missing arrays exclude documents unless preserveNullAndEmptyArrays: true.
Path must be a string with $ prefix: "$fieldName".
After $lookup, unwind the join array field to avoid nested array results.
For tag/category frequency, chain $unwind → $sortByCount or $group.
Previous topic: $unset. Next: $group.

Wrap Up

Conclusion

$unwind turns array fields into rows: use shorthand for simple splits, preserveNullAndEmptyArrays for optional arrays, and includeArrayIndex when position matters.

Pair with $group for analytics or follow $lookup to flatten joins. Next: $group to bucket and summarize unwound rows.

Review examples Next: $group

Pro Tips

💡 Best Practices

✅ Do

Unwind before $group when counting array element frequencies
Unwind $lookup result arrays for flat joined reports
Use preserveNullAndEmptyArrays: true for optional or incomplete arrays
Add includeArrayIndex for ordered line items or ranked lists
$match before unwind when only some parent documents matter

❌ Don’t

Unwind huge arrays on every request without filtering first
Forget that empty arrays disappear with default settings
Skip unwind and expect $group to count individual tags correctly
Unwind the same array twice without need—row count grows fast
Omit the $ prefix on the path string

Summary

Key Takeaways

Knowledge Unlocked

Five things to remember about `$unwind`

Use these points whenever array elements must become rows.

Core concepts

🔄 01

Array → rows

One per item.

Basics

📝 02

$path

Field string.

Syntax

📋 03

Preserve empty

Optional flag.

Option

🔢 04

Index field

Line number.

Order

👥 05

+ $group

Analytics.

Pattern

❓ Frequently Asked Questions

What does the MongoDB $unwind stage do?

$unwind deconstructs an array field so each array element becomes its own output document. One document with tags: ["mongo", "api"] becomes two documents—each with a single tag value—so you can filter, group, or join on individual array items.

What is the syntax for $unwind?

Short form: { $unwind: "$arrayField" }. Extended form: { $unwind: { path: "$arrayField", preserveNullAndEmptyArrays: true, includeArrayIndex: "indexName" } }. The path must be prefixed with $.

What happens to documents with empty or missing arrays?

By default, $unwind removes documents where the array is missing, null, or empty. Set preserveNullAndEmptyArrays: true to keep those documents with the array field null or missing in output.

Why use $unwind before $group?

When you need counts or sums per array element—tag frequency, line-item totals, skills per employee—you must unwind first so each element is its own row, then $group on that field.

How is $unwind used with $lookup?

$lookup returns matching documents in an array field. $unwind flattens that array so joined fields sit at the top level—one output row per match instead of nested arrays.

Can $unwind include the array index?

Yes. Set includeArrayIndex to a field name string—e.g. includeArrayIndex: "lineIndex"—and MongoDB adds the zero-based position of each element in the original array.

Did you know?

MongoDB also offers $unwind with a path pointing at nested arrays—you can unwind sub-documents inside arrays when each element is an object (like order line items). For arrays of arrays, you may need two unwind stages in sequence. See the official $unwind docs.

Continue the Stages Series

Flatten arrays with $unwind, then summarize with $group.

Next: $group →

About the author

Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

Experience 12 years building web and cloud systems
Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

5 people found this page helpful

MongoDB $unset Stage MongoDB $group Stage

MongoDB $unwind Stage

What You’ll Learn

Array → rows

path

preserve null

Array index

+ $group

+ $lookup

Definition and Usage

📝 Syntax

Syntax Rules

⚡ Quick Reference

🧰 $unwind Options

Examples Gallery

📚 Getting Started

Example 1 — Articles and orders collections

How It Works

Example 2 — Unwind tags (basic shorthand)

How It Works

Example 3 — Keep articles with no tags (preserveNullAndEmptyArrays)

How It Works

📈 Practical Patterns

Example 4 — Order line items with array index

How It Works

Example 5 — Tag frequency ($unwind + $group)

How It Works

📋 $unwind vs related array stages

🧠 How $unwind Works

Read array field

Emit one row per element

Apply options

Flattened stream

📝 Notes

Conclusion

💡 Best Practices

✅ Do

❌ Don’t

Key Takeaways

Five things to remember about $unwind

Array → rows

$path

Preserve empty

Index field

+ $group

❓ Frequently Asked Questions

🧩 Related MongoDB Topics

MongoDB $unset

MongoDB $group

MongoDB $lookup

MongoDB $sortByCount

Practice examples

Official MongoDB docs

Continue the Stages Series

About the author

🧰 `$unwind` Options

📋 `$unwind` vs related array stages

🧠 How `$unwind` Works

Five things to remember about `$unwind`