The $zip operator merges parallel arrays element by element inside MongoDB aggregation pipelines. Each output item is a sub-array containing the values at the same index from every input array — like pairing columns in a spreadsheet row.
Pair by index.
inputs + options.
Default length rule.
useLongestLength.
Zip + $map.
Zip vs append.
In MongoDB’s aggregation framework, the $zip operator takes two or more arrays and combines them by index. If you have names: ["Alice", "Bob"] and scores: [90, 85], zipping them produces [["Alice", 90], ["Bob", 85]].
This is useful when related data is stored in separate parallel arrays instead of an array of objects. You can zip them together, then use $map to reshape each pair into a structured object for reporting or export.
Think of $zip as stacking arrays side by side. Index 0 from each array becomes one row, index 1 becomes the next row, and so on. By default, zipping stops when the shortest array runs out of elements.
The $zip operator takes an object with an inputs array and optional length options:
{
$zip: {
inputs: [ <array1>, <array2>, ... ],
useLongestLength: <boolean>,
defaults: <array>
}
}// Zip two field arrays
{
$zip: {
inputs: [ "$names", "$scores" ]
}
}
// Zip three parallel arrays
{
$zip: {
inputs: [ "$first", "$last", "$grades" ]
}
}
// Pad shorter arrays to longest length
{
$zip: {
inputs: [ "$keys", "$values" ],
useLongestLength: true,
defaults: [ null, 0 ]
}
}
// Zip then build objects with $map
{
$map: {
input: {
$zip: { inputs: [ "$names", "$scores" ] }
},
as: "pair",
in: {
name: { $arrayElemAt: [ "$$pair", 0 ] },
score: { $arrayElemAt: [ "$$pair", 1 ] }
}
}
}inputs — required array of two or more array expressions (field paths or literals).useLongestLength — optional boolean; default false (stop at shortest array).defaults — optional array of fallback values, one per input array, used when useLongestLength is true.null or not an array, $zip returns null.$project, $addFields, or $set.$zip → pairs elements by index: [["a",1],["b",2]]$concatArrays → appends into one flat array: ["a","b",1,2]$map → transforms each element in a single array; often used after $zip$zip = Python zip(), $concatArrays = array spread / concat| Question | Answer |
|---|---|
| Operator type | Aggregation array expression operator |
| Syntax | { $zip: { inputs, useLongestLength?, defaults? } } |
| Input | Two or more arrays (field paths or literals) |
| Output | Array of sub-arrays (or null) |
| Default length | Length of the shortest input array |
| Common stages | $project, $addFields, $set |
{
$zip: {
inputs: [ "$a", "$b" ]
}
}Pair by index
{
$zip: {
inputs: [
"$first",
"$last",
"$score"
]
}
}Three-column rows
{
$zip: {
inputs: [ "$k", "$v" ],
useLongestLength: true,
defaults: [ "", 0 ]
}
}Pad shorter arrays
{
$zip: {
inputs: [
["x", "y"],
[1, 2]
]
}
}Returns [["x",1],["y",2]]
Zip parallel arrays, handle mismatched lengths, pad with defaults, and reshape zipped pairs into objects using a students collection.
Pair names with scores using the default shortest-length behavior.
Suppose you have a students collection where names and scores are stored in separate arrays:
[
{
"_id": 1,
"className": "Math 101",
"names": ["Alice", "Bob", "Carol"],
"scores": [92, 85, 78]
},
{
"_id": 2,
"className": "Science 201",
"names": ["Dave", "Eve"],
"scores": [88, 91, 95]
}
]Merge names and scores into paired sub-arrays:
db.students.aggregate([
{
$project: {
className: 1,
nameScorePairs: {
$zip: {
inputs: [ "$names", "$scores" ]
}
}
}
}
])$zip reads index 0 from each input array and builds the first sub-array, then index 1, and so on. For Science 201, names has only two items, so the extra score 95 is ignored.
Zip three columns, control output length, and reshape results into objects.
Combine first names, last names, and grades into three-column rows:
db.students.aggregate([
{
$project: {
rows: {
$zip: {
inputs: [
["Alice", "Bob"],
["Smith", "Jones"],
["A", "B"]
]
}
}
}
}
])
// rows: [
// ["Alice", "Smith", "A"],
// ["Bob", "Jones", "B"]
// ]inputs accepts literal arrays as well as field paths. Each position across all three arrays becomes one sub-array in the output.
When arrays differ in length, only the shortest count is used:
db.students.aggregate([
{
$project: {
paired: {
$zip: {
inputs: [
["a", "b", "c"],
[1, 2]
]
}
}
}
}
])
// paired: [["a", 1], ["b", 2]]
// "c" is dropped because the second array has only 2 elementsWith default settings (useLongestLength: false), MongoDB stops at the shortest input. This prevents mismatched pairings when one array is unexpectedly longer.
Pad shorter arrays so every element in the longest array gets a pair:
db.students.aggregate([
{
$project: {
paired: {
$zip: {
inputs: [
["a", "b", "c"],
[1, 2]
],
useLongestLength: true,
defaults: [ null, 0 ]
}
}
}
}
])
// paired: [["a", 1], ["b", 2], ["c", 0]]useLongestLength: true continues to the longest array. The defaults array supplies fill values per input column — null for missing names and 0 for missing scores.
Turn each zipped pair into a readable object for API responses or exports:
db.students.aggregate([
{
$project: {
className: 1,
roster: {
$map: {
input: {
$zip: {
inputs: [ "$names", "$scores" ]
}
},
as: "row",
in: {
name: { $arrayElemAt: [ "$$row", 0 ] },
score: { $arrayElemAt: [ "$$row", 1 ] }
}
}
}
}
}
])
// roster: [
// { name: "Alice", score: 92 },
// { name: "Bob", score: 85 }
// ]$zip creates sub-arrays; $map walks each sub-array and uses $arrayElemAt to pick index 0 (name) and index 1 (score). This is the standard pattern for converting parallel arrays into structured data.
When keys and values live in separate arrays, zip them before converting to an object:
db.students.aggregate([
{
$project: {
scoreMap: {
$arrayToObject: {
$map: {
input: {
$zip: {
inputs: [
["math", "science", "english"],
[92, 88, 95]
]
}
},
as: "pair",
in: {
k: { $arrayElemAt: [ "$$pair", 0 ] },
v: { $arrayElemAt: [ "$$pair", 1 ] }
}
}
}
}
}
}
])
// scoreMap: { math: 92, science: 88, english: 95 }$arrayToObject expects an array of { k, v } documents. Zipping parallel key and value arrays is a clean way to build that structure. See the $arrayToObject operator tutorial for more patterns.
$arrayToObject.$zip WorksEvery expression in inputs is resolved per document — field paths like "$names" or literal arrays.
By default, length equals the shortest input. With useLongestLength: true, length equals the longest input and defaults fill gaps.
For each index i, MongoDB collects element i from every input array into one sub-array.
Pass the result to $map, $arrayToObject, or $unwind for further shaping.
The $zip operator merges parallel arrays element-wise in MongoDB aggregation pipelines. It is the go-to tool when related values live in separate arrays and you need to pair them by index before reshaping with $map or $arrayToObject.
Remember: default behavior stops at the shortest array. Use useLongestLength and defaults when you need every element from the longest column. Next in the series: MongoDB Accumulators.
$zip with $map to build readable objectsuseLongestLength + defaults when padding is intentional$arrayToObject for key-value reconstruction$zip with $concatArrays (pair vs append)$zipUse these points when merging parallel arrays in MongoDB.
Columns → rows.
PurposeTwo+ arrays.
SyntaxDefault length.
BehaviorBuild objects.
PatternZip vs append.
CompareYou’ve reached the last expression operator. Move on to MongoDB Accumulators for grouping calculations like $sum and $avg.
5 people found this page helpful