DOCS-11947: countDocuments and estimatedDocumentCount

Author: kay-kim

config/redirects

@@ -1425,8 +1425,8 @@ raw: /master/release-notes/3.0-general-improvements -> ${base}/release-notes/3.0
 [v3.0-v3.6]: /${version}/tutorial/upgrade-to-enterprise-replica-set -> ${base}/${version}/installation
 [v3.0-v3.6]: /${version}/tutorial/upgrade-to-enterprise-sharded-cluster -> ${base}/${version}/installation
 
-
-
+[*-v3.6]: /${version}/reference/method/db.collection.countDocuments -> ${base}/${version}/reference/operator/aggregation/count
+[*-v3.6]: /${version}/reference/method/db.collection.estimatedDocumentCount -> ${base}/${version}/reference/method/db.collection.count
 [*-v3.6]: /${version}/reference/method/db.watch -> ${base}/${version}/changeStreams
 [*-v3.6]: /${version}/reference/method/Mongo.watch -> ${base}/${version}/changeStreams
 

source/aggregation.txt

@@ -95,8 +95,8 @@ can also output to a sharded collection. See
 Single Purpose Aggregation Operations
 -------------------------------------
 
-MongoDB also provides :method:`db.collection.count()` and
-:method:`db.collection.distinct()`.
+MongoDB also provides :method:`db.collection.estimatedDocumentCount()`,
+:method:`db.collection.count()` and :method:`db.collection.distinct()`.
 
 All of these operations aggregate documents from a single collection.
 While these operations provide simple access to common aggregation

source/core/transactions.txt

@@ -105,6 +105,10 @@ collection-level API ``countDocuments(filter, options)`` as a helper
 method that uses the :pipeline:`$group` with a :group:`$sum` expression
 to perform a count. The 4.0 drivers have deprecated the ``count()`` API.
 
+Starting in MongoDB 4.0.3, the :binary:`~bin.mongo` shell provides the
+:method:`db.collection.countDocuments()` helper method that uses the
+:pipeline:`$group` with a :group:`$sum` expression to perform a count.
+
 .. _transactions-ops-info:
 
 Informational Operations

source/core/views.txt

@@ -101,5 +101,7 @@ restrictions mentioned in this page:
      - | :method:`db.collection.aggregate()`
        | :method:`db.collection.find()`
        | :method:`db.collection.findOne()`
+       | :method:`db.collection.countDocuments()`
+       | :method:`db.collection.estimatedDocumentCount()`
        | :method:`db.collection.count()`
        | :method:`db.collection.distinct()`

source/includes/extracts-views.yaml

@@ -13,6 +13,8 @@ content: |
    - :method:`db.collection.find()`
    - :method:`db.collection.findOne()`
    - :method:`db.collection.aggregate()`
+   - :method:`db.collection.countDocuments()`
+   - :method:`db.collection.estimatedDocumentCount()`
    - :method:`db.collection.count()`
    - :method:`db.collection.distinct()`
 

source/includes/ref-toc-method-collection.yaml

@@ -14,6 +14,17 @@ name: ":method:`db.collection.count()`"
 file: /reference/method/db.collection.count
 description: "Wraps :dbcommand:`count` to return a count of the number of documents in a collection or a view."
 ---
+name: ":method:`db.collection.countDocuments()`"
+file: /reference/method/db.collection.countDocuments
+description: |
+   Wraps the :pipeline:`$group` aggregation stage with a :group:`$sum`
+   expression to return a count of the number of documents in a
+   collection or a view.
+---
+name: ":method:`db.collection.estimatedDocumentCount()`"
+file: /reference/method/db.collection.estimatedDocumentCount
+description: "Wraps :dbcommand:`count` to return an approximate count of the documents in a collection or a view."
+---
 name: ":method:`db.collection.createIndex()`"
 file: /reference/method/db.collection.createIndex
 description: "Builds an index on a collection."

source/includes/table-transactions-operations.rst

@@ -17,6 +17,12 @@
        - :pipeline:`$listSessions`
        - :pipeline:`$out`
 
+   * - :method:`db.collection.countDocuments()` 
+     -
+
+     - Uses the :pipeline:`$group` aggregation stage with a
+       :group:`$sum` expression to perform a count.
+
    * - :method:`db.collection.distinct()`
      - :dbcommand:`distinct`
      - 

source/reference/command/count.txt

@@ -44,17 +44,20 @@ Definition
 
    .. include:: /includes/apiargs/dbcommand-count-field.rst
 
-   MongoDB also provides the :method:`~cursor.count()` and
-   :method:`db.collection.count()` wrapper methods in the
-   :binary:`~bin.mongo` shell.
+   The :binary:`~bin.mongo` shell also provides the following wrapper methods for :dbcommand:`count`:
+   
+   - :method:`~cursor.count()`
+   - :method:`db.collection.estimatedDocumentCount()`
+   - :method:`db.collection.count()`
 
    .. important::
 
       - Avoid using the :dbcommand:`count` and its wrapper methods
-        without a query predicate since without the query predicate,
-        these operations return results based on the collection's
-        metadata, which may result in an approximate count. In
-        particular,
+        without a query predicate (note:
+        :method:`db.collection.estimatedDocumentCount()` does not take
+        a query predicate) since without the query predicate, these
+        operations return results based on the collection's metadata,
+        which may result in an approximate count. In particular,
 
         - On a sharded cluster, the resulting count will not correctly
           filter out :term:`orphaned documents <orphaned document>`.

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

@@ -56,7 +56,11 @@ Definition
    :method:`~db.collection.count()` is equivalent to the
    ``db.collection.find(query).count()`` construct.
 
