DOCSP-41978: Count documents

source/includes/read/count.php

@@ -0,0 +1,44 @@
+<?php
+require 'vendor/autoload.php';
+
+use MongoDB\BSON\Document;
+
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
+$client = new MongoDB\Client($uri);
+
+// start-db-coll
+$collection = $client->sample_training->companies;
+// end-db-coll
+
+// Counts all documents in the collection
+// start-count-all
+$result = $collection->countDocuments([]);
+echo "Number of documents: " . $result;
+// end-count-all
+
+// Counts documents that have a "founded_year" value of 2010
+// start-count-accurate
+$result = $collection->countDocuments(['founded_year' => 2010]);
+echo "Number of companies founded in 2010: " . $result;
+// end-count-accurate
+
+// Counts a maximum of 100 documents that have a "number_of_employees" value of 50
+// start-modify-accurate
+$result = $collection->countDocuments(
+    ['number_of_employees' => 50],
+    ['limit' => 100]
+);
+echo "Number of companies with 50 employees: " . $result;
+// end-modify-accurate
+
+// Estimates the number of documents in the collection
+// start-count-estimate
+$result = $collection->estimatedDocumentCount();
+echo "Estimated number of documents: " . $result;
+// end-count-estimate
+
+// Estimates the number of documents in the collection and sets a time limit on the operation
+// start-modify-estimate
+$result = $collection->estimatedDocumentCount(['maxTimeMS' => 1000]);
+echo "Estimated number of documents: " . $result;
+// end-modify-estimate

source/read.txt

@@ -9,6 +9,7 @@ Read Data from MongoDB
    :maxdepth: 1
 
    /read/retrieve
+   /read/project
+   /read/count
    /read/specify-documents-to-return
    /read/specify-a-query
-   /read/project

source/read/count.txt

@@ -0,0 +1,252 @@
+.. _php-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 use the {+php-library+} to retrieve an accurate
+and estimated count of the number of documents in a collection. The following methods
+count documents in a collection:
+
+- ``MongoDB\Collection::countDocuments()``: Returns the exact number of documents that
+   match a query filter or that exist in a collection
+
+- ``MongoDB\Collection::estimatedDocumentCount()``: Returns the estimated number of documents
+  in a collection
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``companies`` collection in the ``sample_training``
+database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
+from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
+and assign the following value to your ``collection`` variable:
+
+.. literalinclude:: /includes/read/count.php
+    :language: php
+    :dedent:
+    :start-after: start-db-coll
+    :end-before: end-db-coll
+
+To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` guide.
+
+.. _php-accurate-count:
+
+Retrieve an Accurate Count
+--------------------------
+
+Use the ``MongoDB\Collection::countDocuments()`` method to count the number of documents
+in a collection. To count the number of documents that match specific search criteria,
+pass a query filter to the ``countDocuments()`` method.
+
+To learn more about specifying a query, see the :ref:`php-specify-query` guide.
+
+Count All Documents
+~~~~~~~~~~~~~~~~~~~
+
+To return a count of all documents in the collection, pass an empty query filter array to
+the ``countDocuments()`` method, as shown in the following example:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.php
+      :start-after: start-count-all
+      :end-before: end-count-all
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Number of documents: 9500
+
+Count Specific Documents
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To return a count of documents that match specific search criteria, pass a query
+filter to the ``countDocuments()`` method.
+
+The following example counts the number of documents in which the value of the
+``founded_year`` field is ``2010``:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.php
+      :start-after: start-count-accurate
+      :end-before: end-count-accurate
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Number of companies founded in 2010: 33
+
+Customize Count Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can modify the behavior of the ``countDocuments()`` method by
+passing an array that specifies option values. The following table
+describes some options you can set to customize the count operation:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+
+   * - ``collation``
+     - | The collation to use for the operation.
+       | **Type**: ``array|object``
+
+   * - ``hint``
+     - | The index to use for the operation.
+       | **Type**: ``string|array|object``
+
+   * - ``comment``
+     - | The comment to attach to the operation.
+       | **Type**: any valid BSON type
+
+   * - ``limit``
+     - | The maximum number of documents to count. This value must be a positive integer.
+       | **Type**: ``integer``
+
+   * - ``maxTimeMS``
+     - | The maximum amount of time in milliseconds that the operation can run.
+       | **Type**: ``integer``
+
+   * - ``skip``
+     - | The number of documents to skip before counting documents.
+       | **Type**: ``integer``
+
+   * - ``readPreference``
+     - | The read preference to use for the operation. To learn more, see
+         :manual:`Read Preference </core/read-preference/>` in the Server manual.
+       | **Type**: ``MongoDB\Driver\ReadPreference``
+
+The following example uses the ``countDocuments()`` method to count the number of
+documents in which the ``number_of_employees`` field has the value ``50`` and instructs the
+operation to count a maximum of ``100`` results:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.php
+      :start-after: start-modify-accurate
+      :end-before: end-modify-accurate
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Number of companies with 50 employees: 100
+
+.. _php-estimated-count:
+
+Retrieve an Estimated Count
+---------------------------
+
+You can retrieve an estimate of the number of documents in a collection by calling
+the ``MongoDB\Collection::estimatedDocumentCount()`` 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:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.php
+      :start-after: start-count-estimate
+      :end-before: end-count-estimate
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Estimated number of documents: 9500
+
+Customize Estimated Count Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can modify the behavior of the ``estimatedDocumentCount()`` method
+by passing an array that specifies option values as a parameter. The
+following table describes the options you can set in the array:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+
+   * - ``comment``
+     - | The comment to attach to the operation.
+       | **Type**: any valid BSON type
+
+   * - ``maxTimeMS``
+     - | The maximum amount of time in milliseconds that the operation can run.
+       | **Type**: ``integer``
+
+   * - ``readConcern``
+     - | The read concern to use for the operation. To learn more, see
+         :manual:`Read Concern </reference/read-concern/>` in the Server manual.
+       | **Type**: ``MongoDB\Driver\ReadConcern``
+
+   * - ``readPreference``
+     - | The read preference to use for the operation. To learn more, see
+         :manual:`Read Preference </core/read-preference/>` in the Server manual.
+       | **Type**: ``MongoDB\Driver\ReadPreference``
+
+   * - ``session``
+     - | The client session to associate with the operation.
+       | **Type**: ``MongoDB\Driver\Session``
+
+The following example uses the ``estimatedDocumentCount()`` method to return an
+estimate of the number of documents in the collection and sets a timeout of
+``1000`` milliseconds on the operation:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.php
+      :start-after: start-modify-estimate
+      :end-before: end-modify-estimate
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Estimated number of documents: 9500
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `MongoDB\\Collection::countDocuments() <{+api+}/method/MongoDBCollection-countDocuments/>`__
+- `MongoDB\\Collection::estimatedDocumentCount() <{+api+}/method/MongoDBCollection-estimatedDocumentCount/>`__