The $concatArrays operator merges multiple arrays into one array in MongoDB aggregation pipelines. Use it to combine tags, skills, categories, or any list fields stored separately in your documents.
Join lists end-to-end.
Array of array expressions.
Null → empty array.
Build unified lists.
Tags, skills, defaults.
Arrays vs strings.
In MongoDB’s aggregation framework, the $concatArrays operator concatenates multiple arrays into a single array. For example, { $concatArrays: [["js", "mongo"], ["node"]] } returns ["js", "mongo", "node"]. Elements keep their order: all items from the first array, then the second, and so on.
Do not confuse $concatArrays with $concat. $concat joins strings into one string. $concatArrays joins arrays into one array.
The $concatArrays operator takes an array of array expressions:
{ $concatArrays: [ <array1>, <array2>, ... ] }$concatArrays — returns one array containing all elements in order."$tags"), literal arrays ([1, 2]), or nested expressions.$project, $addFields, or $set.null or missing array fields are treated as empty arrays.["a", "b"] + ["c"] → ["a", "b", "c"]"a" + "b" → "ab"| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (array) |
| Syntax | { $concatArrays: [ arr1, arr2, ... ] } |
| Input types | Arrays only |
| Null / missing | Treated as empty array [] |
| Common stages | $project, $addFields, $set |
{
$concatArrays: ["$a", "$b"]
}Merge field arrays
{
$concatArrays: ["$tags", ["new"]]
}Append literal array
{
$concatArrays: [[1,2], [3]]
}Returns [1, 2, 3]
null → []Safe to merge
Merge tag lists, combine skills from multiple fields, and append default values using $concatArrays.
Use a products collection and combine separate tag arrays with $project.
Suppose you have a products collection with two tag arrays per document:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"name": "Laptop",
"primaryTags": ["electronics", "computers"],
"secondaryTags": ["sale", "featured"]
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"name": "Mouse",
"primaryTags": ["electronics", "accessories"],
"secondaryTags": null
}
]Merge primaryTags and secondaryTags into one allTags array:
db.products.aggregate([
{
$project: {
name: 1,
allTags: {
$concatArrays: [ "$primaryTags", "$secondaryTags" ]
}
}
}
])secondaryTags is null, treated as [] → only primary tags appear.Combine skills, append defaults, and merge three or more arrays.
When secondaryTags is null or missing, $concatArrays treats it as an empty array. The Laptop document merges four tags; the Mouse document keeps only its primary tags:
// Mouse document: secondaryTags is null
{ "name": "Mouse", "allTags": ["electronics", "accessories"] }
// If secondaryTags were missing entirely, result is the sameThis differs from $concat, where null makes the entire result null.
Merge technical and soft skills into one list for search indexing:
db.candidates.aggregate([
{
$project: {
name: 1,
allSkills: {
$concatArrays: [ "$technicalSkills", "$softSkills" ]
}
}
}
])
// technicalSkills: ["MongoDB", "Node.js"]
// softSkills: ["communication", "teamwork"]
// allSkills: ["MongoDB", "Node.js", "communication", "teamwork"]Order is preserved: all elements from the first array, then all from the second. Use $setUnion afterward if you need unique values only.
Always add a default category tag to every product:
db.products.aggregate([
{
$project: {
name: 1,
allTags: {
$concatArrays: [
"$primaryTags",
"$secondaryTags",
["catalog"]
]
}
}
}
])
// Every document gets "catalog" appended to its tag listLiteral arrays work as arguments. This pattern is useful for injecting system tags, default permissions, or baseline categories into every merged result.
Combine multiple list fields in one expression:
db.events.aggregate([
{
$project: {
title: 1,
allAttendees: {
$concatArrays: [
"$organizers",
"$speakers",
"$guests"
]
},
attendeeCount: {
$size: {
$concatArrays: [
"$organizers",
"$speakers",
"$guests"
]
}
}
}
}
])You can pass any number of arrays. Pair with $size to count total elements, or $setUnion to remove duplicates across the merged list.
$unwind or grouping.$concatArrays WorksField references and literals are evaluated. Null or missing fields become empty arrays.
Elements from array 1 come first, then array 2, and so on. Nested arrays are not flattened.
The result is written to the field you define in $project or $addFields.
Ready for $unwind, $size, $setUnion, or further processing.
The $concatArrays operator is the go-to tool for merging array fields in MongoDB aggregation pipelines. It preserves element order, handles null fields gracefully, and works with any number of input arrays.
For beginners, remember: use $concatArrays for arrays and $concat for strings. Use $setUnion when you need unique values after merging.
$concatArrays when merging list-type fields$setUnion to remove duplicates$size to count merged elements$concat)$concatArrays with $concat$setUnion)$concatArraysUse these points when merging arrays in MongoDB.
Join lists end-to-end.
Purpose{ $concatArrays: [a, b] }
Safe unlike $concat.
BehaviorFirst array, then second.
PropertyArrays, not strings.
ImportantMove on to $cond for conditional logic, or review $concat for string joining.
5 people found this page helpful