The $map operator applies an expression to every element in an array and returns a new array of transformed values. It is MongoDB’s aggregation version of JavaScript’s Array.map().
01
Transform Arrays
Map each element.
02
Syntax
input + as + in.
03
$$ Variable
Current element ref.
04
Same Length
One output per input.
05
Use Cases
Scores, prices, names.
06
vs $filter
Transform vs select.
Fundamentals
Definition and Usage
In MongoDB’s aggregation framework, the $map operator loops through an array and evaluates an expression for each element. You provide the source array (input), a variable name (as), and the transformation (in). The results are collected into a new array with the same number of elements as the input.
For example, doubling each score in [70, 85, 90] produces [140, 170, 180]. When the array holds objects, you can extract or reshape fields from each item.
💡
Beginner Tip
Inside in, reference the current array element with a double dollar sign: if as is "score", use "$$score". A single $ refers to document fields; $$ refers to variables defined in $map, $filter, or $let.
Foundation
📝 Syntax
The $map operator takes an object with input, as, and in:
// Double each number
{ $multiply: [ "$$score", 2 ] }
// Extract a field from objects
"$$item.name"
// Add tax to each price
{ $multiply: [ "$$item.price", 1.1 ] }
// Build a new object per element
{ name: "$$item.name", total: {
$multiply: [ "$$item.qty", "$$item.price" ]
}}
Syntax Rules
input — the array to transform (field path like "$scores" or a literal array).
as — variable name for the current element (e.g. "item" or "score").
in — expression evaluated per element; its result becomes the next output array item.
// Alice → results: ["pass", "pass", "pass"]
// Bob → results: ["fail", "pass", "pass"]
// Charlie → results: ["pass", "pass", "pass"]
How It Works
The in expression can be any valid aggregation expression — including $cond, $multiply, or nested objects. Each element gets its own transformed value.
Example 4 — Compute Line Totals from Order Items
Map each item object to its quantity × price total:
input can be a literal array. Every document gets the same result: [11, 12, 13]. Useful for testing expressions or building fixed output structures.
Applications
🚀 Use Cases
Numeric transforms — scale, round, or convert values in score or measurement arrays.
Field extraction — pull one property from each object in an embedded array.
Label generation — map raw values to pass/fail, tier, or status strings.
Line-item math — compute per-item totals before summing with $sum.
🧠 How $map Works
1
MongoDB reads the input array
The input expression resolves to an array from a field path or literal.
Input
2
Loops with as variable
Each element is bound to $$asName while the in expression runs.
Loop
3
Collects transformed values
Each in result is appended to a new output array in the same order.
Output
=
🔄
Transformed array
You get a new array with one transformed value per input element.
Wrap Up
Conclusion
The $map operator brings JavaScript-style array mapping into MongoDB aggregation pipelines. Use it to transform every element in an embedded array — scaling numbers, extracting fields, or building new objects — without unwinding documents.
Remember the pattern: input (the array), as (variable name), in (transformation). Reference elements with $$name. When you only need a subset of elements, use $filter instead.
Use $map when you only need matching elements (use $filter)
Use single $ for loop variables (use $$)
Use $map as a pipeline stage — it is an expression operator
Expect output length to differ from input (it stays the same)
Forget $unwind is different — it expands documents, not arrays in place
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $map
Use these points when transforming arrays in MongoDB.
5
Core concepts
🔄01
Transform All
Every element mapped.
Purpose
📝02
input + in
Array + expression.
Syntax
🔢03
$$ Reference
Current element var.
Variables
🛠04
Same Length
1:1 input/output.
Behavior
📑05
vs $filter
Map vs select.
Compare
❓ Frequently Asked Questions
$map applies an expression to every element in an array and returns a new array with the transformed values. It is like JavaScript's Array.map() inside an aggregation expression.
The syntax is { $map: { input: <array>, as: <string>, in: <expression> } }. The in expression runs once per element and its result becomes the next item in the output array.
Use the variable name you set in as with a double dollar prefix. If as is "item", reference the current element as "$$item" inside in.
$map transforms every element and keeps the same array length. $filter keeps only elements where a condition is true, so the output array may be shorter.
Use $map inside expression stages such as $project, $addFields, and $set when you need to transform values in an embedded array without changing the parent document count.