-.. seealso:: :method:`cursor.count()`
+.. seealso:: 
+
+   - :method:`cursor.count()`
+   - :method:`db.collection.estimatedDocumentCount()`
+   - :method:`db.collection.countDocuments()`
 
 Behavior
 --------

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

@@ -0,0 +1,128 @@
+==============================
+db.collection.countDocuments()
+==============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. method:: db.collection.countDocuments(query, options)
+
+   .. versionadded:: 4.0.3
+
+   Returns the count of documents that match the query for a collection
+   or view. The method wraps the :pipeline:`$group` aggregation stage
+   with a :group:`$sum` expression to perform the count and is
+   available for use in :doc:`/core/transactions`.
+
+   .. code-block:: javascript
+   
+      db.collection.countDocuments( <query>, <options> )
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 20 80
+      
+      * - Parameter
+        - Type
+        - Description
+        
+      * - query
+        - document
+
+        - The query selection criteria. To count all documents, specify
+          an empty document.
+
+      * - options
+        - document
+        - Optional. Extra options that affects the count behavior.
+
+   The ``options`` document can contain the following:
+   
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 20 80
+      
+      * - Field
+        - Type
+        - Description
+
+      * - ``limit``
+        - integer
+        - Optional. The maximum number of documents to count.
+        
+      * - ``skip``
+        - integer
+        - Optional. The number of documents to skip before counting.
+        
+      * - ``hint``
+        - string or document
+
+        - Optional. An index name or the index specification to use for the query.
+
+      * - ``maxTimeMS``
+        - integer
+        - Optional. The maximum amount of time to allow the count to run.
+
+Behavior
+--------
+
+Unlike :method:`db.collection.count()`,
+:method:`db.collection.countDocuments()` does not use the metadata to
+return the count. Instead, it performs an aggregation of the document
+to return an accurate count, even after an unclean shutdown or in the
+presence of :term:`orphaned documents <orphaned document>` in a sharded
+cluster.
+
+:method:`db.collection.countDocuments()` wraps the following
+aggregation operation and returns just the value of ``n``:
+
+.. code-block:: javascript
+
+   db.collection.aggregate([
+      { $match: <query> },
+      { $group: { _id: null, n: { $sum: 1 } } } )
+   ])
+
+:method:`db.collection.countDocuments()` errors on an empty or
+non-existing collection or view.
+
+Examples
+--------
+
+Count all Documents in a Collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To count the number of all documents in the ``orders`` collection, use
+the following operation:
+
+.. code-block:: javascript
+
+   db.orders.countDocuments({})
+
+Count all Documents that Match a Query
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Count the number of the documents in the ``orders``
+collection with the field ``ord_dt`` greater than ``new
+Date('01/01/2012')``:
+
+.. code-block:: javascript
+
+   db.orders.countDocuments( { ord_dt: { $gt: new Date('01/01/2012') } }, { limit: 100 } )
+
+.. seealso::
+
+   - :method:`db.collection.estimatedDocumentCount()`
+   - :pipeline:`$group` and :group:`$sum`
+   - :dbcommand:`count`
+   - :ref:`collStats pipeline stage with the count <collstat-count>`
+     option.
+

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

@@ -0,0 +1,87 @@
+======================================
+db.collection.estimatedDocumentCount()
+======================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. method:: db.collection.estimatedDocumentCount(options)
+
+   .. versionadded:: 4.0.3
+
+   Returns the count of all documents in a collection or view. The
+   method wraps the :dbcommand:`count` command.
+
+   .. code-block:: javascript
+
+      db.collection.estimatedDocumentCount( <options> )
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 20 80
+
+      * - Parameter
+        - Type
+        - Description
+
+      * - options
+        - document
+        - Optional. Extra options that affect the count behavior.
+
+   The ``options`` document can contain the following:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 20 80
+
+      * - Field
+        - Type
+        - Description
+
+      * - ``maxTimeMS``
+        - integer
+        - Optional. The maximum amount of time to allow the count to run.
+
+
+Behavior
+--------
+
+:method:`db.collection.estimatedDocumentCount()` does not take a query
+filter and instead uses metadata to return the count for a collection.
+
+- On a sharded cluster, the resulting count will not correctly filter
+  out :term:`orphaned documents <orphaned document>`.
+
+- After an unclean shutdown, the count may be incorrect.
+
+  .. include:: /includes/fact-unexpected-shutdown-accuracy.rst
+
+  .. |cmd| replace:: :method:`db.collection.estimatedDocumentCount()`
+  .. |opt| replace:: count
+
+
+Example
+-------
+
+The following example uses
+:method:`db.collection.estimatedDocumentCount` to retrieve the count of
+all documents in the ``orders`` collection:
+
+.. code-block:: javascript
+
+   db.orders.estimatedDocumentCount({})
+
+.. seealso:: 
+
+   - :method:`db.collection.countDocuments()`
+   - :dbcommand:`count`
+   - :ref:`collStats pipeline stage with the count <collstat-count>`
+     option.

source/reference/operator/aggregation/count.txt

@@ -32,7 +32,9 @@ Definition
 
    .. seealso::
 
+      - :method:`db.collection.countDocuments()`
       - :pipeline:`$collStats`
+      - :method:`db.collection.estimatedDocumentCount()`
       - :dbcommand:`count`
       - :method:`db.collection.count()`
 
@@ -52,6 +54,9 @@ The :pipeline:`$count` stage is equivalent to the following
 where ``myCount`` would be the output field that contains the count.
 You can specify another name for the output field.
 
+.. seealso:: :method:`db.collection.countDocuments()` which wraps the
+   :pipeline:`$group` aggregation stage with a :group:`$sum` expression.
+
 Example
 -------