DOCS-410 count and index use/performance

source/includes/fact-count-index-use.rst

@@ -0,0 +1,39 @@
+Consider a collection with the following index:
+
+.. code-block:: javascript
+
+   { a: 1, b: 1 }
+
+When performing a count, MongoDB can return the count using only the
+index if:
+
+- the query can use an index,
+
+- the query only contains conditions on the keys of the index, *and*
+
+- the query predicates access a single contiguous range of index keys.
+
+For example, the following operations can return the count using only
+the index:
+
+.. code-block:: javascript
+
+   db.collection.find( { a: 5, b: 5 } ).count()
+   db.collection.find( { a: { $gt: 5 } } ).count()
+   db.collection.find( { a: 5, b: { $gt: 10 } } ).count()
+
+If, however, the query can use an index but the query predicates do not
+access a single contiguous range of index keys or the query also
+contains conditions on fields outside the index, then in addition to
+using the index, MongoDB must also read the documents to return the
+count.
+
+.. code-block:: javascript
+
+   db.collection.find( { a: 5, b: { $in: [ 1, 2, 3 ] } } ).count()
+   db.collection.find( { a: { $gt: 5 }, b: 5 } ).count()
+   db.collection.find( { a: 5, b: 5, c: 5 } ).count()
+
+In such cases, during the initial read of the documents, MongoDB pages
+the documents into memory such that subsequent calls of the same count
+operation will have better performance.

source/reference/method/cursor.count.txt

@@ -25,26 +25,34 @@ Definition
 
    .. code-block:: javascript
 
-      db.collection.find().count()
+      db.collection.find(<query>).count()
 
    The :method:`~cursor.count()` method has the following
    parameter:
 
    .. include:: /reference/method/cursor.count-param.rst
 
-   MongoDB also provides the shell wrapper
-   :method:`db.collection.count()` for the
-   ``db.collection.find().count()`` construct.
+   MongoDB also provides an equivalent :method:`db.collection.count()`
+   as an alternative to the ``db.collection.find(<query>).count()``
+   construct.
 
    .. seealso:: :method:`cursor.size()`
 
 Behavior
 --------
 
+Sharded Clusters
+~~~~~~~~~~~~~~~~
+
 .. |count-op| replace:: :method:`~cursor.count()` method
 
 .. include:: /includes/fact-count-on-sharded-clusters.rst
 
+Index Use
+~~~~~~~~~
+
+.. include:: /includes/fact-count-index-use.rst
+
 Examples
 --------
 

source/reference/method/db.collection.count.txt

@@ -19,15 +19,26 @@ Definition
 
    .. include:: /reference/method/db.collection.count-param.rst
 
+   The :method:`db.collection.count()` method is equivalent to the
+   ``db.collection.find(<query>).count()`` construct.
+
 .. seealso:: :method:`cursor.count()`
 
 Behavior
 --------
 
+Sharded Clusters
+~~~~~~~~~~~~~~~~
+
 .. |count-op| replace:: :method:`db.collection.count()`
 
 .. include:: /includes/fact-count-on-sharded-clusters.rst
 
+Index Use
+~~~~~~~~~
+
+.. include:: /includes/fact-count-index-use.rst
+
 Examples
 --------