Document Data Format: BSON

Overview

In this guide, you can learn about the BSON data format, how MongoDB uses it, and how to install the BSON library independently of the MongoDB Java driver.

BSON Data Format

BSON, or Binary JSON, is the data format that MongoDB uses to organize and store data. This data format includes all JSON data structure types and adds support for types including dates, different size integers, ObjectIds, and binary data. For a complete list of supported types, see the BSON Types server manual page.

The binary format is not human-readable, but you can use the Java BSON library to convert it to a JSON representation. You can read more about the relationship between these formats in our article on JSON and BSON.

MongoDB and BSON

The MongoDB Java Driver, which uses the BSON library, allows you to work with BSON data by using one of the object types that implements the BSON interface, including:

• Document (BSON library package)

• BsonDocument (BSON library package)

• RawBsonDocument (BSON library package)

• JsonObject (BSON library package)

• BasicDBObject (Java Driver package)

For more information about using these object types, see our Documents guide.

Install the BSON Library

These instructions show you how to add the BSON library as a dependency to your project. If you added the MongoDB Java driver as a dependency to your project, you can skip this step since the BSON library is already included as a required dependency of the driver. For instructions on how to add the MongoDB Java driver as a dependency to your project, see the driver installation section of our Quick Start guide.

We recommend that you use the Maven or Gradle build automation tool to manage your project's dependencies. Select from the following tabs to see the dependency declaration for that tool:

<dependencies>
    <dependency>
        <groupId>org.mongodb</groupId>
        <artifactId>bson</artifactId>
        <version>5.3.0</version>
    </dependency>
</dependencies>

dependencies {
   compile 'org.mongodb:bson:5.3.0'
}

If you are not using one of the preceding tools, you can include it in your project by downloading the JAR file directly from the sonatype repository.

Frequently Asked Questions

This section answers questions that may arise when using the BSON data format.

// incorrectly formatted update document
collection.updateOne(
    new Document().append("name", "fizz"),
    new Document().append("name", "buzz")
);

// Builder class imports
import static com.mongodb.client.model.Filters.*;
import static com.mongodb.client.model.Updates.*;
// ...
collection.updateOne(eq("name", "fizz"), set("name", "buzz"));