/ /

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 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 also supports other types, including dates, different size integers, ObjectId values, and binary data. For a complete list of supported types, see the BSON Types page in the MongoDB Server manual.

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

MongoDB and BSON

The 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. The following types implement the BSON interface:

Document (BSON library package)
BsonDocument (BSON library package)
RawBsonDocument (BSON library package)
JsonObject (BSON library package)
BasicDBObject (JVM package)

Install the BSON Library

This section shows how to add the BSON library as a dependency to your project. If you added the 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 Java driver as a dependency to your project, see the Get Started with the Java Driver guide.

Tip

Bill of Materials

We recommend adding the JVM driver Bill of Materials (BOM) to your application to manage the versions of driver artifacts. This removes the need to specify a version for any individual package covered by the BOM, simplifying dependency management. To learn more, see the Get Started with the Java Driver 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:

The following snippet shows the dependency declaration in the dependencies section of your pom.xml file.

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

The following snippet shows the dependency declaration in the dependencies object in your build.gradle file.

dependencies {
    compile 'org.mongodb:bson'
}

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.

How do I prevent the "IllegalArgumentException: Invalid BSON field name" error?

Your application might throw this exception if you pass an incorrectly formatted document to an operation and you are using Java driver v4.7 or earlier.

Note

In driver versions v4.8 and later, this error message was replaced by one that includes more specific details on what was incorrectly formatted.

For example, the driver throws this error when you call an update operation and incorrectly omit the update operator as shown in the following code example:

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

To avoid this error, use the builder class for the appropriate operation. The driver offers builder classes to create syntactically correct BSON for MongoDB operations. The preceding example can be correctly expressed using the builder classes, as shown in the following code example:

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

To learn more about the available builders classes, see the Builders guide.

Back

Update

Extended JSON