Capped Collections

Insertion Order

Capped collections guarantee preservation of the insertion order. As a result, queries do not need an index to return documents in insertion order. Without this indexing overhead, capped collections can support higher insertion throughput.

Automatic Removal of Oldest Documents

To make room for new documents, capped collections automatically remove the oldest documents in the collection without requiring scripts or explicit remove operations.

Consider the following potential use cases for capped collections:

• Store log information generated by high-volume systems. Inserting documents in a capped collection without an index is close to the speed of writing log information directly to a file system. Furthermore, the built-in first-in-first-out property maintains the order of events, while managing storage use. For example, the oplog uses a capped collection.

• Cache small amounts of data in a capped collections. Since caches are read rather than write heavy, you would either need to ensure that this collection always remains in the working set (i.e. in RAM) or accept some write penalty for the required index or indexes.

Oplog Collection

The oplog.rs collection that stores a log of the operations in a replica set uses a capped collection.

Starting in MongoDB 4.0, unlike other capped collections, the oplog can grow past its configured size limit to avoid deleting the majority commit point.

_id Index

Capped collections have an _id field and an index on the _id field by default.

Reads

Starting in MongoDB 5.0, you cannot use read concern "snapshot" when reading from a capped collection.

Updates

If you plan to update documents in a capped collection, create an index so that these update operations do not require a collection scan.

Sharding

You cannot shard a capped collection.

Query Efficiency

Use natural ordering to retrieve the most recently inserted elements from the collection efficiently. This is similar to using the tail command on a log file.

Aggregation $out

The aggregation pipeline stage $out cannot write results to a capped collection.

Transactions

You cannot write to capped collections in transactions.

Stable API

Capped collections are not supported in Stable API V1.

Create a Capped Collection

You must create capped collections explicitly using the db.createCollection() method, which is a mongosh helper for the create command. When creating a capped collection you must specify the maximum size of the collection in bytes, which MongoDB will pre-allocate for the collection. The size of the capped collection includes a small amount of space for internal overhead.

db.createCollection( "log", { capped: true, size: 100000 } )

Additionally, you may also specify a maximum number of documents for the collection using the max field as in the following document:

db.createCollection("log", { capped : true, size : 5242880, max :
5000 } )

Query a Capped Collection

If you perform a find() on a capped collection with no ordering specified, MongoDB guarantees that the ordering of results is the same as the insertion order.

To retrieve documents in reverse insertion order, issue find() along with the sort() method with the $natural parameter set to -1, as shown in the following example:

db.cappedCollection.find().sort( { $natural: -1 } )

Check if a Collection is Capped

Use the isCapped() method to determine if a collection is capped, as follows:

db.collection.isCapped()

Convert a Collection to Capped

You can convert a non-capped collection to a capped collection with the convertToCapped command:

db.runCommand({"convertToCapped": "mycoll", size: 100000});

The size parameter specifies the size of the capped collection in bytes.

This holds a database exclusive lock for the duration of the operation. Other operations which lock the same database will be blocked until the operation completes. See What locks are taken by some common client operations? for operations that lock the database.

Change a Capped Collection's Size

You can resize a capped collection using the collMod command's cappedSize option to set the cappedSize in bytes. cappedSize must be greater than 0 and less than or equal to 1024^5 (1 PB).

For example, the following command sets the maximum size of the "log" capped collection to 100000 bytes:

db.runCommand( { collMod: "log", cappedSize: 100000 } )

Change the Maximum Number of Documents in a Capped Collection

To change the maximum number of documents in a capped collection, use the collMod command's cappedMax option. If cappedMax is less than or equal to 0, there is no maximum document limit. If cappedMax is less than the current number of documents in the collection, MongoDB removes the excess documents on the next insert operation.

For example, the following command sets the maximum number of documents in the "log" capped collection to 500:

db.runCommand( { collMod: "log", cappedMax: 500 } )

Tailable Cursor

You can use a tailable cursor with capped collections. Similar to the Unix tail -f command, the tailable cursor "tails" the end of a capped collection. As new documents are inserted into the capped collection, you can use the tailable cursor to continue retrieving documents.

See Tailable Cursors for information on creating a tailable cursor.