> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $bsonSize (expression operator)

## Definition

Returns the size in bytes of a given document (i.e. bsontype `Object`) when encoded as [BSON](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-BSON). You can use [`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) as an alternative to the `bsonSize()` method.

[`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) has the following syntax:

```javascript
{ $bsonSize: <object> }
```

The argument can be any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) as long as it resolves to either an object or `null`. For more information on expressions, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

## Behavior

If the argument is an object, the expression returns the size of the object in bytes when the object is encoded as [BSON.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-BSON)

If the argument is `null`, the expression returns `null`.

If the argument resolves to a data type other than an object or `null`, [`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) errors.

**Changed in version 9.0**

[`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) accepts input documents larger than the 16 MiB maximum BSON document size, such as large intermediate results produced earlier in the pipeline. In earlier MongoDB versions, [`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) returns a `BSONObjectTooLarge` error for input larger than 16 MiB.

[`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) still returns a `BSONObjectTooLarge` error when the input exceeds the 125 MiB maximum size for intermediate results.

## Examples

### Return Sizes of Documents

In [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh), create a sample collection named `employees` with the following documents:

```javascript
 db.employees.insertMany([
   {
     "_id": 1,
     "name": "Alice", "email": "alice@company.com", "position": "Software Developer",
     "current_task": {
       "project_id": 1,
       "project_name": "Aggregation Improvements",
       "project_duration": 5,
       "hours": 20
     }
   },
   {
     "_id": 2,
     "name": "Bob", "email": "bob@company.com", "position": "Sales",
     "current_task": {
       "project_id": 2,
       "project_name": "Write Blog Posts",
       "project_duration": 2,
       "hours": 10,
       "notes": "Progress is slow. Waiting for feedback."
     }
   },
   {
     "_id": 3,
     "name": "Charlie", "email": "charlie@company.com", "position": "HR (On Leave)",
     "current_task": null
   },
   {
     "_id": 4,
     "name": "Dianne", "email": "diane@company.com", "position": "Web Designer",
     "current_task": {
       "project_id": 3,
       "project_name": "Update Home Page",
       "notes": "Need to scope this project."
     }
   }
]);
```

The following aggregation [`projects`:](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project)

- The `name` field

- The `object_size` field, which uses [`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) to return the size of the document in bytes. The [`$$ROOT`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.ROOT) variable references the document currently being processed by the pipeline. To learn more about variables in the aggregation pipeline, see [Variables in Aggregation Expressions.](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md)

```javascript
db.employees.aggregate([
  {
    "$project": {
      "name": 1,
      "object_size": { $bsonSize: "$$ROOT" }
    }
  }
])
```

The operation returns the following result:

```javascript
{ "_id" : 1, "name" : "Alice", "object_size" : 222 }
{ "_id" : 2, "name" : "Bob", "object_size" : 248 }
{ "_id" : 3, "name" : "Charlie", "object_size" : 112 }
{ "_id" : 4, "name" : "Dianne", "object_size" : 207 }
```

### Return Combined Size of All Documents in a Collection

The following pipeline returns the combined size of all of the documents in the `employees` collection:

```javascript
db.employees.aggregate([
  {
    "$group": {
      "_id": null,
      "combined_object_size": { $sum: { $bsonSize: "$$ROOT" } }
    }
  }
])
```

When you specify an [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) \_id value of `null`, or any other constant value, the [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) stage calculates accumulated values for all the input documents as a whole.

The operation uses the [`$sum`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sum.md#mongodb-group-grp.-sum) operator to calculate the combined [`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) of each document in the collection. The [`$$ROOT`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.ROOT) variable references the document currently being processed by the pipeline. To learn more about variables in the aggregation pipeline, see [Variables in Aggregation Expressions.](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md)

The operation returns the following result:

```none
{ "_id" : null, "combined_object_size" : 789 }
```

**See also:**

- [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group)

- [`$sum`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sum.md#mongodb-group-grp.-sum)

### Return Document with Largest Specified Field

The following pipeline returns the document with the largest `current_task` field in bytes:

```javascript
db.employees.aggregate([
   // First Stage
   { $project: { name: "$name", task_object_size: { $bsonSize: "$current_task" } }  },
   // Second Stage
   { $sort: { "task_object_size" : -1 } },
   // Third Stage
   { $limit: 1 }
])
```

First Stage

The first stage of the pipeline [`projects`:](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project)

- The `name` field

- The `task_object_size` field, which uses [`$bsonSize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonsize.md#mongodb-expression-exp.-bsonSize) to return the size of the document's `current_task` field in bytes.

This stage outputs the following documents to the next stage:

```javascript
{ "_id" : 1, "name" : "Alice", "task_object_size" : 109 }
{ "_id" : 2, "name" : "Bob", "task_object_size" : 152 }
{ "_id" : 3, "name" : "Charlie", "task_object_size" : null }
{ "_id" : 4, "name" : "Dianne", "task_object_size" : 99 }
```

Second Stage

The second stage [`sorts`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort) the documents by `task_object_size` in descending order.

This stage outputs the following documents to the next stage:

```javascript
{ "_id" : 2, "name" : "Bob", "task_object_size" : 152 }
{ "_id" : 1, "name" : "Alice", "task_object_size" : 109 }
{ "_id" : 4, "name" : "Dianne", "task_object_size" : 99 }
{ "_id" : 3, "name" : "Charlie", "task_object_size" : null }
```

Third Stage

The third stage [`limits`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit) the output documents to only return the document appearing first in the sort order:

```javascript
{ "_id" : 2, "name" : "Bob", "task_object_size" : 152 }
```

**See also:**

- [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project)

- [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort)

- [`$limit`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit)

- [`$strLenBytes`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/strlenbytes.md#mongodb-expression-exp.-strLenBytes)

- [`$binarySize`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/binarysize.md#mongodb-expression-exp.-binarySize)