Explaining BSON with Examples | MongoDB

This is my original tutorial, republished on this website. The examples are preserved. Tool versions and interfaces may have changed.

What is BSON? BSON Explained

BSON essentially is binary encoded Javascript Object Notation (JSON) - a textual object notation widely used to transmit and store data across web based applications. Because BSON is binary encoded JSON, it is easy to generate and parse for machines. JSON is easier to understand as it is human-readable but compared to BSON it supports fewer data types. BSON encodes type and length information, making it easier for machines to parse. Just like JSON, BSON supports various programming languages such as C, C++, C#, Java, JavaScript, PHP, Python, Ruby and Swift.

What does BSON stand for?

BSON stands for Binary Javascript Object Notation. It is a binary-encoded serialization of JSON documents.

BSON file types

BSON files have the extension .bson.

BSON specifications and BSON types

BSON specification version 1.1 is published at bsonspec.org. The topmost element in the structure must be of type BSON object and should contain 1 or more elements, where an element can be a field name (string), a type or a value. The following are some of the types included in BSON.

byte	1 byte (8-bits)
int32	4 bytes (32-bit signed integer, two's complement)
int64	8 bytes (64-bit signed integer, two's complement)
uint64	8 bytes (64-bit unsigned integer)
double	8 bytes (64-bit IEEE 754-2008 binary floating-point)
decimal128	16 bytes (128-bit IEEE 754-2008 decimal floating-point)

To learn more about BSON specifications, visit BSON documentation.

How is BSON different from JSON?

	JSON	BSON
Type	JSON files are written in text format.	BSON files are written in binary.
Speed	JSON is fast to read but slower to build.	BSON is slow to read but faster to build.
Space	JSON data is slightly smaller in byte size.	BSON data is slightly larger in byte size.
Encode and Decode	We can send JSON through APIs without encoding and decoding.	BSON files are encoded before storing and decoded before displaying.
Parse	JSON is a human-readable format that doesn't require parsing.	BSON needs to be parsed as they are machine generated and not human readable.
Data Types	JSON has a specific set of data types - string, boolean, number for numeric data types, array, object and null.	Unlike JSON, BSON offers additional data types such as bindata for binary data, decimal128 for numeric.
Usage	Used to send data through the network (mostly through APIs)	Databases use BSON to store data.

To know more about the differences between BSON and JSON, visit JSON and BSON.

Advantages of BSON. Why does MongoDB use BSON?

The following three characteristics make BSON advantageous to use.

Lightweight and Traversable

BSON is lightweight. This makes it possible for a large amount of data to be stored in BSON file format. Additionally, BSON files are easily stored and sent through the network. Therefore, they are perfect for storing and sending data.

Efficient

BSON was made to be efficient in storing space and scan. In a BSON document, large elements are prefixed with a length field. This makes it easier to scan the documents. The documents use more space than JSON due to the length prefixes and explicit array indices. But, because of those prefixes, we are able to scan and query much faster with BSON. It is also easy to compare and calculate directly on data, simplifying application code consumption.

Additional Data Types

Unlike in JSON, you can find data types such as Bindata, Minkey, Maxkey, Binary Data, ObjectID, Regular Expression, JavaScript, Decimal128, Date for datetime in BSON. These data types are crucial when working with specialty programs. For example, when working with financial systems data, you can use BSON’s Decimal128 for 128 bits of high precision decimal representation. Many modern systems use a binary-based floating-point arithmetic to represent exact decimal fractions through Float and double data types. These data types provide approximation but not the precise value. Using BSON in such cases gives you high precision. Visit BSON data types to find the list of datatypes exclusive to BSON but not to JSON.

How to convert JSON to BSON (or vice versa)?

You can use various converters to interchange between JSON and BSON formats. They are available on the internet and easily change the JSON format to BSON format and vice versa. You can also store your data in MongoDB Atlas which will convert your data into BSON in your database. You can learn more about MongoDB Atlas here.

How to open a BSON document?

You can use specific software to open BSON files. There are also plenty of online BSON text viewers that are capable of opening BSON files. If you have a large set of BSON files, you can import BSON files to MongoDB to see the contents of the file from there.

How to import and export BSON documents in MongoDB?

You can easily import and export BSON files in MongoDB by using a few simple commands.The mongorestore command loads data from either a binary database dump created by mongodump or the standard input into a mongod or mongos instance. To import a .bson file, run the following command on mongo shell.

mongorestore -d db_name /path/file.bson

Here, db_name is the name of the database you want to import. path denotes the absolute path of your .bson file, while file represents the BSON file’s name. For a single collection, run the following command on mongo shell.

mongorestore --drop -d db_name -c collection_name /path/file.bson

Here**, collection_name** defines the name of the collection that you want to import. For restoring the complete folder exported by mongodump:

mongorestore -d db_name /path/

If you face any problems with a programming language, be sure to update the mongodb driver to the version that supports the language.

BSON Document Example. How BSON is stored in MongoDB Database?

Let’s take the following JSON document example.

{
"hello" : "world"
}

When storing the JSON document, it will be converted to the following.

\x16\x00\x00\x00             // total document size
\x02                         // 0x02 = type String
hello\x00                    // field name
\x06\x00\x00\x00world\x00    // field value (size of value, value, null terminator         
\x00                         // 0x00 = type EOO ('end of object')

Relevant FAQs:

Can a BSON string be null?

Yes. They can contain null.

What is BSON data type?

BSON has various data types which are not included in JSON such as Date for datetime and ObjectID.

What does BSON look like?

BSON is a binary-encoded serialized format of JSON documents. It has characters which are not human readable.

Why does MongoDB use BSON rather than JSON?

BSON is easier to generate and parse for machines and also supports more data types than JSON.