MongoDB $substr Operator

What Is $substr?

$substr is a MongoDB aggregation expression that returns a substring starting at a zero-based index for a given length. It is deprecated since 3.4 and is an alias for $substrBytes. Prefer $substrBytes or $substrCP in new code.

$substr ≈ $substrBytes (legacy alias)

{ $substr: [ <string>, <start>, <length> ] }

"13Q1" + start 0, length 2 → "13"
"13Q1" + start 2, length -1 → "Q1"  (rest of string)

negative start → ""
ASCII-safe; for Unicode chars prefer $substrCP

How to Use $substr in MongoDB

Pass the string, a start index, and a length (or -1 for the remainder).

1. Choose an expression stage ($addFields or $project).
2. Pass the string expression as the first argument.
3. Set start (0-based). Negative start returns "".
4. Set length, or use -1 to take everything from start to the end.

Pseudocode

for each document:
    s = evaluate(string)
    start = evaluate(startIndex)
    len = evaluate(length)
    if start < 0:
        result = ""
    else if len < 0:
        result = s from start to end
    else:
        result = s from start for len units
    emit { ..., field: result }

Cheat Sheet

Keep these facts handy while extracting substrings.

Live Preview

Watch $substr cut a quarter code into year and quarter parts. Try the rest-of-string pattern with length -1.

string = "13Q1"
start  = 0
length = 2

$substr → "13"

{ year: "13" }

Worked Walkthrough — 13Q1

A quarter code stores year digits then a quarter label. We pull "13" and "Q1" with two $substr calls.

String: "13Q1"
Index:   0 1 2 3
Chars:   1 3 Q 1

Year:
  $substr(["$quarter", 0, 2]) → "13"

Quarter (rest):
  $substr(["$quarter", 2, -1]) → "Q1"

Check: "13" + "Q1" = "13Q1" ✓

MongoDB Examples

We store one inventory item with quarter code 13Q1. First we extract the year, then the rest of the string. Run these in mongosh after inserting the sample data once.

db.inventory.insertOne({
  _id: 1,
  item: "ABC1",
  quarter: "13Q1"
});

db.inventory.find()

[
  {
    _id: 1,
    item: "ABC1",
    quarter: "13Q1"
  }
]

quarter: 1 3 Q 1
index:   0 1 2 3

[0..2)  → "13"   year
[2..end] → "Q1"  quarter label

db.inventory.aggregate([
  {
    $addFields: {
      year: {
        $substr: ["$quarter", 0, 2]
      }
    }
  }
]);

{
  _id: 1,
  item: "ABC1",
  quarter: "13Q1",
  year: "13"
}

db.inventory.aggregate([
  {
    $addFields: {
      year: { $substr: ["$quarter", 0, 2] },
      qtr: { $substr: ["$quarter", 2, -1] }
    }
  }
]);

{
  _id: 1,
  item: "ABC1",
  quarter: "13Q1",
  year: "13",
  qtr: "Q1"
}

Performance Notes

Substring extraction is cheap for short strings. If you filter on year often, store year as its own field. Filter early with $match when only some documents need slicing.

Key Takeaways