Working with MongoDB Capped Collections from Java

Have a Database Problem? Speak with an Expert for Free
Get Started >>


In MongoDB, there’s normally no limit on the size of a collection. The more documents you index, the larger the collection grows. However, for log storage or high-throughput applications, an unlimited-size collection isn’t always an ideal structure. In these cases, it’s often preferable to use a different type of collection called a capped collection. In this article, we’ll learn more about this special collection type and discuss the advantages and disadvantages of working with MongoDB capped collections in Java.


Before we take a closer look at capped collections and how they work, it’s important to review the system requirements. For this task, there’s only one prerequisite: You must ensure that both MongoDB and the MongoDB Java driver have been properly configured beforehand.

What are MongoDB Capped Collections?

As we said in the introduction, most MongoDB collections are not limited in size. Capped collections, on the other hand, are fixed-size circular collections that follow insertion order. The term “circular” refers to the fact that when the fixed size allocated to a capped collection has been reached, it will automatically start deleting the oldest documents in the collection and overwriting them to accommodate the new documents– much like a circular buffer. Another key characteristic of capped collections is the preservation of insertion order; this eliminates the need for an index to return documents in order of insertion. Overall, the structure and functionality of a capped collection supports high performance for create, read, and delete operations.

Use Cases for a MongoDB Capped Collection

Although a standard MongoDB collection will work well in most circumstances, there are certain use cases where performance can be optimized by using a capped collection instead. A few common use cases include:

  1. Logging information
  2. Cache data
  3. Audit information

In all of these use cases, performance is optimized by the elimination of an index as well as the circular (first-in-first-out) nature of the collection, which maintains order and keeps storage use in check.

How to Create a MongoDB Capped Collection using Java

Now that we understand how capped collections work, let’s look at some code that utilizes them. The code below shows an example of how to create a MongoDB capped collection:

MongoClient mongo = MongoClients.create("mongodb://"); // (1)
MongoDatabase db = mongo.getDatabase("heroDB"); // (2)
db.createCollection("heroColl", new CreateCollectionOptions() // (3)

There’s a lot going on in these few lines of code, so let’s take a closer look and review what’s happening, line by line:

  1. First, we connect to a MongoDB deployment that’s running locally.
  2. Once the MongoDB client instance is connected to the MongoDB deployment, we use the getDatabase() method to access the database.
  3. Finally, we use the createCollection() method to explicitly create a collection. This method enables the user to provide various options using the CreateCollectionOptions(). In this example, we indicated that the collection would be capped and that its size in bytes would be 256.

After the code executes, we’ll have a new heroColl collection in the heroDB database with a limited size of 256 Bytes.

NOTE : MongoDB will automatically create an index on the _id field, but this auto index can be disabled to improve performance on inserts.

If you choose to disable the auto index, the code will look something like this:

db.createCollection("heroColl", new CreateCollectionOptions()

How to Insert a MongoDB Document into a MongoDB Capped Collection using Java

Next, we’ll look at an example where we insert a document into our capped collection:

MongoClient mongo = MongoClients.create("mongodb://");
MongoDatabase db = mongo.getDatabase("heroDB");
Document doc = new Document("heroName", "Ethan")
.append("age", 25)
.append("nationality", "American")
.append("movie", "mission impossible");


After running this code, we can verify the insert operation using the MongoDB Shell.

  • First, access the “heroDB” database:
use heroDB
switched to db heroDB
  • Then, find the documents within the “heroCall” collection:
  • The results that are returned should look like the following:
"_id" : ObjectId("5ce4dc71a7986c1842433d0f"),
"heroName" : "Ethan",
"age" : 25,
"nationality" : "American",
"movie" : "mission impossible"

Advantages of a MongoDB Capped Collection

There are a few key advantages to working with MongoDB capped collections:

  1. MongoDB capped collections provide higher throughput because queries don’t need an index to return documents in order of insertion.

  2. A capped collection will only perform an update if the updated document fits the original document size. This ensures that the documents do not change their location on disk.

  3. The fixed size and circular nature of a capped collection makes it an ideal choice for storing log files.

Disadvantages of a MongoDB Capped Collection

Although there are several benefits of using capped collection, there are a few drawbacks to keep in mind:

  1. An update operation will fail if the update increases the original size of a MongoDB capped collection.

  2. You can’t delete documents in a capped collection. Deletion occurs automatically when the fixed size has been reached and the oldest document is deleted to make room for a new one. You can, however, use the {emptycapped: theCollection} to delete all documents from a capped collection.

  3. You can’t shard a MongoDB capped collection.


If you’re just getting acquainted with capped collections in MongoDB, you can see that they’re quite different from standard collections. Capped collections offer many advantages for high-volume log storage and high-throughput applications, so it’s important to understand how they work and know how to use them. With the instructions provided in this tutorial, you’ll have no trouble working with MongoDB capped collections in your own applications.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.