Docs Menu

JSON & BSON

On this page

  • Overview
  • JSON (JavaScript Object Notation)
  • EJSON (Extended JSON)
  • BSON (Binary JSON)
  • BSON.ObjectId
  • BSON.BSONRegExp
  • BSON.Binary
  • BSON.MaxKey
  • BSON.MinKey
  • BSON.Int32
  • BSON.Long
  • BSON.Double
  • BSON.Decimal128

MongoDB Realm functions include built-in global modules that allow you to process and convert between data formats. Each format supports various different data types and encodings.

Module
Description
Includes methods that convert between string and object representations of JSON data.
Includes methods that convert between string and object representations of Extended JSON data.
Includes methods that create Binary JSON objects and convert between various BSON data types and encodings.

JSON is a standard data format that stores groups of key-value pairs and supports basic JavaScript types. For details on syntax and supported types, refer to the JSON specification.

Realm exposes the standard JSON module in the global scope of every function. The module includes methods that convert between string and object representations of standard JSON objects.

JSON.parse(jsonString)

Parses the provided JSON string and converts it to a JavaScript object.

Parameter
Type
Description
jsonString
A serialized string representation of a standard JSON object.
Returns:A standard JavaScript object generated from the provided JSON string.
Example
const jsonString = `{
"answer": 42,
"submittedAt": "2020-03-02T16:50:24.475Z"
}`;
const jsonObject = JSON.parse(jsonString);
JSON.stringify(object)

Serializes the provided JavaScript object to a JSON string.

Parameter
Type
Description
object
A standard JavaScript Object.
Returns:A string representation of the provided JavaScript object.
Example
const object = {
answer: 42,
submittedAt: new Date("2020-03-02T16:46:47.977Z")
};
const jsonString = JSON.stringify(object);

Extended JSON is a superset of standard JSON that adds additional support for types that are available in BSON but not included in the JSON specification.

Realm exposes the EJSON module in the global scope of every function. This module is similar to the standard JSON module but preserves additional type information.

EJSON.parse(ejsonString)

Parses the provided EJSON string and converts it to a JavaScript object.

Parameter
Type
Description
ejsonString
string
A serialized string representation of an Extended JSON object.
Returns:A JavaScript object representation of the provided EJSON string.
Example
const ejsonString = `{
"answer": {
"$numberLong": "42"
},
"submittedAt": {
"$date": {
"$numberLong": "1583167607977"
}
}
}`;
const ejsonObject = EJSON.parse(ejsonString);
EJSON.stringify(object)

Serializes the provided JavaScript object to an EJSON string.

Parameter
Type
Description
object
document
An EJSON object. The object may contain BSON types.
Returns:A string representation of the provided EJSON object.
Example
const object = {
answer: 42,
submittedAt: new Date("2020-03-02T16:46:47.977Z")
};
const ejsonString = EJSON.stringify(object);

BSON is a data format that encodes binary representations of extended JSON objects. BSON includes additional data types beyond those in the JSON standard and provides a unified interface for converting data to and from binary representations. For more information, refer to the BSON specification.

Realm exposes the BSON module in the global scope of every Function. This module provides methods that allow you to create BSON objects and convert them to and from various data types and encodings.

Note
MongoDB Documents are BSON

MongoDB stores all documents in BSON format, so you'll use the BSON package most commonly when you run CRUD & Aggregation operations.

The BSON.ObjectId type represents a 12-byte MongoDB ObjectId identifier.

BSON.ObjectId(id)

Constructs a BSON.ObjectId object that encodes an ObjectId

Parameter
Type
Description
id
string
Optional. A 12-byte string or a string of 24 hex characters.
Returns:A BSON.ObjectId object that encodes the specified ObjectId string or a generated ObjectId string if none was specified.
Example
const objectId = new BSON.ObjectId("5e58667d902d38559c802b13");
const generatedObjectId = new BSON.ObjectId();

The BSON.BSONRegExp type represents a regular expression. You can use a BSON.BSONRegExp object with the $regex query operator to perform a regular expression query on a MongoDB collection.

BSON.BSONRegExp(pattern, flags)

Constructs a BSON.BSONRegExp object from a regular expression string. You can optionally specify configuration flags.

Parameter
Type
Description
pattern
string
flags
string
Optional. One or more regular expression flags.
Returns:A BSON.BSONRegExp object that encodes the provided regular expression pattern and flags.
Example
const regex = BSON.BSONRegExp("the great", "ig");

