diff --git a/draft/core/capped-collections.txt b/draft/core/capped-collections.txt index 03bb605289e..e0242ba6ee4 100644 --- a/draft/core/capped-collections.txt +++ b/draft/core/capped-collections.txt @@ -2,3 +2,157 @@ Capped Collections ================== +.. default-domain:: mongodb + +:term:`Capped collections ` are fixed-size +collections that automatically overwrite their oldest documents when new +documents are inserted. Capped collections work in a way similar to +circular buffers. Once a collection fills its allocated space, it makes +room for new documents by deleting the oldest documents in the +collection. + +Capped collections are particularly fast and efficient for operations, +such as logging, that retrieve and delete documents based on insertion +order. + +Capped collections have the following behaviors: + +- Capped collections automatically store documents in their insertion + order. Therefore, no index is required to query on insertion order, + and capped collections incur no indexing overhead for this property. + +- Capped collections guarantee that insertion order is identical to the + order on disk (:term:`natural order`) and do so by prohibiting updates + that increase document size. Capped collections only allow updates + that fit the original document size, which ensures a document does not + change its location on disk. + +- Capped collections automatically remove the oldest documents in the + collection without requiring scripts or explicit remove operations. + +Capped collections provide a high-performance means for storing logging +information. Inserting documents in an unindexed capped collection is +close to the speed of logging to a filesystem. Additionally, the +built-in FIFO mechanism ensures logging does not use excessive disk +space. + +Capped collections also provide a convenient way to cache known small +numbers of documents, such as cached computations of information. This +scenario would likely have more reads than writes and require an index. + +The :term:`oplog.rs ` collection used in replication is an +example of a capped collection. + +Recommendations and Restrictions +-------------------------------- + +You cannot shard a capped collection. + +You may update the existing documents in the collection. However, the +documents must not grow in size. If they do, the update fails. + +Note that for versions prior to 2.2, if perform updates, you likely want +to declare an appropriate index as pre-2.2 versions do not create an +``_id`` index by default. + +You cannot delete documents from a capped collection. To remove all +records from the collection, use the :method:`drop() +` method. After the drop you must explicitly +recreate the collection. + +Capped collection are not shard-able. + +.. versionchanged:: 2.2 + +All :term:`capped collections ` have an ``_id`` field +by default and have indexes on the ``_id`` field, *with the exception* +of the capped collections in the ``local`` :term:`database`. This change +affects capped collections created with 2.2 instances and does not +affect capped collections created with pre-2.2 instances. + +.. warning:: + + Prior to 2.2, capped collections do not have a unique index on + ``_id``. If you are using a capped collection and + replication, you should create a unique index on ``_id``. + Ensure uniqueness by using the + default client-generated MongoDB ``_id`` or the ``autoIndexId`` + field, as explained in :ref:`capped-collections-options`. + +When appropriate, do not create indexes on a capped collection. If the +collection is written to much more than it is read from, it is +better to have no indexes. Note that you may create indexes on a capped +collection; however, you are then moving from "log speed" inserts to +"database speed" inserts -- that is, it still is quite fast by +database standards. + +Use natural ordering to retrieve the most recently inserted elements +from the collection efficiently. This is (somewhat) analogous to tail on +a log file. + +Procedures +---------- + +Create a Capped Collection +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unlike a standard collection, you must explicitly create a capped +collection using the :method:`createCollection() ` method. When you +do, you specify the collection size in bytes. The size must include +space for database headers. MongoDB then preallocates the space. + +.. code-block:: javascript + + db.createCollection("mycoll", {capped:true, size:100000}) + +.. seealso:: :method:`db.createCollection()` + +.. _capped-collections-options: + +Query a Capped Collection +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you perform a :method:`find() ` on a capped +collection with no ordering specified, the documents are returned in +insertion order. + +To retrieve documents in reverse insertion order, issue :method:`find() +` along with the :method:`sort() ` +method with the ``$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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can check if a collection is capped by using the ``isCapped()`` method: + +.. code-block:: javascript + + db.collection.isCapped() + +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}); + +Note that the size is in bytes. + +No indexes are created when the new capped collection is. If you +want the old indexes you must recreate them after it has been +converted. + +Automatically Remove Data After a Specified Period of Time +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To automatically remove data, use MongoDB’s :term:`TTL` feature, as +described in :ref:`/tutorial/expire-data`. + diff --git a/source/core/indexes.txt b/source/core/indexes.txt index dda9a8b0487..39b384e19cf 100644 --- a/source/core/indexes.txt +++ b/source/core/indexes.txt @@ -97,6 +97,7 @@ is a 12-byte unique identifiers suitable for use as the value of an for more information. .. todo:: fix the above when a full capped-collection page exists. + 2012.11.08 Note: The capped-collection page is now created and in the draft folder. .. _index-types-secondary: diff --git a/source/reference/commands.txt b/source/reference/commands.txt index 66f2237044f..451d9f49f48 100644 --- a/source/reference/commands.txt +++ b/source/reference/commands.txt @@ -172,6 +172,8 @@ Geospatial Commands .. include:: command/geoSearch.txt :start-after: mongodb +.. _collection-commands: + Collection Commands ~~~~~~~~~~~~~~~~~~~