diff --git a/source/data-formats.txt b/source/data-formats.txt index 4a0c516fd..a0b28f2a8 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -22,6 +22,7 @@ Specialized Data Formats :maxdepth: 1 BSON + Extended JSON Time Series Data Overview diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index bef850a93..28726bc22 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -1,9 +1,9 @@ .. _node-bson-control: .. _node-bson: -============== -Work with BSON -============== +=================== +Work with BSON Data +=================== .. default-domain:: mongodb @@ -37,6 +37,16 @@ The code samples in this guide use the following BSON document as an example: "name" : "Mongo's Pizza" } +.. note:: Use the {+driver-short+}'s BSON package + + We recommend that you use the BSON package that is bundled with the driver to avoid + compatibility issues with other BSON packages. You can import the {+driver-short+}'s + BSON package with the following import statement: + + .. code-block:: js + + import { BSON } from 'mongodb'; + BSON Data Types --------------- @@ -56,7 +66,7 @@ example generates a random UUID: import { UUID } from 'mongodb'; - const myUuid = new BSON.UUID(); + const myUuid = new UUID(); Create a BSON Document ---------------------- @@ -109,7 +119,7 @@ The following example writes the sample BSON document to ``file.bson``: .. code-block:: javascript import fs from 'fs/promises'; // Import the file system module - import { BSON } from 'bson'; // Import the BSON package + import { BSON } from 'mongodb'; // Import the BSON package // Create a BSON object const bsonData = BSON.serialize(result); @@ -133,7 +143,7 @@ The following example reads the sample BSON document from ``file.bson``: :language: javascript import fs from 'fs/promises'; // Import the file system module - import { BSON } from 'bson'; // Import the BSON package + import { BSON } from 'mongodb'; // Import the BSON package // Read the BSON data from a file const data = await fs.readFile('file.bson'); diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt new file mode 100644 index 000000000..0f1a93bd0 --- /dev/null +++ b/source/data-formats/extended-json.txt @@ -0,0 +1,219 @@ +.. _node-extended-json: + +============================ +Work with Extended JSON Data +============================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code examples, bson, relaxed, canonical, legacy + +Overview +-------- + +JSON is a data format that represents the values of objects, arrays, numbers, +strings, booleans, and nulls. The **Extended JSON** format defines a reserved +set of keys prefixed with "``$``" to represent field type information that +directly corresponds to each type in BSON, the format that MongoDB uses to +store data. + +Extended JSON Formats +--------------------- + +MongoDB Extended JSON features different string formats to represent BSON data. +Each of the different formats conform to the JSON RFC +and meet specific use cases. The **Extended** format, also known as the +**Canonical** format, features specific representations for every BSON type +for bidirectional conversion without loss of information. The **Relaxed Mode** +format is more concise and closer to ordinary JSON, but does not represent +all the type information such as the specific bit width of numeric fields. + +See the following table to see a description of each format: + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 10 40 + + * - Name + - Description + + * - **Extended** + - | Also known as the *Canonical* format, this JSON representation avoids loss of + BSON type information. + | This format prioritizes type preservation at the loss of human-readability and + interoperability with older formats. + + * - **Relaxed Mode** + - | JSON representation that describes BSON documents with some type information loss. + | This format prioritizes human-readability and interoperability at the loss of + certain type information. + +To learn more about JSON, BSON, and Extended JSON, see +`our article about JSON and BSON `__ +and :manual:`Extended JSON ` in the {+mdb-server+} manual. + +.. _extended_json_example_section: + +Extended JSON Examples +~~~~~~~~~~~~~~~~~~~~~~ + +The following examples show a document containing an ObjectId, date, and long +number field represented in the Extended JSON format. Click the tab that +corresponds to the format of the example you want to see: + +.. tabs:: + + .. tab:: Extended + :tabid: extended-format + + .. code-block:: json + + { + "_id": { "$oid": "573a1391f29313caabcd9637" }, + "createdAt": { "$date": { "$numberLong": "1601499609" }}, + "numViews": { "$numberLong": "36520312" } + } + + .. tab:: Relaxed Mode + :tabid: relaxed-mode-format + + .. code-block:: json + + { + "_id": { "$oid": "573a1391f29313caabcd9637" }, + "createdAt": { "$date": "2020-09-30T18:22:51.648Z" }, + "numViews": 36520312 + } + +Write Extended JSON +------------------- + +You can write an Extended JSON string from a BSON document object by using the +``EJSON.stringify()`` method. + +The following example outputs an Extended JSON string in the Relaxed format: + +.. io-code-block:: + + .. input:: + :language: js + + import { Code, BSON } from 'mongodb'; + const EJSON = BSON.EJSON; + + const doc = { + foo: [1, 2], + bar: { hello: "world" }, + code: new Code("function x() { return 1; }", {}), + date: new Date(2024, 6, 20, 10, 30, 0), + }; + + const ejsonStr = EJSON.stringify(doc); + console.log(ejsonStr); + + .. output:: + :language: none + :visible: false + + {"foo":[1,2],"bar":{"hello":"world"},"code":{"$code":"function x() { return 1; }","$scope":{}},"date":{"$date":"2024-07-20T14:30:00Z"}} + +By default, the ``stringify()`` method returns the Extended JSON string in the +Relaxed format. To specify the Canonical format, set the ``relaxed`` +option to ``false``. + +The following example shows how to output Extended JSON in the Canonical format: + +.. io-code-block:: + + .. input:: + :language: js + + import { Code, BSON } from 'mongodb'; + const EJSON = BSON.EJSON; + + const doc = { + foo: [1, 2], + bar: { hello: "world" }, + code: new Code("function x() { return 1; }", {}), + date: new Date(2024, 6, 20, 10, 30, 0), + }; + + const ejsonStr = EJSON.stringify(doc, { relaxed: false }); + print(ejsonStr) + + .. output:: + :language: none + :visible: false + + {"foo":[{"$numberInt":"1"},{"$numberInt":"2"}],"bar":{"hello":"world"},"code":{"$code":"function x() { return 1; }","$scope":{}},"date":{"$date":{"$numberLong":"1721485800000"}}} + +Read Extended JSON +------------------ + +You can read an Extended JSON string into the JavaScript value or object described +by the string by using the ``EJSON.parse()`` method. + +The following example shows how you can read an Extended JSON string into a +JavaScript value or object by using the ``parse()`` method: + +.. The back ticks on ejsonStr in the below code example causes the orange +.. highlighting in this file, but the page still renders correctly. + +.. io-code-block:: + + .. input:: + :language: javascript + + import { BSON } from 'mongodb'; + const EJSON = BSON.EJSON; + + const ejsonStr = `{ + "foo": [ + { "$numberInt": "1" }, + { "$numberInt": "2" } + ], + "bar": { "hello": "world" }, + "code": { + "$code": "function x() { return 1; }", + "$scope": {} + }, + "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } } + }`; + + const doc = EJSON.parse(ejsonStr); + console.log(doc); + + .. output:: + :language: none + :visible: false + + { + foo: [ 1, 2 ], + bar: { hello: 'world' }, + code: new Code('function x() { return 1; }', {}), + bin: Binary.createFromBase64('AQIDBA==', 0) + } + +.. note:: + + The driver parses the ``$uuid`` Extended JSON type from a string to a + ``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field + parsing, see the + :spec:`Special Rules for Parsing $uuid Fields ` + section in the extended JSON specification. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the `EJSON `__ API documentation.