The $binarySize operator returns the byte size of a string or BinData value in MongoDB aggregation pipelines. Use it to audit attachments, track storage, or find the largest binary fields.
Measure content in bytes.
One expression inside $binarySize.
Works on both types.
Aggregation expression operator.
Files, storage, auditing.
Field vs whole document.
In MongoDB’s aggregation framework, the $binarySize operator returns how many bytes a string or BinData value occupies. For example, the string "Hello" is 5 bytes, and BinData(0, "SGVsbG8=") (base64 for "Hello") is also 5 bytes.
$binarySize measures one field’s content. To measure an entire document’s BSON footprint, use $bsonSize instead. They answer different questions.
The $binarySize operator takes one expression:
{ $binarySize: <expression> }$binarySize — returns the size in bytes of the expression value.<expression> — must resolve to a string, BinData, or null.$project, $addFields, or $set.null, the result is null.$binarySize only accepts string and BinData values:
$binarySize: "$fileData" → bytes (BinData field)$binarySize: "$title" → bytes (string field)$binarySize: "$tags" → error (array not supported)$binarySize: null → null (safe)| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (data size) |
| Syntax | { $binarySize: <expression> } |
| Accepted types | string, BinData, null |
| Output unit | Bytes (integer) |
| MongoDB version | 4.4+ |
{
$binarySize: "$data"
}File attachment bytes
{
$binarySize: "$title"
}Text field byte length
{
$binarySize: "Hello"
}Returns 5
{
$binarySize: null
}Returns null
Measure binary and string field sizes, find the largest attachment, and sum total bytes across a collection.
Use an images collection with BinData file fields and compute byte sizes with $project.
Suppose you have an images collection storing uploaded files as BinData:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"name": "logo.png",
"binary": BinData(0, "iVBORw0KGgo=")
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"name": "avatar.jpg",
"binary": BinData(0, "/9j/4AAQSkZJRg==")
}
]Return the byte size of each file’s binary data:
db.images.aggregate([
{
$project: {
name: 1,
imageSize: { $binarySize: "$binary" }
}
}
])$binarySize decodes the BinData content and counts its raw bytes. The subtype metadata is not included in the count — only the binary payload size.
Measure string fields, find the largest file, and aggregate total storage.
Strings are also supported. Measure the byte length of text content:
db.posts.aggregate([
{
$project: {
title: 1,
titleSize: { $binarySize: "$title" },
bodySize: { $binarySize: "$body" }
}
}
])
// title: "Hello" → titleSize: 5
// body: "MongoDB" → bodySize: 7For UTF-8 strings, multi-byte characters count as multiple bytes. This is useful when estimating storage or validating field length limits.
Project sizes, sort descending, and return the top result:
db.images.aggregate([
{
$project: {
name: 1,
imageSize: { $binarySize: "$binary" }
}
},
{ $sort: { imageSize: -1 } },
{ $limit: 1 }
])Combine $binarySize with $sort and $limit to quickly identify the heaviest binary field in a collection.
Calculate total bytes stored across all documents:
db.images.aggregate([
{
$project: {
imageSize: { $binarySize: "$binary" }
}
},
{
$group: {
_id: null,
totalBytes: { $sum: "$imageSize" },
fileCount: { $sum: 1 },
avgBytes: { $avg: "$imageSize" }
}
}
])Project the byte size per document, then use $group with $sum and $avg for collection-level storage statistics. Documents with a null binary field contribute 0 to the sum.
$binarySize WorksThe pipeline evaluates the expression — typically a field like "$binary" or "$title".
MongoDB measures the raw content length of the string or BinData value. Unsupported types trigger an error.
The integer result is written to the field you define in $project or $addFields.
Sort, filter, sum, or average the byte counts in later pipeline stages.
The $binarySize operator is a practical tool for measuring string and BinData field sizes in MongoDB aggregation pipelines. It answers a simple question: how many bytes does this field contain?
For beginners, remember: it works on strings and BinData only, returns bytes as an integer, and is different from $bsonSize which measures entire documents.
$binarySize for individual string or BinData fields$sort to find the largest attachments$sum in $group for total storage reports$bsonSize when you need whole-document size$binarySize$binarySize with $bsonSize$binarySizeUse these points when measuring data sizes in MongoDB.
Counts content in bytes.
Purpose{ $binarySize: expr }
Two supported types.
InputAggregation operator.
VersionField vs document.
ImportantMove on to $bsonSize for whole-document BSON size, or review $arrayElemAt for array access.
5 people found this page helpful