Permalink
Fetching contributors…
Cannot retrieve contributors at this time
436 lines (262 sloc) 9.24 KB
=====================
MongoDB Extended JSON
=====================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
:term:`JSON` can only represent a subset of the types supported by
:term:`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 <http://www.json.org>`_. 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
:program:`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.
- :ecosystem:`REST Interfaces </tools/http-interfaces>`
- :program:`mongoimport`
- ``--query`` option of various MongoDB tools
- :products:`MongoDB Compass </compass>`
Other JSON parsers, including :program:`mongo` shell and
:method:`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.
- :ecosystem:`REST Interfaces </tools/http-interfaces>`
- :program:`mongoimport`
- ``--query`` option of various MongoDB tools
- :program:`mongo` shell
Output in Strict mode
~~~~~~~~~~~~~~~~~~~~~
:program:`mongoexport` and :ecosystem:`REST and HTTP Interfaces
</tools/http-interfaces>` output data in *Strict mode*.
Output in ``mongo`` Shell Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:program:`bsondump` outputs in ``mongo`` *Shell 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
~~~~~~
.. bsontype:: data_binary
.. list-table::
:header-rows: 1
:widths: 50 5 40
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$binary": "<bindata>", "$type": "<t>" }
-
- .. code-block:: none
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
~~~~
.. bsontype:: data_date
.. list-table::
:header-rows: 1
:widths: 40 20 40
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$date": "<date>" }
-
- .. code-block:: none
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 :term:`Unix epoch`. When formatting
pre-epoch dates and dates past what your system's ``time_t`` type can hold,
the following format is used:
.. code-block:: none
{ "$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
~~~~~~~~~
.. bsontype:: data_timestamp
.. list-table::
:header-rows: 1
:widths: 40 10 30
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$timestamp": { "t": <t>, "i": <i> } }
-
- .. code-block:: none
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
~~~~~~~~~~~~~~~~~~
.. bsontype:: data_regex
.. list-table::
:header-rows: 1
:widths: 50 5 30
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$regex": "<sRegex>", "$options": "<sOptions>" }
-
- .. code-block:: none
/<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
~~~
.. bsontype:: data_oid
.. list-table::
:header-rows: 1
:widths: 40 20 40
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$oid": "<id>" }
-
- .. code-block:: none
ObjectId( "<id>" )
``<id>`` is a 24-character hexadecimal string.
DB Reference
~~~~~~~~~~~~
.. bsontype:: data_ref
.. list-table::
:header-rows: 1
:widths: 50 5 30
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$ref": "<name>", "$id": "<id>" }
-
- .. code-block:: none
DBRef("<name>", "<id>")
- ``<name>`` is a string of valid JSON characters.
- ``<id>`` is any valid extended JSON type.
Undefined Type
~~~~~~~~~~~~~~
.. bsontype:: data_undefined
.. list-table::
:header-rows: 1
:widths: 40 20 40
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$undefined": true }
-
- .. code-block:: none
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:
.. code-block:: sh
db.people.insert( { name : "Sally", age : undefined } )
The following queries return an error:
.. code-block:: sh
db.people.find( { age : undefined } )
db.people.find( { age : { $gte : undefined } } )
However, you can query for undefined values using :query:`$type`, as
in:
.. code-block:: sh
db.people.find( { age : { $type : 6 } } )
This query returns all documents for which the ``age`` field has
value ``undefined``.
MinKey
~~~~~~
.. bsontype:: data_minkey
.. list-table::
:header-rows: 1
:widths: 40 20 40
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$minKey": 1 }
-
- .. code-block:: none
MinKey
The representation of the MinKey BSON data type that compares lower
than all other types. See
:ref:`faq-dev-compare-order-for-BSON-types` for more information on
comparison order for BSON types.
MaxKey
~~~~~~
.. bsontype:: data_maxkey
.. list-table::
:header-rows: 1
:widths: 40 20 40
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$maxKey": 1 }
-
- .. code-block:: none
MaxKey
The representation of the MaxKey BSON data type that compares higher
than all other types. See
:ref:`faq-dev-compare-order-for-BSON-types` for more information on
comparison order for BSON types.
NumberLong
~~~~~~~~~~
.. versionadded:: 2.6
.. bsontype:: data_numberlong
.. list-table::
:header-rows: 1
:widths: 40 10 30
* - Strict Mode
-
- mongo Shell Mode
* - .. code-block:: none
{ "$numberLong": "<number>" }
-
- .. code-block:: none
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:
.. code-block:: sh
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:
.. code-block:: sh
db.json.find()
{ "_id" : ObjectId("54ee1f2d33335326d70987df"), "longQuoted" : NumberLong("9223372036854775807") }
{ "_id" : ObjectId("54ee1f7433335326d70987e0"), "longUnquoted" : NumberLong("-9223372036854775808") }