diff --git a/source/includes/read/count.php b/source/includes/read/count.php new file mode 100644 index 00000000..3167cb90 --- /dev/null +++ b/source/includes/read/count.php @@ -0,0 +1,44 @@ +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 diff --git a/source/read.txt b/source/read.txt index a3f245ca..be850609 100644 --- a/source/read.txt +++ b/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 \ No newline at end of file diff --git a/source/read/count.txt b/source/read/count.txt new file mode 100644 index 00000000..5b825a78 --- /dev/null +++ b/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 `. 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 ` 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 ` 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 ` in the Server manual. + | **Type**: ``MongoDB\Driver\ReadConcern`` + + * - ``readPreference`` + - | The read preference to use for the operation. To learn more, see + :manual:`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/>`__ \ No newline at end of file