MongoDB $concat Operator

Beginner
5 min read
Updated: Oct 2026
3 examples
Live preview
MongoDB $concat tutorial — join strings in aggregation pipelines
Definition

What Is $concat?

$concat is a MongoDB aggregation expression that joins multiple strings into one. Pass an array of pieces—fields, literals, or other string expressions. If any piece is null or missing, the whole result is null.

Remember
$concat = join strings in aggregation

{ $concat: [ <expr1>, <expr2>, ... ] }

pieces → strings only (use $toString for numbers)
space  → include " " as a literal if you need one
null   → any null/missing piece → whole result null
fix → wrap fields with $ifNull(field, "")
UsePrefer
Join strings into one string$concat
Join arrays into one array$concatArrays
Number → string first$toString
Approach

How to Use $concat in MongoDB

List the string pieces in order, including any separators you want between them.

  1. Choose an expression stage ($addFields or $project).
  2. Build an array: fields, literals (like " "), and other string expressions.
  3. Pass that array to $concat.
  4. If a field can be missing, wrap it with $ifNull.
PieceRequired?Role
$concatYesJoin string expressions
Array of expressionsYesOrdered pieces to glue together
$ifNull / $toStringNoNull-safe fields / convert non-strings

Pseudocode

Pseudocode
for each document:
    parts = evaluate each expression in [expr1, expr2, ...]
    if any part is null or missing:
        result = null
    else:
        result = join(parts)   // no separator unless you included one
    emit { ..., field: result }
Reference

Cheat Sheet

Keep these facts handy while writing string-join expressions.

TopicDetail
TypeAggregation expression (not a find filter)
Syntax{ $concat: [ <a>, <b>, ... ] }
InputStrings only
Null ruleAny null/missing → result null
Full-name pattern$concat: ["$first", " ", "$last"]
Null-safe pattern$ifNull: ["$middle", ""] inside the array
Sample check"Ada" + " " + "Lovelace" → "Ada Lovelace"
Try it

Live Preview

Watch $concat join first name, a separator, and last name.

Simulates $concat with three string pieces (same idea as the mongosh examples below).

Result
pieces = ["Ada", " ", "Lovelace"]
$concat → "Ada Lovelace"

{ full_name: "Ada Lovelace" }
Trace

Worked Walkthrough — Full Name

One person document with first and last. We want a single full_name string with a space in the middle.

Calculation
Document:
  { first: "Ada", last: "Lovelace" }

$concat: ["$first", " ", "$last"]

Step by step:
  1) "$first" → "Ada"
  2) " "     → " "          (literal space)
  3) "$last" → "Lovelace"
  4) join    → "Ada Lovelace"

Check: three pieces, one result string ✓
Code

MongoDB Examples

We use one person document. First we store the name parts, then we build a full name, then we build a label with a hyphen. Run these in mongosh after inserting the sample data once.

Example 1 — Sample Data

Imagine one person: first name Ada, last name Lovelace. We save those two strings as one document in a collection named people.

mongosh
db.people.insertOne({
  _id: 1,
  first: "Ada",
  last: "Lovelace"
});

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps one document in people. Run find() to see it:

mongosh
db.people.find()

Read that document like this:

Field in MongoDBValuePlain English
_id1Document id (row number for this lesson)
first"Ada"First name string
last"Lovelace"Last name string
Picture
Name parts stored separately:

  first: "Ada"
  last:  "Lovelace"

Goal for the next examples:
  join them into one display string
  with either a space or a hyphen in between

How It Works

  1. Insert once. insertOne adds a single person document to people.
  2. MongoDB stores fields as written. first and last are just strings.
  3. find() shows the same shape. What you inserted is what you get back—ready for $concat in the next examples.

Example 2 — Full Name

Goal: build full_name as first + space + last.

mongosh
db.people.aggregate([
  {
    $addFields: {
      full_name: {
        $concat: ["$first", " ", "$last"]
      }
    }
  }
]);

How It Works

  1. Read the stored strings. MongoDB already has first: "Ada" and last: "Lovelace" from Example 1.
  2. Include a space literal. The middle piece " " is not a field—it is written into the array on purpose.
  3. Join in order. $concat glues the three pieces into "Ada Lovelace".
  4. Keep all fields. $addFields adds full_name next to the original name parts—nothing is deleted.

Example 3 — Hyphen Label

Same person, but use a hyphen instead of a space for a compact label.

mongosh
db.people.aggregate([
  {
    $addFields: {
      label: {
        $concat: ["$first", "-", "$last"]
      }
    }
  }
]);

How It Works

  1. Same stored document. Still using Ada / Lovelace from Example 1.
  2. Change only the separator. Replace " " with "-" in the array.
  3. Join again. Result becomes "Ada-Lovelace".
  4. Easy check. Separators are just more string pieces—you control spacing by what you put in the array.

Edge Cases & Pitfalls

Check these before using $concat in production pipelines.

null

One null makes the whole result null

Missing or null fields do not skip themselves. Wrap with $ifNull and "" when you still want a partial string.

type

Strings only

Numbers and dates are not auto-converted. Use $toString (or $dateToString) first.

space

Spaces are not automatic

$concat does not insert separators. Add " ", "-", or ", " yourself as array items.

arrays

Not for array joining

To merge arrays, use $concatArrays. $concat is string-only.

Analysis

Performance Notes

ApproachCostBest for
$concat alonePer-document string workDisplay names, labels, keys
+ $ifNull wrappersSmall extra costOptional / sparse name parts
+ $toStringOne conversion per valueMixing numbers into labels

String joins are cheap compared with large sorts or joins. Filter early with $match when only some documents need a computed label.

Remember

Key Takeaways

  • Role: join string pieces into one string.
  • Separators: add " " or "-" yourself in the array.
  • Nulls: one null/missing piece → whole result null.
  • Types: strings only—convert with $toString first.

One line: $concat answers “glue these strings together in order”—and returns null if any piece is null.

Frequently Asked Questions

$concat joins multiple string values into one string. Pass an array of expressions—field references, string literals, or other string expressions—inside aggregation stages such as $project and $addFields.
The syntax is { $concat: [ <expression1>, <expression2>, ... ] }. Include as many pieces as you need, including literal separators like a space or hyphen.
If any expression evaluates to null or a missing field, $concat returns null for the whole result. Wrap risky fields with $ifNull to fall back to an empty string.
No. $concat only accepts strings. Convert numbers first with $toString, then pass them into $concat.
$concat joins strings into one string. $concatArrays joins arrays into one array. Same idea, different data types.
Yes in spirit. Think of $concat as MongoDB’s aggregation version of joining strings—run it in the pipeline, not as a standalone find() filter.

Next: $concatArrays

Join multiple arrays into one array in an aggregation pipeline.

$concatArrays tutorial →

About the author

Mari Selvan M P
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)

9 people found this page helpful

MongoDB $comment Operator MongoDB $concatArrays Operator