MongoDB $indexOfCP Operator

What You’ll Learn

The $indexOfCP operator finds where a substring first appears inside a string, measured in Unicode code points (characters). It returns a zero-based index or -1 when the text is not found. Use it for international text, emoji, and any string work where character positions matter more than byte offsets.

Definition and Usage

In MongoDB’s aggregation framework, the $indexOfCP operator searches a string for the first occurrence of a substring and returns its zero-based code point index. For example, searching "Hello MongoDB" for "Mongo" returns 6. If the substring is absent, the result is -1.

Code points represent Unicode characters. Unlike $indexOfBytes, which counts UTF-8 bytes, $indexOfCP counts characters — so emoji and accented letters each count as one position. This makes it the better choice for human-readable text processing.

📝 Syntax

The $indexOfCP operator takes a string expression, a substring, and optional code point range bounds:

{
  $indexOfCP: [
    <string expression>,
    <substring expression>,
    <start>,   // optional code point offset, default 0
    <end>      // optional code point offset, default string length in CP
  ]
}

Common Patterns

// Basic substring search in a field
{ $indexOfCP: [ "$message", "hello" ] }

// Search from code point 3 onward
{ $indexOfCP: [ "$bio", "developer", 3 ] }

// Check if substring exists (index >= 0)
{ $gte: [
    { $indexOfCP: [ "$comment", "🚀" ] },
    0
] }

Syntax Rules

• First argument — the string to search (field path like "$message" or a literal string).
• Second argument — the substring to find (literal, field reference, or expression).
• start — optional code point offset where the search begins (default 0).
• end — optional code point offset before which the search stops (default string length in code points).
• Returns -1 when the substring is not found in the specified range.
• Indexes are measured in code points, not UTF-8 bytes.
• Use inside stages like $project, $addFields, $set, and $cond.

Examples Gallery

Walk through sample message data, find substring positions with $project, and see why code point indexing matters for Unicode text.

[
  { "_id": ObjectId("609c26812e9274a86871bc6a"), "body": "Welcome to MongoDB tutorials!", "locale": "en" },
  { "_id": ObjectId("609c26812e9274a86871bc6b"), "body": "Launch day 🚀 Let's go!", "locale": "en" },
  { "_id": ObjectId("609c26812e9274a86871bc6c"), "body": "Bienvenue sur CodeToFun", "locale": "fr" }
]

db.messages.aggregate([
  {
    $project: {
      body: 1,
      mongoIndex: {
        $indexOfCP: [ "$body", "MongoDB" ]
      }
    }
  }
])

// "Welcome to MongoDB tutorials!" → mongoIndex: 11
// "Launch day 🚀 Let's go!"       → mongoIndex: -1
// "Bienvenue sur CodeToFun"       → mongoIndex: -1

db.messages.aggregate([
  {
    $project: {
      body: 1,
      rocketIndex: {
        $indexOfCP: [ "$body", "🚀" ]
      },
      rocketIndexBytes: {
        $indexOfBytes: [ "$body", "🚀" ]
      }
    }
  }
])

// "Launch day 🚀 Let's go!"
//   → rocketIndex: 11       (code point position)
//   → rocketIndexBytes: 11  (byte position — may differ for other emoji)

db.messages.aggregate([
  {
    $project: {
      body: 1,
      hasRocket: {
        $gte: [
          { $indexOfCP: [ "$body", "🚀" ] },
          0
        ]
      }
    }
  }
])

// body contains 🚀 → hasRocket: true
// body without 🚀  → hasRocket: false

db.messages.aggregate([
  {
    $project: {
      body: 1,
      messageType: {
        $cond: [
          {
            $gte: [
              { $indexOfCP: [ "$body", "Launch" ] },
              0
            ]
          },
          "promotional",
          "standard"
        ]
      }
    }
  }
])

db.messages.aggregate([
  {
    $addFields: {
      keywordIndex: {
        $indexOfCP: [ "$body", "MongoDB" ]
      }
    }
  },
  {
    $project: {
      body: 1,
      afterKeyword: {
        $cond: [
          { $gte: [ "$keywordIndex", 0 ] },
          {
            $substrCP: [
              "$body",
              { $add: [ "$keywordIndex", 7 ] },
              20
            ]
          },
          null
        ]
      }
    }
  }
])

🚀 Use Cases

• International text — search substrings in multilingual content with correct character positions.
• Emoji and symbols — detect or locate emoji in social posts, comments, and chat messages.
• Keyword detection — flag promotional, spam, or policy-related phrases in message bodies.
• String slicing — pair with $substrCP to extract text after a found keyword.

💡 Best Practices