The BSON.Binary type represents a binary-encoded data string.

BSON.Binary.fromHex(hexString, subType)

Constructs a BSON.Binary object from data represented as a hexadecimal string.

Parameter
Type
Description
hexString
string
A byte aligned string of hexadecimal characters (0-9 and A-F).
subType
integer
Optional. The type of data encoded in the hexadecimal string. The value must be in the range 0-255 where 0, the default value, represents a generic binary. For a full list of supported subtypes, refer to the BSON specification.
Returns:A BSON.Binary object that encodes the provided hexadecimal string.
Example
const binary = BSON.Binary.fromHex("54657374206d65737361676520706c656173652069676e6f7265=");
BSON.Binary.toHex()

Converts the BSON.Binary object into a hexadecimal string.

Returns:A hexadecimal string representation of the provided BSON.Binary object.
Example
const binary = BSON.Binary.fromHex("54657374206d65737361676520706c656173652069676e6f7265=");
const hexString = binary.toHex();
BSON.Binary.fromBase64(base64String, subType)

Constructs a BSON.Binary object from data represented as a base64 string.

Parameter
Type
Description
base64String
string

A string of base64 encoded characters.

Note
String Padding

The base64-encoded string must include either one or two equals signs (=), referred to as "padding", at the end of the string. BSON.Binary.fromBase64() does not support unpadded strings.

subType
integer
Optional. The type of data encoded in the hexadecimal string. The value must be in the range 0-255 where 0, the default value, represents a generic binary. For a full list of supported subtypes, refer to the BSON specification.
Returns:A BSON.Binary object that encodes the provided base64 string.
Example
const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");
BSON.Binary.toBase64()

Converts the BSON.Binary object into a base64 string.

Returns:A base64 string representation of the BSON.Binary object.
Example
const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");
const base64String = binary.toBase64();
BSON.Binary.text()

Converts the BSON.Binary object into a UTF-8 string.

Returns:A UTF-8 string representation of the provided BSON.Binary object.
Example
const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");
const decodedString = binary.text();

The BSON.MaxKey type represents a value that compares higher than all other BSON values.

Example
await collection.findOne({ date: { $lt: BSON.MaxKey } });

The BSON.MinKey type represents a value that compares lower than all other BSON values.

Example
await collection.findOne({ date: { $gt: BSON.MinKey } });

The BSON.Int32 type represents a 32-bit signed integer.

BSON.Int32(integer)

Constructs a BSON.Int32 object from a 32-bit number.

Parameter
Type
Description
low32
number
A 32-bit number.
Returns:A BSON.Int32 object that encodes the specified integer. Returns 0 if no arguments are supplied.
Example
const int32 = BSON.Int32(42);

The BSON.Long type represents a 64-bit signed integer.

BSON.Long(low32, high32)

Constructs a BSON.Long object from two 32-bit integers that represent the low 32 bits and the high 32 bits in the 64-bit Long integer.

Parameter
Type
Description
low32
integer
Optional. The long integer's 32 low bits. These bits represent the least significant digits of the number.
high32
integer
Optional. The long integer's 32 high bits. These bits represent the most significant digits of the number.
Returns:A BSON.Long object that encodes the specified integer. Returns 0 if no arguments are supplied.

BSON.Long encodes using the following formula:

(high32 * (2**32)) + low32
Example
const long = BSON.Long(600206158, 342);

The BSON.Double type represents a 64-bit (8-byte) floating point number.

Important
Use Decimal128 for Money

BSON.Double is subject to floating point rounding errors, so it is not recommended for use cases where decimal values must round exactly, e.g. financial data. For these cases, use BSON.Decimal128 instead.

BSON.Double(double)

Constructs a BSON.Double object from a 64-bit decimal value.

Parameter
Type
Description
double
number
A 64-bit decimal value.
Returns:A BSON.Double object that encodes the specified double. Returns 0 if no argument is supplied.
Example
const double = BSON.Double(1234.5678);

The BSON.Decimal128 type represents a 128-bit (16-byte) floating point number. This type is intended for use cases where decimal values must round exactly, e.g. financial data.

BSON.Decimal128.fromString(decimalString)

Constructs a BSON.Decimal128 from a string representation of a decimal number.

Parameter
Type
Description
decimalString
string
A string representing a decimal number, e.g. "1234.5678910123456".
Returns:A BSON.Decimal128 that encodes the provided decimal value.
Example
const double = BSON.Decimal128.fromString("1234.5678910123456");
Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.