Navigation

JSON & BSON

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.

ModuleDescription
JSONIncludes methods that convert between string and object representations of JSON data.
EJSONIncludes methods that convert between string and object representations of Extended JSON data.
BSONIncludes 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.

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

Serializes the provided JavaScript object to a JSON string.

ParameterTypeDescription
objectobjectA standard JavaScript Object.
Returns:A string representation of the provided JavaScript object.
Beaker IconExample
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.

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

Serializes the provided JavaScript object to an EJSON string.

ParameterTypeDescription
objectdocumentAn EJSON object. The object may contain BSON types.
Returns:A string representation of the provided EJSON object.
Beaker IconExample
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.

Info With Circle IconCreated with Sketch.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

ParameterTypeDescription
idstringOptional. 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.
Beaker IconExample
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.

ParameterTypeDescription
patternstringA regular expression pattern.
flagsstringOptional. One or more regular expression flags.
Returns:A BSON.BSONRegExp object that encodes the provided regular expression pattern and flags.
Beaker IconExample
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.

ParameterTypeDescription
hexStringstringA byte aligned string of hexadecimal characters (0-9 and A-F).
subTypeintegerOptional. 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.
Beaker IconExample
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.
Beaker IconExample
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.

ParameterTypeDescription
base64Stringstring

A string of base64 encoded characters.

Info With Circle IconCreated with Sketch.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.

subTypeintegerOptional. 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.
Beaker IconExample
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.
Beaker IconExample
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.
Beaker IconExample
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.

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

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

Beaker IconExample
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.

ParameterTypeDescription
low32numberA 32-bit number.
Returns:A BSON.Int32 object that encodes the specified integer. Returns 0 if no arguments are supplied.
Beaker IconExample
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.

ParameterTypeDescription
low32integerOptional. The long integer's 32 low bits. These bits represent the least significant digits of the number.
high32integerOptional. 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
Beaker IconExample
const long = BSON.Long(600206158, 342);

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

Important With Circle IconCreated with Sketch.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.

ParameterTypeDescription
doublenumberA 64-bit decimal value.
Returns:A BSON.Double object that encodes the specified double. Returns 0 if no argument is supplied.
Beaker IconExample
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.

ParameterTypeDescription
decimalStringstringA string representing a decimal number, e.g. "1234.5678910123456".
Returns:A BSON.Decimal128 that encodes the provided decimal value.
Beaker IconExample
const double = BSON.Decimal128.fromString("1234.5678910123456");
Give Feedback