- Reference >
- MongoDB Extended JSON
MongoDB Extended JSON¶
JSON can only represent a subset of the types supported by BSON. To preserve type information, MongoDB adds the following extensions to the JSON format:
- Strict mode. Strict mode representations of BSON types conform to the JSON RFC. Any JSON parser can parse these strict mode representations as key/value pairs; however, only the MongoDB internal JSON parser recognizes the type information conveyed by the format.
- mongo Shell mode. The MongoDB internal JSON parser and the mongo shell can parse this mode.
The representation used for the various data types depends on the context in which the JSON is parsed.
Parsers and Supported Format¶
Input in Strict Mode¶
The following can parse representations in strict mode with recognition of the type information.
- REST Interfaces
- mongoimport
- --query option of various MongoDB tools
Other JSON parsers, including mongo shell and db.eval(), can parse strict mode representations as key/value pairs, but without recognition of the type information.
Input in mongo Shell Mode¶
The following can parse representations in mongo shell mode with recognition of the type information.
- REST Interfaces
- mongoimport
- --query option of various MongoDB tools
- mongo shell
Output in Strict mode¶
mongoexport and REST and HTTP Interfaces output data in Strict mode.
BSON Data Types and Associated Representations¶
The following presents the BSON data types and the associated representations in Strict mode and mongo Shell mode.
Binary¶
- data_binary¶
Strict Mode mongo Shell Mode { "$binary": "<bindata>", "$type": "<t>" }
BinData ( <t>, <bindata> )
- <bindata> is the base64 representation of a binary string.
- <t> is a representation of a single byte indicating the data type. In Strict mode it is a hexadecimal string, and in Shell mode it is an integer. See the extended bson documentation. http://bsonspec.org/spec.html
Date¶
- data_date¶
Strict Mode mongo Shell Mode { "$date": "<date>" }
new Date ( <date> )
In Strict mode, <date> is an ISO-8601 date format with a mandatory time zone field following the template YYYY-MM-DDTHH:mm:ss.mmm<+/-Offset>.
The MongoDB JSON parser currently does not support loading ISO-8601 strings representing dates prior to the Unix epoch. When formatting pre-epoch dates and dates past what your system’s time_t type can hold, the following format is used:
{ "$date" : { "$numberLong" : "<dateAsMilliseconds>" } }
In Shell mode, <date> is the JSON representation of a 64-bit signed integer giving the number of milliseconds since epoch UTC.
Timestamp¶
- data_timestamp¶
Strict Mode mongo Shell Mode { "$timestamp": { "t": <t>, "i": <i> } }
Timestamp( <t>, <i> )
- <t> is the JSON representation of a 32-bit unsigned integer for seconds since epoch.
- <i> is a 32-bit unsigned integer for the increment.
Regular Expression¶
- data_regex¶
Strict Mode mongo Shell Mode { "$regex": "<sRegex>", "$options": "<sOptions>" }
/<jRegex>/<jOptions>
- <sRegex> is a string of valid JSON characters.
- <jRegex> is a string that may contain valid JSON characters and unescaped double quote (") characters, but may not contain unescaped forward slash (/) characters.
- <sOptions> is a string containing the regex options represented by the letters of the alphabet.
- <jOptions> is a string that may contain only the characters ‘g’, ‘i’, ‘m’ and ‘s’ (added in v1.9). Because the JavaScript and mongo Shell representations support a limited range of options, any nonconforming options will be dropped when converting to this representation.
OID¶
- data_oid¶
Strict Mode mongo Shell Mode { "$oid": "<id>" }
ObjectId( "<id>" )
<id> is a 24-character hexadecimal string.
DB Reference¶
- data_ref¶
Strict Mode mongo Shell Mode { "$ref": "<name>", "$id": "<id>" }
DBRef("<name>", "<id>")
- <name> is a string of valid JSON characters.
- <id> is any valid extended JSON type.
Undefined Type¶
- data_undefined¶
Strict Mode mongo Shell Mode { "$undefined": true }
undefined
The representation for the JavaScript/BSON undefined type.
You cannot use undefined in query documents. Consider the following document inserted into the people collection:
db.people.insert( { name : "Sally", age : undefined } )
The following queries return an error:
db.people.find( { age : undefined } ) db.people.find( { age : { $gte : undefined } } )
However, you can query for undefined values using $type, as in:
db.people.find( { age : { $type : 6 } } )
This query returns all documents for which the age field has value undefined.
MinKey¶
- data_minkey¶
Strict Mode mongo Shell Mode { "$minKey": 1 }
MinKey
The representation of the MinKey BSON data type that compares lower than all other types. See What is the compare order for BSON types? for more information on comparison order for BSON types.
MaxKey¶
- data_maxkey¶
Strict Mode mongo Shell Mode { "$maxKey": 1 }
MaxKey
The representation of the MaxKey BSON data type that compares higher than all other types. See What is the compare order for BSON types? for more information on comparison order for BSON types.
NumberLong¶
New in version 2.6.
- data_numberlong¶
Strict Mode mongo Shell Mode { "$numberLong": "<number>" }
NumberLong( "<number>" )
NumberLong is a 64 bit signed integer. You must include quotation marks or it will be interpreted as a floating point number, resulting in a loss of accuracy.
For example, the following commands insert 9223372036854775807 as a NumberLong with and without quotation marks around the integer value:
db.json.insert( { longQuoted : NumberLong("9223372036854775807") } ) db.json.insert( { longUnQuoted : NumberLong(9223372036854775807) } )
When you retrieve the documents, the value of longUnquoted has changed, while longQuoted retains its accuracy:
db.json.find() { "_id" : ObjectId("54ee1f2d33335326d70987df"), "longQuoted" : NumberLong("9223372036854775807") } { "_id" : ObjectId("54ee1f7433335326d70987e0"), "longUnquoted" : NumberLong("-9223372036854775808") }
Thank you for your feedback!
We're sorry! You can Report a Problem to help us improve this page.