MongoDB $substrCP Operator

What You’ll Learn

The $substrCP operator extracts part of a string using Unicode code-point positions. It is the recommended way to slice text when emoji, accents, and international characters must count as single characters.

Definition and Usage

In MongoDB’s aggregation framework, the $substrCP operator returns a substring starting at a zero-based code-point index for a given code-point length. CP stands for code points — the Unicode units that roughly match visible characters. For example, { $substrCP: [ "hello", 0, 3 ] } returns "hel".

Use $substrCP for tweet-style character limits, title previews, and any user-facing truncation. Use $substrBytes when you need storage-byte positions instead. Pair with $strLenCP to measure length before slicing.

📝 Syntax

The $substrCP operator takes a string, code-point start index, and code-point length:

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

Literal Examples

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

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

{ $substrCP: [ "Hi 👋", 0, 4 ] }
// Result: "Hi 👋"  (emoji counts as 1 code point)

Syntax Rules

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

Examples Gallery

Slice strings by visible character count, truncate posts safely with emoji, and compare with byte-based extraction.

[
  { "_id": 1, "title": "Hello World", "body": "Short update today." },
  { "_id": 2, "title": "MongoDB 🚀", "body": "Learning aggregation pipelines!" },
  { "_id": 3, "title": "café culture", "body": "Unicode and emoji 👋 work fine." }
]

db.posts.aggregate([
  {
    $project: {
      title: 1,
      titlePreview: {
        $substrCP: [ "$title", 0, 5 ]
      }
    }
  }
])

// "Hello World"  → titlePreview: "Hello"
// "MongoDB 🚀"   → titlePreview: "Mongo"
// "café culture" → titlePreview: "café "

db.posts.aggregate([
  {
    $project: {
      body: 1,
      snippet: {
        $substrCP: [ "$body", 0, 4 ]
      }
    }
  }
])

// "Unicode and emoji 👋 work fine."
// snippet: "Unic"  (4 code points)

// Compare: $substrBytes at byte 4 might split a multi-byte character

db.posts.aggregate([
  {
    $project: {
      title: 1,
      bodyPreview: {
        $substrCP: [ "$body", 0, 50 ]
      },
      fullLength: {
        $strLenCP: "$body"
      }
    }
  }
])

db.posts.aggregate([
  {
    $project: {
      body: 1,
      byCodePoints: {
        $substrCP: [ "$body", 0, 20 ]
      },
      byBytes: {
        $substrBytes: [ "$body", 0, 20 ]
      }
    }
  }
])

// On text with emoji, byte slice may end mid-character
// Code-point slice always ends on character boundaries

db.users.aggregate([
  {
    $project: {
      username: 1,
      suffix: {
        $substrCP: [
          "$username",
          { $subtract: [ { $strLenCP: "$username" }, 4 ] },
          4
        ]
      }
    }
  }
])

// "developer123" → suffix: "r123"

🚀 Use Cases

• Display previews — show the first N characters of posts, comments, or descriptions in lists.
• Character limits — enforce tweet-style or form-field max character counts.
• International content — slice text with accents, CJK characters, and emoji without corruption.
• Data cleanup — extract fixed segments from user-generated text for reporting.

💡 Best Practices