Fetching contributors…
Cannot retrieve contributors at this time
214 lines (149 sloc) 6.54 KB
Capped Collections
.. default-domain:: mongodb
.. contents:: On this page
:backlinks: none
:depth: 1
:class: singlecol
:term:`Capped collections <capped collection>` are fixed-size
collections that support high-throughput operations that insert
and retrieve documents based on insertion order. Capped
collections work in a way similar to circular buffers: once a
collection fills its allocated space, it makes room for new documents
by overwriting the oldest documents in the collection.
See :method:`~db.createCollection()` or :dbcommand:`create`
for more information on creating 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.
For example, the :term:` <oplog>` collection that stores a log
of the operations in a :term:`replica set` uses a capped
collection. Consider the following potential use cases for capped
- 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.
- 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
``_id`` Index
Capped collections have an ``_id`` field and an index on the ``_id``
field by default.
.. _capped-collections-recommendations-and-restrictions:
Restrictions and Recommendations
If you plan to update documents in a capped collection, create an index
so that these update operations do not require a collection scan.
Document Size
.. versionchanged:: 3.2
.. include:: /includes/extracts/capped-collection-immutable-document-size.rst
Document Deletion
You cannot delete documents from a capped collection. To remove all
documents from a collection, use the :method:`~db.collection.drop()`
method to drop the collection and recreate the capped collection.
You cannot shard a capped collection.
Query Efficiency
Use natural ordering to retrieve the most recently inserted elements
from the collection efficiently. This is (somewhat) analogous to tail
on a log file.
Aggregation ``$out``
The aggregation pipeline operator :pipeline:`$out` cannot write results
to a capped collection.
.. include:: /includes/replacement-mms.rst
Create a Capped Collection
You must create capped collections explicitly using the
:method:`db.createCollection()` method, which is a helper in the
:program:`mongo` shell for the :dbcommand:`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.
.. code-block:: javascript
db.createCollection( "log", { capped: true, size: 100000 } )
If the ``size`` field is less than or equal to 4096, then the collection will
have a cap of 4096 bytes. Otherwise, MongoDB will raise the provided size to
make it an integer multiple of 256.
Additionally, you may also specify a maximum number of documents for the
collection using the ``max`` field as in the following document:
.. code-block:: javascript
db.createCollection("log", { capped : true, size : 5242880, max : 5000 } )
.. important:: The ``size`` argument is *always* required, even when
you specify ``max`` number of documents. MongoDB will remove older
documents if a collection reaches the maximum size limit before it
reaches the maximum document count.
.. see:: :method:`db.createCollection()` and :dbcommand:`create`.
.. _capped-collections-options:
Query a Capped Collection
If you perform a :method:`~db.collection.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
:method:`~db.collection.find()` along with the :method:`~cursor.sort()`
method with the :operator:`$natural` parameter set to ``-1``, as shown
in the following example:
.. code-block:: javascript
db.cappedCollection.find().sort( { $natural: -1 } )
Check if a Collection is Capped
Use the :method:`~db.collection.isCapped()` method to determine if a
collection is capped, as follows:
.. code-block:: javascript
Convert a Collection to Capped
You can convert a non-capped collection to a capped collection with
the :dbcommand:`convertToCapped` command:
.. code-block:: javascript
db.runCommand({"convertToCapped": "mycoll", size: 100000});
The ``size`` parameter specifies the size of the capped collection in
.. include:: /includes/warning-blocking-global.rst
Automatically Remove Data After a Specified Period of Time
For additional flexibility when expiring data, consider MongoDB's
:term:`TTL` indexes, as described in
:doc:`/tutorial/expire-data`. These indexes allow you to expire and
remove data from normal collections using a special type, based on the
value of a date-typed field and a TTL value for the index.
:doc:`TTL Collections </tutorial/expire-data>` are not compatible with
capped collections.
Tailable Cursor
You can use a :term:`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
See :doc:`/core/tailable-cursors` for information on creating
a tailable cursor.