DOCSP-37550-count-documents (#54)

Author: jordan-smith721

source/fundamentals/crud/count.txt

@@ -12,7 +12,9 @@ Read Data from MongoDB
    :maxdepth: 1
 
    /read/retrieve
+   /read/count
    /read/cursors
 
 - :ref:`pymongo-retrieve`
-- :ref:`pymongo-cursors`
+- :ref:`pymongo-count`
+- :ref:`pymongo-cursors`

source/read.txt

@@ -0,0 +1,140 @@
+.. _pymongo-count:
+
+===============
+Count Documents
+===============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: number, amount, estimation, code example
+
+Overview
+---------
+
+In this guide, you can learn how to retrieve an accurate and estimated count of the
+number of documents in a collection.
+
+Retrieve an Accurate Count
+--------------------------
+
+Use the ``count_documents()`` method to count the number of documents that are in a
+collection. To count the number of documents that match a specific search
+critera, pass a dictionary that includes a query filter to the
+``count_documents()`` method.
+
+To learn more about specifying a query, see :ref:`pymongo-specify-query`.
+
+Count All Documents
+~~~~~~~~~~~~~~~~~~~
+
+To return a count of all documents in the collection, pass an empty dictionary to
+the ``count_documents()`` method, as shown in the following example:
+
+.. code-block:: python
+
+   collection.count_documents({})
+
+Count Specific Documents
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To return a count of documents that match specific search criteria, specify your
+query in the ``count_documents()`` method, as shown in the following example:
+
+.. code-block:: python
+   
+   collection.count_documents({ "author": "Mike" })
+
+Customize Count Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``count_documents()`` method accepts optional parameters, which represent
+options you can use to configure the count operation. If you don't specify any
+options, the driver does not customize the count operation.
+
+The following table describes the options you can set to customize ``count_documents()``:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``comment``
+     - | A comment to attach to the operation.
+
+   * - ``session``
+     - | An instance of ``ClientSession``.
+
+   * - ``skip``
+     - | The number of documents to skip before returning results.
+
+   * - ``limit``
+     - | The maximum number of documents to count. Must be a positive integer.
+
+   * - ``maxTimeMS``
+     - | The maximum amount of time to allow the operation to run, in
+         milliseconds.
+     
+   * - ``collation``
+     - | An instance of ``Collation``.
+
+   * - ``hint``
+     - | Gets or sets the index to scan for documents.
+
+Retrieve an Estimated Count
+---------------------------
+
+You can get an estimate of the number of documents in a collection by calling
+the ``estimated_document_count()`` method. The method estimates the amount of
+documents based on collection metadata, which might be faster than performing an 
+accurate count.
+
+The following example estimates the number of documents in a collection:
+
+.. code-block:: python
+   
+   collection.estimated_document_count()
+
+Customize Estimated Count Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``estimated_document_count()`` method accepts optional parameters, which
+represent options you can use to configure the count operation. If you don't
+specify any options, the driver does not customize the count operation.
+
+The following table describes the options you can set to customize ``estimated_document_count()``:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``comment``
+     - | A comment to attach to the operation.
+
+   * - ``maxTimeMS``
+     - | The maximum amount of time to allow the operation to run, in
+         milliseconds.
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `count_documents() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.count_documents>`__
+- `estimated_document_count() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.count_documents>`__
+- `Collation <{+api-root+}pymongo/collation.html#pymongo.collation.Collation>`__
+- `ClientSession <{+api-root+}pymongo/client_session.html#pymongo.client_session.ClientSession>`__