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

# $toArray (expression operator)

## Definition

Converts a value to an array. If the value cannot be converted, `$toArray` errors. If the value is `null` or missing, `$toArray` returns null.

`$toArray` has the following syntax:

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

`$toArray` takes any valid [expression.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

`$toArray` is a shorthand for the following [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) expression:

```javascript
{ $convert: { input: <expression>, to: "array" } }
```

## Behavior

### Input Type Expectations

The following table describes the behavior of `$toArray` for different input types:

| Input Type | Behavior |
| --- | --- |
| binData | Returns an array of numeric values. The numeric type of the array elements depends on the binData format. |
| String | Returns an array corresponding to the content within the string. The string must contain characters that represent a valid [JSON](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-JSON) array. |
| Null or Missing | Returns null. |

### Parsing Rules

When converting a string to an array, `$toArray`:

- Requires valid [JSON](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-JSON) syntax. Comments and trailing commas are not allowed.

- Requires the top-level value to be an array. If the string does not represent an array, `$toArray` errors.

- Does not interpret Extended JSON type wrappers such as `$oid`, `$date`, or `Timestamp(...)`. These remain strings or nested objects in the result.

### binData Conversion

When converting binData to an array, `$toArray`:

- Accepts binData with subtype 9 values.

- Converts `PACKED_BIT` vectors to `boolean` arrays.

- Converts `INT8` vectors to `integer` arrays.

- Converts `FLOAT32` vectors to `double` arrays.

### Numeric Type Mapping

`$toArray` converts numeric types based on their value and format:

- Integers within the 32-bit signed range become `int`.

- Integers outside the 32-bit range but within the 64-bit signed range become `long`.

- Integers outside the 64-bit signed range become `double`, which can result in loss of precision.

- Numbers with a decimal point or exponent notation become `double`.

## Examples

The following table shows examples of using `$toArray` to convert strings to arrays:

| Example | Results |
| --- | --- |
| `$toArray: "[1, 2, 3]"` | [ 1, 2, 3 ] |
| `$toArray: '["a", "b", "c"]'` | [ 'a', 'b', 'c' ] |
| `$toArray: "[]"` | [ ] |
| `$toArray: "{}"` | Error: Input doesn't match expected type 'array' |
| `$toArray: 123` | Error: Unsupported conversion from int to array in $convert with no onError value |
| `$toArray: "123"` | Error: Input doesn't represent valid JSON: Unexpected standalone value |
| `$toArray: "[{\"$oid\": \"507f1f77bcf86cd799439011\"}]"` | [ { '$oid': '507f1f77bcf86cd799439011' } ] |
| `$toArray: null` | null |

### Convert String to Array

Insert a document into the `jsonStrings` collection:

```javascript
db.jsonStrings.insertOne({_id: 1})
```

The following operation converts strings to arrays:

```javascript
db.jsonStrings.aggregate([
  {
    $project: {
      _id: 0,
      numbers: { $toArray: "[1, 2, 3]" },
      documents: { $toArray: '[{"a": 1}, {"b": 2}]' }
    }
  }
])
```

The `numbers` field in the result is an array of integers, and `documents` is an array of embedded documents:

```json
{
  numbers: [ 1, 2, 3 ],
  documents: [ { a: 1 }, { b: 2 } ]
}
```

### Convert binData to Array

The following operation converts binData vectors to arrays:

```javascript
db.t.insertMany([
  // Empty PACKED_BIT vector converts to empty array
  { v: BinData(9, "EAA=") },

  // PACKED_BIT vector converts to bool array
  { v: BinData(9, "EAB/Bw==") },

  // INT8 vector converts to int array
  { v: BinData(9, "AwAAAQ==") },

  // FLOAT32 vector converts to double array
  { v: BinData(9, "JwCamZk+") },

  // FLOAT32 vector with special values converts to [-Infinity, 0, Infinity]
  { v: BinData(9, "JwAAAID/AAAAAAAAgH8=") }
])

```

```javascript
db.t.aggregate([
  {
    $project: {
      _id: 0,
      original: "$v",
      asArray: { $toArray: "$v" }
    }
  }
])
```

The operation returns:

```javascript
[
  { original: Binary.fromPackedBits(new Uint8Array([])), asArray: [] },
  {
    original: Binary.fromPackedBits(new Uint8Array([ 127, 7 ])),
    asArray: [
      false, true,  true,  true,
      true,  true,  true,  true,
      false, false, false, false,
      false, true,  true,  true
    ]
  },
  {
    original: Binary.fromInt8Array(new Int8Array([ 0, 1 ])),
    asArray: [ 0, 1 ]
  },
  {
    original: Binary.fromFloat32Array(new Float32Array([ 0.30000001192092896 ])),
    asArray: [ 0.30000001192092896 ]
  },
  {
    original: Binary.fromFloat32Array(new Float32Array([ -Infinity, 0, Infinity ])),
    asArray: [ -Infinity, 0, Infinity ]
  }
]
```

**Note:**

If the conversion operation encounters an error, the aggregation operation stops and throws an error. To override this behavior, use [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) instead.