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

# $size  (expression operator)

## Definition

Counts and returns the total number of items in an array.

## Compatibility

You can use `$size` for deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

* [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

* [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

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

```javascript
{ $size: <expression> }
```

The argument for [`$size`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/size.md#mongodb-expression-exp.-size) can be any [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) as long as it resolves to an array. For more information on expressions, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

## Behavior

The argument for [`$size`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/size.md#mongodb-expression-exp.-size) must resolve to an array. If the argument for [`$size`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/size.md#mongodb-expression-exp.-size) is missing or does not resolve to an array, [`$size`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/size.md#mongodb-expression-exp.-size) errors.

## Example

Consider an `inventory` collection with the following documents:

```javascript
db.inventory.insertMany( [
   { _id: 1, item: "ABC1", description: "product 1", colors: [ "blue", "black", "red" ] },
   { _id: 2, item: "ABC2", description: "product 2", colors: [ "purple" ] },
   { _id: 3, item: "XYZ1", description: "product 3", colors: [ ] },
   { _id: 4, item: "ZZZ1", description: "product 4 - missing colors" },
   { _id: 5, item: "ZZZ2", description: "product 5 - colors is string", colors: "blue,red" }
] )
```

The following aggregation pipeline operation uses the [`$size`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/size.md#mongodb-expression-exp.-size) operator to return the number of elements in the `colors` array:

```javascript
db.inventory.aggregate([
   {
      $project: {
         item: 1,
         numberOfColors: { $cond: { if: { $isArray: "$colors" }, then: { $size: "$colors" }, else: "NA"} }
      }
   }
] )
```

The operation returns the following:

```javascript
{ _id: 1, item: "ABC1", numberOfColors: 3 }
{ _id: 2, item: "ABC2", numberOfColors: 1 }
{ _id: 3, item: "XYZ1", numberOfColors: 0 }
{ _id: 4, item: "ZZZ1", numberOfColors: "NA" }
{ _id: 5, item: "ZZZ2", numberOfColors: "NA" }
```