/ /

$toArray (expression operator)

Definition

$toArray

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:

{
   $toArray: <expression>
}

$toArray takes any valid expression.

$toArray is a shorthand for the following $convert expression:

{ $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 array.
Null or Missing	Returns null.

Parsing Rules

When converting a string to an array, $toArray:

Requires valid 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 Note The input must be a "string".
`$toArray: "123"`	Error: Input doesn't represent valid JSON: Unexpected standalone value
`$toArray: "[{\"$oid\": \"507f1f77bcf86cd799439011\"}]"`	[ { '$oid': '507f1f77bcf86cd799439011' } ] Note Extended JSON is not recognized.
`$toArray: null`	null

Convert String to Array

Insert a document into the jsonStrings collection:

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

The following operation converts strings to arrays:

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:

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

Convert binData to Array

The following operation converts binData vectors to arrays:

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=") }
])

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

The operation returns:

[
  { 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 instead.

Back

$tanh

$toBool