MongoDB $strLenBytes Operator

What You’ll Learn

The $strLenBytes operator returns how many bytes a string occupies in UTF-8 encoding. Use it for storage validation, index size checks, and any scenario where byte length matters more than visible character count.

Definition and Usage

In MongoDB’s aggregation framework, the $strLenBytes operator counts the number of bytes in a string. MongoDB stores strings as BSON UTF-8, so plain ASCII characters use one byte each, while accented letters, CJK characters, and emoji may use two, three, or four bytes per character.

For example, { $strLenBytes: "hello" } returns 5. A string with emoji can have fewer visible characters but more bytes. When you need character count instead, use $strLenCP (code points).

📝 Syntax

The $strLenBytes operator takes one string expression:

{ $strLenBytes: <string expression> }

Literal Examples

{ $strLenBytes: "hello" }
// Result: 5  (5 ASCII bytes)

{ $strLenBytes: "café" }
// Result: 5  (é uses 2 bytes in UTF-8)

{ $strLenBytes: "$message" }
// Byte length of the message field

Syntax Rules

• $strLenBytes — returns an integer byte count.
• <string expression> — field path, literal, or nested string expression.
• Use inside $project, $addFields, $set, or $match with $expr.
• ASCII characters — typically 1 byte each.
• Multi-byte UTF-8 characters — 2–4 bytes each.
• null input — returns null.

Examples Gallery

Measure byte length on ASCII and UTF-8 strings, filter by size limits, and compare with character-based length.

[
  { "_id": 1, "text": "Hello" },
  { "_id": 2, "text": "MongoDB rocks!" },
  { "_id": 3, "text": "café" },
  { "_id": 4, "text": "Hi 👋" }
]

db.messages.aggregate([
  {
    $project: {
      text: 1,
      byteLength: { $strLenBytes: "$text" }
    }
  }
])

// "Hello"         → byteLength: 5
// "MongoDB rocks!" → byteLength: 14
// "café"           → byteLength: 5  (é = 2 bytes)
// "Hi 👋"          → byteLength: 7  (emoji = 4 bytes)

db.messages.aggregate([
  {
    $project: {
      text: 1,
      bytes:    { $strLenBytes: "$text" },
      codePoints: { $strLenCP: "$text" }
    }
  }
])

// "Hi 👋"  → bytes: 7,  codePoints: 4
// "Hello"  → bytes: 5,  codePoints: 5

db.messages.aggregate([
  {
    $match: {
      $expr: {
        $gt: [
          { $strLenBytes: "$text" },
          280
        ]
      }
    }
  },
  {
    $project: {
      text: 1,
      byteLength: { $strLenBytes: "$text" }
    }
  }
])

db.messages.aggregate([
  {
    $addFields: {
      byteLength: { $strLenBytes: "$text" },
      withinLimit: {
        $lte: [
          { $strLenBytes: "$text" },
          100
        ]
      }
    }
  }
])

// text under 100 bytes → withinLimit: true
// text over 100 bytes  → withinLimit: false

db.messages.aggregate([
  {
    $project: {
      emptyLen: { $strLenBytes: "" },
      nullLen:  { $strLenBytes: null },
      safeLen:  {
        $strLenBytes: {
          $ifNull: [ "$text", "" ]
        }
      }
    }
  }
])

// ""   → 0
// null → null
// $ifNull guards missing fields

🚀 Use Cases

• Storage validation — enforce maximum byte size before writing to MongoDB or an external API.
• Index key sizing — check whether a string field approaches index key byte limits.
• International content — measure UTF-8 footprint for multilingual apps.
• Data quality reports — flag unusually long fields for cleanup or truncation.

💡 Best Practices