MongoDB BSON Guide

1. Introduction

In this tutorial, we’ll be looking at BSON and how we can use it to interact with MongoDB.

Now, an in-depth description of MongoDB and all of its capabilities is beyond the scope of this article. However, it’ll be useful to understand a few key concepts.

MongoDB is a distributed, NoSQL document storage engine. Documents are stored as BSON data and grouped together into collections. Documents in a collection are analogous to rows in a relational database table.

For a more in-depth information about Mongo db, have a look at the introductory MongoDB article.

2. What Is BSON?

BSON stands for Binary JSON. It’s a protocol for binary serialization of JSON-like data.

JSON is a data exchange format that is popular in modern web services. It provides a flexible way to represent complex data structures.

BSON provides several advantages over using regular JSON:

• Compact: In most cases, storing a BSON structure requires less space than its JSON equivalent
• Data Types: BSON provides additional data types not found in regular JSON, such as Date and BinData

One of the main benefits of using BSON is that it’s easy to traverse. BSON documents contain additional metadata that allow for easy manipulation of the fields of a document, without having to read the entire document itself.

3. The MongoDB Driver

Now that we have a basic understanding of BSON and MongoDB, let’s look at how to use them together. We’ll focus on the main actions from the CRUD acronym (Create, Read, Update, Delete).

MongoDB provides software drivers for most modern programming languages. The drivers are built on top of the BSON library, which means we’ll be working directly with the BSON API when building queries. For more information, see our guide to the MongoDB query language.

In this section, we’ll look at using the driver to connect to a cluster, and using the BSON API to perform different types of queries. Note that the MongoDB driver provides a Filters class that can help us write more compact code. For this tutorial, however, we’ll focus solely on using the core BSON API.

As an alternative to using the MongoDB driver and BSON directly, take a look at our Spring Data MongoDB guide.

3.1. Connecting

To get started, we first add the MongoDB driver as a dependency into our application:

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId>
    <version>4.8.2</version>
</dependency>

Then we create a connection to a MongoDB database and collection:

MongoClient mongoClient = MongoClients.create();
MongoDatabase database = mongoClient.getDatabase("myDB");
MongoCollection<Document> collection = database.getCollection("employees");

The remaining sections will look at creating queries using the collection reference.

3.2. Insert

Let’s say we have the following JSON that we want to insert as a new document into an employees collection:

{
  "first_name" : "Joe",
  "last_name" : "Smith",
  "title" : "Java Developer",
  "years_of_service" : 3,
  "skills" : ["java","spring","mongodb"],
  "manager" : {
     "first_name" : "Sally",
     "last_name" : "Johanson"
  }
}

This example JSON shows the most common data types we would encounter with MongoDB documents: text, numeric, arrays, and embedded documents.

To insert this using BSON, we’d use MongoDB’s Document API:

Document employee = new Document()
    .append("first_name", "Joe")
    .append("last_name", "Smith")
    .append("title", "Java Developer")
    .append("years_of_service", 3)
    .append("skills", Arrays.asList("java", "spring", "mongodb"))
    .append("manager", new Document()
        .append("first_name", "Sally")
        .append("last_name", "Johanson"));
collection.insertOne(employee);

The Document class is the primary API used in BSON. It extends the Java Map interface and contains several overloaded methods. This makes it easy to work with native types as well as common objects such as object IDs, dates, and lists.

3.3. Find

To find a document in MongoDB, we provide a search document that specifies which fields to query on. For example, to find all documents that have a last name of “Smith” we would use the following JSON document:

{  
  "last_name": "Smith"
}

Written in BSON this would be:

Document query = new Document("last_name", "Smith");
List results = new ArrayList<>();
collection.find(query).into(results);

“Find” queries can accept multiple fields and the default behavior is to use the logical and operator to combine them. This means only documents that match all fields will be returned.

To get around this, MongoDB provides the or query operator:

{
  "$or": [
    { "first_name": "Joe" },
    { "last_name":"Smith" }
  ]
}

This will find all documents that have either first name “Joe” or last name “Smith”. To write this as BSON, we would use a nested Document just like the insert query above:

Document query = 
  new Document("$or", Arrays.asList(
      new Document("last_name", "Smith"),
      new Document("first_name", "Joe")));
List results = new ArrayList<>();
collection.find(query).into(results);

3.4. Update

Update queries are a little different in MongoDB because they require two documents:

1. The filter criteria to find one or more documents
2. An update document specifying which fields to modify

For example, let’s say we want to add a “security” skill to every employee that already has a “spring” skill. The first document will find all employees with “spring” skills, and the second one will add a new “security” entry to their skills array.

In JSON, these two queries would look like:

{
  "skills": { 
    $elemMatch:  { 
      "$eq": "spring"
    }
  }
}

{
  "$push": { 
    "skills": "security"
  }
}

And in BSON, they would be:

Document query = new Document(
  "skills",
  new Document(
    "$elemMatch",
    new Document("$eq", "spring")));
Document update = new Document(
  "$push",
  new Document("skills", "security"));
collection.updateMany(query, update);

3.5. Delete

Delete queries in MongoDB use the same syntax as find queries. We simply provide a document that specifies one or more criteria to match.

For example, let’s say we found a bug in our employee database and accidentally created employees a with a negative value for years of service. To find them all, we would use the following JSON:

{
  "years_of_service" : { 
    "$lt" : 0
  }
}

The equivalent BSON document would be:

Document query = new Document(
  "years_of_service", 
  new Document("$lt", 0));
collection.deleteMany(query);

4. Conclusion

In this tutorial, we’ve seen a basic introduction to building MongoDB queries using the BSON library. Using only the BSON API, we implemented basic CRUD operations for a MongoDB collection.

What we have not covered are more advanced topics such as projections, aggregations, geospatial queries, bulk operations, and more. All of these are possible using just the BSON library. The examples we’ve seen here form the building blocks we would use to implement these more advanced operations.