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

# $toObject (expression operator)

## Definition

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

`$toObject` has the following syntax:

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

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

`$toObject` 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: "object" } }
```

## Behavior

### Input Type Expectations

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

| Input Type | Behavior |
| --- | --- |
| String | Returns a document 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) object. |
| Null or Missing | Returns null. |

### Parsing Rules

When converting a string to an object, `$toObject`:

- 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 object. If the string does not represent an object, `$toObject` errors.

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

- Preserves the last value when the object contains duplicate field names. Earlier values for the same field are discarded.

### Numeric Type Mapping

`$toObject` 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 `$toObject` to convert strings to objects:

| Example | Results |
| --- | --- |
| `$toObject: "{\"a\": 1, \"b\": 2}"` | { a: 1, b: 2 } |
| `$toObject: "{}"` | { } |
| `$toObject: "[]"` | Error:  Input doesn't match expected type 'object' |
| `$toObject: "123"` | Error: Input doesn't represent valid JSON: Unexpected standalone value |
| `$toObject: "{\"nam\\u0000e\": \"foo\"}"` | Error: Input doesn't represent valid JSON: Illegal embedded null byte |
| `$toObject: "{\"name\": \"fo\\u0000o\"}"` | { name: 'fox00o' } |
| `$toObject: "{\"a\": 1, \"b\": 2, \"a\": 3}"` | { a: 3, b: 2 } |
| `$toObject: "{\"foo\": null}"` | { foo: null } |
| `$toObject: "{\"foo\": false}"` | { foo: false } |
| `$toObject: "{\"__proto__\": {\"foo\": null}}"` | { ['__proto__']: { foo: null } } |
| `$toObject: "{\"foo\": \"NaN\"}"` | { foo: 'NaN' } |
| `$toObject: "{\"foo\": 123}"` | { foo: 123 } |
| `$toObject: "{\"foo\": 4294967296}"` | { foo: Long('4294967296') } |
| `$toObject: "{\"foo\": 1.123123}"` | { foo: 1.123123 } |
| `$toObject: "{\"foo\": 1.2e+3}"` | { foo: 1200 } |
| `$toObject: "{\"largePos\": 18446744073709551615}"` | { largePos: 18446744073709552000 } |
| `$toObject: "{\"largeNeg\": -18446744073709551615}"` | { largeNeg: -18446744073709552000 } |
| `$toObject: null` | null |

### Convert String to Object

Create a collection with strings stored in a field:

```javascript
db.jsonStrings.insertOne({
  _id: 1,
  config: '{"feature": true, "threshold": 10}'
})
```

The following aggregation converts the string in `config` to an object:

```javascript
db.jsonStrings.aggregate([
  {
    $project: {
      _id: 0,
      parsedConfig: { $toObject: "$config" }
    }
  }
])
```

This operation returns a document where `parsedConfig` is a nested document with a boolean and an integer value:

```javascript
{ parsedConfig: { feature: true, threshold: 10 } }
```

**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.