DOCS-653 capped collections first draft

draft/core/capped-collections.txt

@@ -2,3 +2,157 @@
 Capped Collections
 ==================
 
+.. default-domain:: mongodb
+
+:term:`Capped collections <capped collection>` 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 <oplog>` 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()
+<db.collection.drop()>` method. After the drop you must explicitly
+recreate the collection.
+
+Capped collection are not shard-able.
+
+.. versionchanged:: 2.2
+
+All :term:`capped collections <capped collection>` 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() <db.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() <db.collection.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()
+<db.collection.find()>` along with the :method:`sort() <cursor.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`.
+

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:
 

source/reference/commands.txt

@@ -172,6 +172,8 @@ Geospatial Commands
 .. include:: command/geoSearch.txt
    :start-after: mongodb
 
+.. _collection-commands:
+
 Collection Commands
 ~~~~~~~~~~~~~~~~~~~