How to Use $substr in Aggregation in MongoDB

In MongoDB aggregation, use the $substr operator to extract a substring from a string by specifying the string, the start index, and the length. It is used inside the $project or other pipeline stages to manipulate string fields.

Syntax

The $substr operator takes three arguments inside an array: the string to extract from, the starting index (0-based), and the length of the substring.

Example: { $substr: [ , , ] }

• string: The field or string expression to extract from.
• start: The zero-based index to start extraction.
• length: The number of characters to extract.

json

{
  $substr: [ "$fieldName", startIndex, length ]
}

Example

This example shows how to extract the first 5 characters from the name field of documents in a collection using $substr inside a $project stage.

mongodb

db.collection.aggregate([
  {
    $project: {
      name: 1,
      shortName: { $substr: ["$name", 0, 5] }
    }
  }
])

Output

[
  { "_id": ObjectId("..."), "name": "Michael", "shortName": "Micha" },
  { "_id": ObjectId("..."), "name": "Jessica", "shortName": "Jessi" },
  { "_id": ObjectId("..."), "name": "Daniel", "shortName": "Danie" }
]

Common Pitfalls

• Using negative or out-of-range start indexes causes errors.
• Specifying a length longer than the string returns only available characters without error.
• Using $substr on non-string fields causes errors; ensure the field is a string.
• In MongoDB 4.4 and later, $substr is deprecated; use $substrBytes or $substrCP for byte or code point substrings.

json

/* Wrong: negative start index */
{
  $project: { shortName: { $substr: ["$name", -1, 3] } }
}

/* Correct: start index zero or positive */
{
  $project: { shortName: { $substr: ["$name", 0, 3] } }
}

Quick Reference

Operator	Arguments	Description
$substr	[string, start, length]	Extract substring starting at zero-based index for given length
$substrBytes	[string, start, length]	Extract substring by bytes (recommended for binary-safe)
$substrCP	[string, start, length]	Extract substring by Unicode code points

Key Takeaways

Use $substr with three arguments: string, start index, and length inside aggregation pipelines.

Start index is zero-based and must be non-negative to avoid errors.

If length exceeds string length, $substr returns available characters without error.

For MongoDB 4.4+, prefer $substrBytes or $substrCP instead of $substr.

Always ensure the field used with $substr is a string to prevent errors.