Skip to content

Commit a49a56c

Browse files
author
Dave Cuthbert
authored
DOCSP-31806 ejson methods (#284)
* DOCSP-31809 ejson methods * self review * review feedback * review feedback * review feedback * Review feedback * Review comments * Review comments
1 parent 7c6c518 commit a49a56c

File tree

7 files changed

+744
-1
lines changed

7 files changed

+744
-1
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ toc_landing_pages = ["/run-commands",
99
"/write-scripts",
1010
"/snippets",
1111
"/configure-mongosh",
12-
"/reference/configure-shell-settings"
12+
"/reference/configure-shell-settings",
13+
"/reference/ejson"
1314
]
1415

1516
[constants]

‎source/includes/links-urls/ejson.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. |bsonUrl| replace:: `BSON <https://www.mongodb.com/basics/bson>`__
2+
3+
.. |ejsonUrl| replace:: `EJSON <https://www.npmjs.com/package/bson#EJSON>`__
4+
5+
.. |bsonParseUrl| replace:: `Node.js BSON parser <https://www.npmjs.com/package/bson>`__
6+
7+
.. |mdn-json-parse| replace:: `JSON.parse <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse>`__
8+
9+
.. |mdn-json-stringify| replace:: `JSON.stringify() <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify>`__
10+

‎source/reference.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Reference
1010
/reference/compatibility
1111
/reference/data-types
1212
/reference/methods
13+
/reference/ejson
1314
/mongoshrc
1415
/reference/options
1516
/logs

‎source/reference/ejson.txt

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. _mongosh-ejson:
2+
3+
=====
4+
EJSON
5+
=====
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. include:: /includes/links-urls/ejson.rst
14+
15+
MongoDB uses |bsonUrl|, a binary serialization format, to store
16+
documents and to exchange data. BSON is a rich format and has data types
17+
that aren't included in the JSON standard. :ref:`Extended JSON (EJSON)
18+
<mongodb-extended-json-v2>` adds support for the additional types. EJSON
19+
is a JSON compatible way to represent BSON values.
20+
21+
``mongosh`` exposes the |ejsonUrl| interface from the |bsonParseUrl| to
22+
help you transform your data. Use the ``EJSON`` interface when you need
23+
to transform BSON data.
24+
25+
.. list-table::
26+
:header-rows: 1
27+
28+
* - EJSON Method
29+
- Use
30+
31+
* - :ref:`EJSON.stringify() <mongosh-ejson-stringify>`
32+
- Convert BSON objects to strings. This method is useful to
33+
transform ``mongosh`` output.
34+
35+
* - :ref:`EJSON.parse() <mongosh-ejson-parse>`
36+
- Convert strings to JSON. This method is useful to transform
37+
inputs.
38+
39+
For additional EJSON capabilities, see the `npm EJSON documentation
40+
<https://www.npmjs.com/package/bson#EJSON>`__.
41+
42+
Learn More
43+
----------
44+
45+
`BSON specification <http://bsonspec.org/>`__
46+
47+
.. toctree::
48+
:titlesonly:
49+
50+
/reference/ejson/parse
51+
/reference/ejson/stringify
52+

‎source/reference/ejson/parse.txt

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
.. _mongosh-ejson-parse:
2+
3+
=============
4+
EJSON.parse()
5+
=============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. include:: /includes/links-urls/ejson.rst
14+
15+
The ``EJSON.parse()`` method converts string values to JSON.
16+
17+
Syntax
18+
------
19+
20+
The ``EJSON.parse()`` method takes a string as input and an optional
21+
modifier that controls the output format.
22+
23+
.. code-block:: javascript
24+
:copyable: false
25+
26+
EJSON.parse(string, [options])
27+
28+
Command Fields
29+
--------------
30+
31+
The ``EJSON.parse()`` method takes these fields:
32+
33+
.. list-table::
34+
:header-rows: 1
35+
36+
* - Field
37+
- Type
38+
- Necessity
39+
- Description
40+
41+
* - ``value``
42+
- string
43+
- Required
44+
- String ``EJSON.parse()`` transforms into JSON key-value pairs
45+
46+
* - ``options``
47+
- string
48+
- Optional
49+
- Modifies output :ref:`types <mongo-shell-data-type>`. The only
50+
option is ``{ relaxed: <boolean> }``.
51+
52+
.. list-table::
53+
:header-rows: 1
54+
:widths: 30 70
55+
56+
* - Value
57+
- Effect
58+
59+
* - ``true``
60+
- Returns native JavaScript types when possible
61+
62+
* - ``false``
63+
- Prefer to return BSON types
64+
65+
Behavior
66+
--------
67+
68+
You can call ``EJSON.parse()`` from inside an interactive ``mongosh``
69+
session or from the system command line using ``--eval``.
70+
71+
Call ``EJSON.parse()`` from an interactive session:
72+
73+
.. code-block:: javascript
74+
:copyable: false
75+
76+
EJSON.parse(string)
77+
78+
Call ``EJSON.parse()`` from the system command line:
79+
80+
.. code-block:: shell
81+
:copyable: false
82+
83+
mongosh --eval "EJSON.parse(string)"
84+
85+
Examples
86+
--------
87+
88+
To try these examples, first create the ``sales`` collection:
89+
90+
.. code-block:: javascript
91+
92+
db.sales.insertMany( [
93+
{ custId: 345, purchaseDate: ISODate("2023-07-04"), quantity: 4, cost: Decimal128("100.60"), },
94+
{ custId: 346, purchaseDate: ISODate("2023-07-12"), quantity: 3, cost: Decimal128("175.45"), },
95+
{ custId: 486, purchaseDate: ISODate("2023-08-01"), quantity: 9, cost: Decimal128("200.53"), },
96+
] )
97+
98+
Format Input with EJSON.parse()
99+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100+
101+
``EJSON.parse()`` accepts a string as input. For this example, use the
102+
:ref:`EJSON.stringify() <mongosh-ejson-stringify>` method to export the
103+
``sales`` collection as a string.
104+
105+
.. code-block:: javascript
106+
107+
let salesCollection = EJSON.stringify( db.sales.find().toArray() )
108+
109+
Use ``EJSON.parse()`` to format the string for methods like
110+
:method:`db.collection.insertMany()` that expect JSON pairs:
111+
112+
.. code-block:: javascript
113+
114+
db.salesRestored.insertMany( EJSON.parse( salesCollection ) )
115+
116+
- ``EJSON.parse()`` formats the values in ``salesCollection`` as JSON
117+
pairs.
118+
119+
- :method:`db.salesRestored.insertMany() <db.collection.insertMany()>`
120+
uses the JSON pairs to create the ``salesRestored`` collection.
121+
122+
Use EJSON.parse() from the command line
123+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124+
125+
To import string data from an external source such as a file or an API
126+
call, use ``EJSON.parse()`` with the ``mongosh --eval`` method.
127+
128+
For this example, save the ``sales`` collection as a file.
129+
130+
.. code-block:: javascript
131+
132+
let salesCollection = EJSON.stringify( db.sales.find().toArray() )
133+
134+
fs.writeFileSync( 'sales.json', salesCollection )
135+
136+
The code creates a file on your local system called ``sales.json``. To
137+
import the file and create a new collection, exit ``mongosh`` and run an
138+
``--eval`` operation from the command line.
139+
140+
.. code-block:: javascript
141+
142+
# Note: This example is formatted to fit on the page.
143+
144+
mongosh --quiet \
145+
--eval "db.salesFromFile.insertMany( \
146+
EJSON.parse( fs.readFileSync( 'sales.json', 'utf8' ) ) )"
147+
148+
- ``EJSON.parse()`` takes a string as input. This example uses
149+
``fs.readFileSync()`` to read the ``sale.json`` file as a string.
150+
151+
- ``EJSON.parse()`` formats the input string as JSON pairs.
152+
153+
- ``db.salesFromFile.insertMany()`` creates the ``salesFromFile``
154+
collection from the JSON pairs.
155+
156+
Learn More
157+
----------
158+
159+
- |ejsonUrl| documentation
160+
- Mozilla Developer Network |mdn-json-parse| documentation
161+

0 commit comments

Comments
 (0)