The $bsonSize operator returns how many bytes a document or object occupies when encoded as BSON. Use $$ROOT to measure the entire current document, or pass a subdocument field to audit nested data.
Full encoded size.
One object expression.
Measure whole document.
Aggregation operator.
Storage, limits, tuning.
Document vs one field.
In MongoDB’s aggregation framework, the $bsonSize operator calculates the BSON-encoded size of an object in bytes. This includes field names, BSON type markers, and values — not just the raw data payload. A small document with long field names can be larger than you expect.
MongoDB enforces a 16 MB maximum document size. Use { $bsonSize: "$$ROOT" } to check how close documents are to that limit before inserts or schema changes.
The $bsonSize operator takes one object expression:
{ $bsonSize: <object> }$bsonSize — returns the BSON-encoded size in bytes.<object> — must resolve to an object (document) or null.$$ROOT to reference the entire document in the current pipeline stage."$metadata" to measure a nested subdocument.null, the result is null.Both measure bytes, but at different scopes:
{ name: "Hi", data: BinData(...) }$bsonSize: "$$ROOT" → full document bytes$binarySize: "$data" → binary payload bytes only| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (data size) |
| Syntax | { $bsonSize: <object> } |
| Whole document | { $bsonSize: "$$ROOT" } |
| Output unit | Bytes (integer) |
| MongoDB version | 4.4+ |
{
$bsonSize: "$$ROOT"
}Current document size
{
$bsonSize: "$meta"
}Nested object size
16 * 1024 * 1024Max document bytes
{
$bsonSize: null
}Returns null
Measure document sizes, audit subdocuments, find the largest records, and sum total BSON storage across a collection.
Use an employees collection and measure each document’s BSON size with $$ROOT.
Suppose you have an employees collection:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"name": "Alice",
"department": "Engineering",
"skills": ["MongoDB", "Node.js", "React"]
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"name": "Bob",
"department": "Sales",
"metadata": { "region": "US", "quota": 50000, "notes": "Top performer" }
}
]Return the BSON size of each document currently being processed:
db.employees.aggregate([
{
$project: {
name: 1,
objectSize: { $bsonSize: "$$ROOT" }
}
}
])$$ROOT refers to the whole document at the current pipeline stage. $bsonSize serializes it as BSON and counts every byte, including _id, field names, and array structure.
Measure subdocuments, find outliers, and aggregate total collection size.
Check how much space a nested object consumes without counting the rest of the document:
db.employees.aggregate([
{
$project: {
name: 1,
metadataSize: { $bsonSize: "$metadata" },
rootSize: { $bsonSize: "$$ROOT" }
}
}
])
// Alice (no metadata) → metadataSize: null
// Bob (has metadata) → metadataSize: ~65, rootSize: ~168Pass any object field to $bsonSize. If the field is missing or null, the result is null. This is useful for comparing which nested structures grow fastest.
Add a size field, sort descending, and return the top offenders:
db.employees.aggregate([
{
$addFields: {
docSize: { $bsonSize: "$$ROOT" }
}
},
{ $sort: { docSize: -1 } },
{ $limit: 5 },
{
$project: {
name: 1,
docSize: 1
}
}
])This pattern helps identify documents approaching the 16 MB limit or bloated schemas. On large collections, add { allowDiskUse: true } when sorting.
Calculate combined document size for storage reporting:
db.employees.aggregate([
{
$group: {
_id: null,
totalBytes: { $sum: { $bsonSize: "$$ROOT" } },
docCount: { $sum: 1 },
maxBytes: { $max: { $bsonSize: "$$ROOT" } },
avgBytes: { $avg: { $bsonSize: "$$ROOT" } }
}
}
])Use $bsonSize inside $sum, $max, and $avg accumulators in a $group stage. This gives collection-level size statistics in one query.
$bsonSize across collections for growth estimates.$bsonSize WorksThe pipeline evaluates the expression — typically "$$ROOT" or a subdocument field like "$metadata".
MongoDB serializes the object into BSON format and counts every byte, including type markers and field names.
The integer result is written to the field you define in $project or $addFields.
Sort, filter, sum, or alert on document sizes in later pipeline stages.
The $bsonSize operator is essential for understanding how much space your MongoDB documents actually consume on disk. Combined with $$ROOT, it gives you a precise byte count for storage audits and schema tuning.
For beginners, remember: it measures BSON-encoded objects (not single string fields), use $$ROOT for the full document, and pair it with $sort to find outliers.
$$ROOT to measure the full document sizeallowDiskUse: true when sorting large collections by size$binarySize when you need field-level detail$bsonSize with $binarySize$bsonSizeUse these points when measuring document storage in MongoDB.
Full encoded object size.
Purpose{ $bsonSize: obj }
Whole document reference.
VariableMonitor large docs.
LimitDocument vs one field.
ImportantMove on to $ceil for rounding up numbers, or review $binarySize for field-level byte counts.
5 people found this page helpful