MongoDB $substr Operator

What You’ll Learn

The $substr operator extracts part of a string starting at a zero-based index for a given length. Use it to pull prefixes, suffixes, IDs, and fixed-width segments from text fields in aggregation pipelines.

Definition and Usage

In MongoDB’s aggregation framework, the $substr operator returns a substring of a string. You specify where to start (zero-based index) and how many characters to include. For example, { $substr: [ "hello world", 0, 5 ] } returns "hello".

This is similar to JavaScript’s String.substring() or String.slice(). MongoDB also offers $substrBytes (byte positions) and $substrCP (code-point positions) for more precise Unicode handling.

📝 Syntax

The $substr operator takes a string, start index, and length:

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

Literal Examples

{ $substr: [ "hello world", 0, 5 ] }
// Result: "hello"

{ $substr: [ "hello world", 6, 5 ] }
// Result: "world"

{ $substr: [ "MongoDB", 0, 5 ] }
// Result: "Mongo"

Syntax Rules

• First argument — string expression (field path or literal).
• Second argument — zero-based start index (integer).
• Third argument — number of characters to extract.
• Use inside $project, $addFields, or $set.
• Start beyond string length — returns "" (empty string).
• null string — returns null.

Examples Gallery

Extract prefixes, pull fixed-width codes, skip headers, and mask sensitive values with $substr.

[
  { "_id": 1, "sku": "ELEC-00123", "description": "Wireless Mouse" },
  { "_id": 2, "sku": "BOOK-00456", "description": "MongoDB Guide" },
  { "_id": 3, "sku": "FOOD-00789", "description": "Organic Tea" }
]

db.products.aggregate([
  {
    $project: {
      description: 1,
      shortDesc: {
        $substr: [ "$description", 0, 5 ]
      }
    }
  }
])

// "Wireless Mouse" → shortDesc: "Wirel"
// "MongoDB Guide"    → shortDesc: "Mongo"
// "Organic Tea"      → shortDesc: "Organ"

db.products.aggregate([
  {
    $project: {
      sku: 1,
      category: {
        $substr: [ "$sku", 0, 4 ]
      }
    }
  }
])

// "ELEC-00123" → category: "ELEC"
// "BOOK-00456" → category: "BOOK"

db.orders.aggregate([
  {
    $project: {
      orderRef: 1,
      localRef: {
        $substr: [ "$orderRef", 5, 10 ]
      }
    }
  }
])

// orderRef: "US-ORD-12345"
// Skip "US-OR" (5 chars), take next 10 → "D-12345" (depends on length param)

db.users.aggregate([
  {
    $project: {
      phone: 1,
      masked: {
        $concat: [
          "****",
          {
            $substr: [
              "$phone",
              { $subtract: [ { $strLenCP: "$phone" }, 4 ] },
              4
            ]
          }
        ]
      }
    }
  }
])

// "5551234567" → masked: "****4567"

db.samples.aggregate([
  {
    $project: {
      greeting: { $substr: [ "hello world", 0, 5 ] },
      target:   { $substr: [ "hello world", 6, 5 ] }
    }
  }
])

// greeting: "hello"
// target:   "world"

🚀 Use Cases

• Fixed-width parsing — extract category codes, region prefixes, or legacy ID segments.
• Display truncation — show a short preview of long text fields in reports.
• Data masking — hide all but the last few digits of phone numbers or account IDs.
• Normalization — strip known prefixes before matching or grouping.

💡 Best Practices