MongoDB $substrBytes Operator

What You’ll Learn

The $substrBytes operator extracts part of a string using byte offsets in UTF-8 encoding. Use it when storage size, index limits, or wire-protocol byte constraints matter more than visible character count.

Definition and Usage

In MongoDB’s aggregation framework, the $substrBytes operator returns a substring starting at a zero-based byte index for a given byte length. For example, on ASCII text { $substrBytes: [ "hello", 0, 3 ] } returns "hel" (3 bytes = 3 characters).

This is the modern replacement for the legacy $substr operator. Pair it with $strLenBytes when you need to truncate text to a maximum storage size, or use $substrCP when slicing by visible characters instead.

📝 Syntax

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

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

Literal Examples

{ $substrBytes: [ "hello", 0, 3 ] }
// Result: "hel"  (3 bytes)

{ $substrBytes: [ "hello", 1, 3 ] }
// Result: "ell"  (skip 1 byte, take 3)

{ $substrBytes: [ "$text", 0, 100 ] }
// First 100 bytes of the text field

Syntax Rules

• First argument — string expression (field path or literal).
• Second argument — zero-based byte start index (integer).
• Third argument — number of bytes to extract.
• Use inside $project, $addFields, or $set.
• Start beyond string byte length — returns "".
• Avoid splitting mid-character in UTF-8 unless you understand the byte layout.
• null string — returns null.

Examples Gallery

Slice strings by byte offset on ASCII and UTF-8 text, truncate to storage limits, and compare with code-point slicing.

[
  { "_id": 1, "message": "INFO: Server started" },
  { "_id": 2, "message": "ERROR: Connection failed" },
  { "_id": 3, "message": "café au lait" },
  { "_id": 4, "message": "Hi 👋 MongoDB" }
]

db.logs.aggregate([
  {
    $project: {
      message: 1,
      payload: {
        $substrBytes: [ "$message", 6, 20 ]
      }
    }
  }
])

// "INFO: Server started"  → payload: "Server started"
// "ERROR: Connection failed" → payload: "Connection failed"
// (ASCII: 1 char = 1 byte, so byte offsets match character positions)

db.logs.aggregate([
  {
    $project: {
      message: 1,
      preview: {
        $substrBytes: [ "$message", 0, 100 ]
      },
      byteLength: {
        $strLenBytes: "$message"
      }
    }
  }
])

db.logs.aggregate([
  {
    $project: {
      message: 1,
      first3Bytes: {
        $substrBytes: [ "$message", 0, 3 ]
      },
      bytes: { $strLenBytes: "$message" },
      chars: { $strLenCP: "$message" }
    }
  }
])

// "café" → first3Bytes: "caf" (stops before full é)
// bytes: 5, chars: 4

db.logs.aggregate([
  {
    $project: {
      message: 1,
      byBytes: {
        $substrBytes: [ "$message", 0, 4 ]
      },
      byCodePoints: {
        $substrCP: [ "$message", 0, 4 ]
      }
    }
  }
])

// "Hi 👋 MongoDB"
// byBytes:      first 4 bytes  → "Hi �" (may split emoji)
// byCodePoints: first 4 chars  → "Hi 👋"

db.orders.aggregate([
  {
    $project: {
      orderId: 1,
      suffix: {
        $substrBytes: [
          "$orderId",
          { $subtract: [ { $strLenBytes: "$orderId" }, 4 ] },
          4
        ]
      }
    }
  }
])

// "ORD-12345678" → suffix: "5678"

🚀 Use Cases

• Storage truncation — cap string fields to a maximum byte size before indexing or export.
• Index key limits — preview or trim values approaching MongoDB index key byte limits.
• Log parsing — skip fixed-width ASCII headers in log lines by byte offset.
• Legacy compatibility — explicit replacement for the deprecated $substr operator.

💡 Best Practices