$binarySize is a MongoDB aggregation expression that returns the size in bytes of a string or BinData value. For strings it counts UTF-8 bytes (not characters). For BinData it counts the raw binary payload.
Confirm the field is a string or BinData (not an array or number).
Pass that field to $binarySize to get an integer byte count.
Optionally $sort / $limit to find the largest values.
Piece
Required?
Role
$binarySize
Yes
Byte length of string or BinData
Expression
Yes
Field, literal, or nested expression
$sort / $limit
No
Find the largest attachment or text
Pseudocode
Pseudocode
for each document:
v = evaluate(expression)
if v is null or missing:
result = null
else if v is string:
result = utf8_byte_length(v)
else if v is BinData:
result = length(v.payload) // not the subtype
else:
error // aggregation fails
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while measuring field sizes.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $binarySize: <expression> }
Accepted
string, BinData, null
Output
Integer bytes (or null)
Empty value
"" or empty BinData → 0
UTF-8 tip
"café" → 5 bytes (not 4)
Version
MongoDB 4.4+
Try it
Live Preview
Watch $binarySize count UTF-8 bytes for a string. Notice that some characters need more than one byte.
Simulates $binarySize on a string (same idea as the mongosh examples below).
Easy check. Two ASCII/Latin titles are 5 bytes; the CJK title is 6—so it wins.
Edge Cases & Pitfalls
Check these before using $binarySize in production pipelines.
types
Only string and BinData
Arrays, numbers, and objects make the pipeline fail. Validate the type or use $cond / $type first.
utf-8
Bytes ≠ characters
Do not treat the result as a character count. For visible length, use $strLenCP.
null
Null and missing become null
Missing fields return null, not 0. Empty strings return 0. Handle both when summing sizes.
scope
Not whole-document size
$binarySize measures one field’s content. For the full BSON document, use $bsonSize.
Analysis
Performance Notes
Approach
Cost
Best for
$binarySize alone
Per-document scan of field bytes
Auditing one string/BinData field
+ $sort / $limit
Still O(docs) + sort
Finding the heaviest attachments
+ $group / $sum
O(docs)
Total storage reports
Measuring bytes is cheap compared with large joins. Filter early with $match when only some documents need a size check.
Remember
Key Takeaways
Role: byte length of a string or BinData value.
Inputs: string, BinData, or null only.
UTF-8: characters may cost 1–4 bytes each.
Scope: one field—use $bsonSize for whole documents.
One line:$binarySize answers “how many bytes is this string or BinData?”—not how many characters, and not how big the whole document is.
Frequently Asked Questions
$binarySize returns the size in bytes of a string or BinData value. Use it inside aggregation expression stages such as $project and $addFields.
The argument must resolve to a string, BinData, or null. Arrays, numbers, objects, and other BSON types cause the aggregation to fail with an error.
For strings, both count UTF-8 bytes. Prefer $binarySize when the field may be BinData or string. Prefer $strLenBytes when you only ever measure strings.
$binarySize measures one string or BinData field’s content. $bsonSize measures the full BSON-encoded size of a document or object, including field names and type metadata.
$binarySize returns null when the input is null or the field is missing. Empty strings and empty BinData return 0, not null.
MongoDB stores strings as UTF-8. ASCII letters use 1 byte each, but characters like é, λ, or emoji may use 2–4 bytes. $binarySize counts bytes, not visible characters.
