/ /

$deserializeEJSON (expression operator)

Definition

$deserializeEJSON: New in version 8.3.
Converts Extended JSON (EJSON) format to native BSON values. You can use this expression to transform EJSON type wrappers into their corresponding BSON types after you parse a JSON string with $convert.

Syntax

{
   $deserializeEJSON: {
      input: <expression>,
      onError: <expression>
   }
}

$deserializeEJSON takes a document with the following fields:

Field	Type	Necessity	Description
`input`	Expression	Required	The Extended JSON value to convert to native BSON format. This should be a BSON document containing EJSON type wrappers.
`onError`	Expression	Optional	Value to return if the operation encounters an error during conversion. If unspecified, when an error occurs, the operation throws an error and stops.

Behavior

Type Wrapper Parsing

$deserializeEJSON converts Extended JSON type wrappers to their corresponding BSON types:

Extended JSON Type Wrapper	BSON Type	Example
`{"$numberInt": "42"}`	Int32	`42`
`{"$numberLong": "42"}`	Int64	`NumberLong(42)`
`{"$numberDouble": "42.5"}`	Double	`42.5`
`{"$oid": "507f1f77bcf86cd799439011"}`	ObjectId	`ObjectId("507f1f77bcf86cd799439011")`
`{"$date": "2021-01-01T00:00:00.000Z"}`	Date	`ISODate("2021-01-01T00:00:00.000Z")`
`{"$date": {"$numberLong": "1609459200000"}}`	Date	`ISODate("2021-01-01T00:00:00.000Z")`
`{"$binary": {"base64": "AQIDBA==", "subType": "00"}}`	Binary	`BinData(0, "AQIDBA==")`
`{"$regularExpression": {"pattern": "abc", "options": "i"}}`	Regular Expression	`/abc/i`

Null and Missing Values

If the input value is null or missing, $deserializeEJSON returns null.

Examples

The examples on this page use data from the sample_mflix sample dataset. For details on how to load this dataset into your self-managed MongoDB deployment, see Load the sample dataset. If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

Deserialize Extended JSON Document

The following example deserializes an Extended JSON document back to native BSON types:

db.movies.aggregate([
  {
    $match: { title: "Inception" }
  },
  {
    $project: {
      original: "$$ROOT",
      serialized: { $serializeEJSON: { input: "$$ROOT" } }
    }
  },
  {
    $project: {
      title: "$original.title",
      deserialized: { $deserializeEJSON: { input: "$serialized" } }
    }
  }
])

{
  _id: ObjectId("573a1398f29313caabcea974"),
  title: "Inception",
  deserialized: {
    _id: ObjectId("573a1398f29313caabcea974"),
    title: "Inception",
    year: 2010,
    runtime: 148,
    released: ISODate("2010-07-16T00:00:00.000Z"),
    cast: [
      "Leonardo DiCaprio",
      "Joseph Gordon-Levitt",
      "Ellen Page",
      "Tom Hardy"
    ],
    genres: [ "Action", "Sci-Fi", "Thriller" ],
    directors: [ "Christopher Nolan" ]
  }
}

Parse JSON String and Deserialize

The following example combines $convert with $deserializeEJSON to parse a JSON string and convert EJSON type wrappers to BSON:

db.aggregate([
  {
    $documents: [
      {
        jsonData: '{"_id":{"$oid":"507f1f77bcf86cd799439011"},' +
          '"title":"The Matrix",' +
          '"year":{"$numberInt":"1999"},' +
          '"rating":{"$numberDouble":"8.7"}}'
      }
    ]
  },
  {
    $project: {
      parsed: {
        $convert: {
          input: "$jsonData",
          to: "object"
        }
      }
    }
  },
  {
    $project: {
      movie: { $deserializeEJSON: { input: "$parsed" } }
    }
  }
])

{
  _id: ObjectId("..."),
  movie: {
    _id: ObjectId("507f1f77bcf86cd799439011"),
    title: "The Matrix",
    year: 1999,
    rating: 8.7
  }
}

Deserialize Specific Fields

You can deserialize specific fields containing EJSON type wrappers:

db.movies.aggregate([
  {
    $match: { title: "Inception" }
  },
  {
    $project: {
      title: 1,
      serializedMetadata: {
        $serializeEJSON: {
          input: {
            releaseDate: "$released",
            runtime: "$runtime",
            rating: "$imdb.rating"
          }
        }
      }
    }
  },
  {
    $project: {
      title: 1,
      metadata: { $deserializeEJSON: { input: "$serializedMetadata" } }
    }
  }
])

{
  _id: ObjectId("573a1398f29313caabcea974"),
  title: "Inception",
  metadata: {
    releaseDate: ISODate("2010-07-16T00:00:00.000Z"),
    runtime: 148,
    rating: 8.8
  }
}

Use onError for Error Handling

The following example uses onError to provide a fallback value if deserialization fails:

db.data.aggregate([
  {
    $project: {
      result: {
        $deserializeEJSON: {
          input: "$ejsonField",
          onError: { error: "Invalid EJSON format" }
        }
      }
    }
  }
])

Learn More

$serializeEJSON
$convert
$toString
The MongoDB Shell provides built-in methods to help work with Extended JSON. To learn more, see EJSON.

Back

$derivative

$divide