MongoDB $strLenCP Operator

What You’ll Learn

The $strLenCP operator returns how many Unicode code points (visible characters) a string contains. Use it for user-facing character limits, form validation, and display rules where emoji and international text count as one character each.

Definition and Usage

In MongoDB’s aggregation framework, the $strLenCP operator counts the number of Unicode code points in a string. A code point is roughly what a user sees as one character on screen. For example, { $strLenCP: "hello" } returns 5, and { $strLenCP: "Hi 👋" } returns 4 (H, i, space, wave emoji).

This differs from $strLenBytes, which counts UTF-8 storage bytes. When you enforce a “280 character” post limit or a “50 character” title rule, $strLenCP is the right choice.

📝 Syntax

The $strLenCP operator takes one string expression:

{ $strLenCP: <string expression> }

Literal Examples

{ $strLenCP: "hello" }
// Result: 5

{ $strLenCP: "Hi 👋" }
// Result: 4  (emoji = 1 code point)

{ $strLenCP: "$title" }
// Code-point length of the title field

Syntax Rules

• $strLenCP — returns an integer code-point count.
• <string expression> — field path, literal, or nested string expression.
• Use inside $project, $addFields, $set, or $match with $expr.
• CP stands for code points (Unicode character units).
• Empty string — returns 0.
• null input — returns null.

Examples Gallery

Count visible characters on ASCII and emoji strings, enforce character limits, and compare with byte-based length.

[
  { "_id": 1, "title": "Hello World", "body": "Short post." },
  { "_id": 2, "title": "MongoDB 🚀", "body": "Learning aggregation today!" },
  { "_id": 3, "title": "café", "body": "Unicode text with accents." },
  { "_id": 4, "title": "Hi 👋", "body": "Wave emoji in title." }
]

db.posts.aggregate([
  {
    $project: {
      title: 1,
      titleLength: { $strLenCP: "$title" }
    }
  }
])

// "Hello World"  → titleLength: 11
// "MongoDB 🚀"   → titleLength: 9   (emoji = 1 char)
// "café"         → titleLength: 4
// "Hi 👋"        → titleLength: 4

db.posts.aggregate([
  {
    $project: {
      title: 1,
      chars:  { $strLenCP: "$title" },
      bytes:  { $strLenBytes: "$title" }
    }
  }
])

// "Hi 👋"       → chars: 4,  bytes: 7
// "Hello World" → chars: 11, bytes: 11

db.posts.aggregate([
  {
    $match: {
      $expr: {
        $gt: [
          { $strLenCP: "$body" },
          280
        ]
      }
    }
  },
  {
    $project: {
      title: 1,
      charCount: { $strLenCP: "$body" }
    }
  }
])

db.posts.aggregate([
  {
    $addFields: {
      titleLength: { $strLenCP: "$title" },
      titleTooLong: {
        $gt: [
          { $strLenCP: "$title" },
          50
        ]
      }
    }
  }
])

// title under 50 chars → titleTooLong: false
// title over 50 chars  → titleTooLong: true

db.posts.aggregate([
  {
    $project: {
      title: 1,
      charsUsed: { $strLenCP: "$body" },
      charsRemaining: {
        $subtract: [
          280,
          { $strLenCP: "$body" }
        ]
      }
    }
  }
])

🚀 Use Cases

• User-facing character limits — enforce max title, bio, or post length the way users count characters.
• Form validation — flag documents where input exceeds allowed character counts.
• Content moderation — find unusually long fields for review or truncation.
• Analytics — report average post length in characters for dashboards.

💡 Best Practices