MongoDB $indexOfBytes Operator

What You’ll Learn

The $indexOfBytes operator finds where a substring first appears inside a string, measured in bytes. It returns a zero-based byte index or -1 when the text is not found. Use it in aggregation pipelines for URL checks, keyword detection, and text parsing.

Definition and Usage

In MongoDB’s aggregation framework, the $indexOfBytes operator searches a string for the first occurrence of a substring and returns its zero-based byte index. For example, searching "Hello MongoDB" for "Mongo" returns 6 (the byte position where "Mongo" starts). If the substring is absent, the result is -1.

Byte indexing matters because UTF-8 characters can use more than one byte. For plain ASCII text, byte indexes match character positions. When working with emoji or international text, consider $indexOfCP for code-point-based indexing instead.

📝 Syntax

The $indexOfBytes operator takes a string expression, a substring, and optional byte range bounds:

{
  $indexOfBytes: [
    <string expression>,
    <substring expression>,
    <start>,   // optional byte offset, default 0
    <end>      // optional byte offset, default string byte length
  ]
}

Common Patterns

// Basic substring search in a field
{ $indexOfBytes: [ "$title", "MongoDB" ] }

// Search from byte offset 5 onward
{ $indexOfBytes: [ "$url", "/", 8 ] }

// Check if substring exists (index >= 0)
{ $gte: [
    { $indexOfBytes: [ "$email", "@" ] },
    0
] }

Syntax Rules

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

Examples Gallery

Walk through sample document data, find substring positions with $project, and combine $indexOfBytes with other operators for practical text checks.

[
  { "_id": ObjectId("609c26812e9274a86871bc6a"), "title": "Learn MongoDB Basics", "url": "https://codetofun.com/mongodb" },
  { "_id": ObjectId("609c26812e9274a86871bc6b"), "title": "JavaScript Arrays Guide", "url": "https://codetofun.com/js/arrays" },
  { "_id": ObjectId("609c26812e9274a86871bc6c"), "title": "CSS Flexbox Tutorial", "url": "https://codetofun.com/css/flexbox" }
]

db.pages.aggregate([
  {
    $project: {
      title: 1,
      mongoIndex: {
        $indexOfBytes: [ "$title", "MongoDB" ]
      }
    }
  }
])

// "Learn MongoDB Basics"  → mongoIndex: 6
// "JavaScript Arrays Guide" → mongoIndex: -1
// "CSS Flexbox Tutorial"    → mongoIndex: -1

db.pages.aggregate([
  {
    $project: {
      url: 1,
      pathSlashIndex: {
        $indexOfBytes: [
          "$url",
          "/",
          8
        ]
      }
    }
  }
])

// "https://codetofun.com/mongodb"
//   → pathSlashIndex: 20 (first "/" after "https://")

// Skipping "https://" avoids matching the slashes in the protocol

db.pages.aggregate([
  {
    $project: {
      title: 1,
      mentionsMongoDB: {
        $gte: [
          { $indexOfBytes: [ "$title", "MongoDB" ] },
          0
        ]
      }
    }
  }
])

// title contains "MongoDB" → mentionsMongoDB: true
// title without "MongoDB"  → mentionsMongoDB: false

db.pages.aggregate([
  {
    $project: {
      title: 1,
      url: 1,
      linkType: {
        $cond: [
          {
            $gte: [
              { $indexOfBytes: [ "$url", "codetofun.com" ] },
              0
            ]
          },
          "internal",
          "external"
        ]
      }
    }
  }
])

db.users.aggregate([
  {
    $project: {
      email: 1,
      hasAtSymbol: {
        $gte: [
          { $indexOfBytes: [ "$email", "@" ] },
          1
        ]
      }
    }
  }
])

🚀 Use Cases

• Keyword detection — check whether titles, descriptions, or logs contain specific text.
• URL and path parsing — locate slashes, domains, or file extensions in URL strings.
• Data validation — verify that required symbols (like @ in emails) appear at expected positions.
• Conditional labeling — drive $cond logic based on whether a substring is present.

💡 Best Practices