Navigation

JSON & BSON

Overview

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
JSON Includes methods that convert between string and object representations of JSON data.
EJSON Includes methods that convert between string and object representations of Extended JSON data.
BSON Includes methods that create Binary JSON objects and convert between various BSON data types and encodings.

JSON (JavaScript Object Notation)

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 string 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 object = JSON.parse(jsonString);
JSON.stringify(object)

Serializes the provided JavaScript object to a JSON string.

Parameter Type Description
object 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);

EJSON (Extended JSON)

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 object = 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 (Binary JSON)

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.

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.

BSON.ObjectId

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();

BSON.BSONRegExp

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 A regular expression pattern.
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");

BSON.Binary

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.

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();

BSON.MaxKey

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

Example

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

BSON.MinKey

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

Example

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

BSON.Int32

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);

BSON.Long

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);

BSON.Double

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

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);

BSON.Decimal128

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");
←   Utility Packages Triggers  →