From 3694bb59e38bd1a7eb77a1e9aedb8419757efd39 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 19 Aug 2024 16:23:08 -0400 Subject: [PATCH 1/5] DOCSP-41978: Count documents --- source/includes/read/count.php | 44 ++++++ source/read.txt | 3 +- source/read/count.txt | 238 +++++++++++++++++++++++++++++++++ 3 files changed, 284 insertions(+), 1 deletion(-) create mode 100644 source/includes/read/count.php create mode 100644 source/read/count.txt diff --git a/source/includes/read/count.php b/source/includes/read/count.php new file mode 100644 index 00000000..73f4a425 --- /dev/null +++ b/source/includes/read/count.php @@ -0,0 +1,44 @@ +sample_training; +$collection = $db->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 +$options = ['limit' => 100]; +$result = $collection->countDocuments(['number_of_employees' => 50], $options); +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 +$options = ['maxTimeMS' => 1000]; +$result = $collection->estimatedDocumentCount($options); +echo "Estimated number of documents: " . $result; +// end-modify-estimate diff --git a/source/read.txt b/source/read.txt index eb974b7f..170423a9 100644 --- a/source/read.txt +++ b/source/read.txt @@ -8,4 +8,5 @@ Read Data from MongoDB :titlesonly: :maxdepth: 1 - /read/retrieve \ No newline at end of file + /read/retrieve + /read/count \ No newline at end of file diff --git a/source/read/count.txt b/source/read/count.txt new file mode 100644 index 00000000..a807c15c --- /dev/null +++ b/source/read/count.txt @@ -0,0 +1,238 @@ +.. _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 ``MongoDB\Collection::countDocuments()`` +method returns the exact number of documents that match a query filter or that exist in +a collection, and the ``MongoDB\Collection::estimatedDocumentCount()`` method 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 values to your ``db`` and ``collection`` variables: + +.. 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 +that are in a collection. To count the number of documents that match a specific search +critera, 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:: + + 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 that have a ``founded_year`` +value of ``2010``: + +.. io-code-block:: + + .. input:: /includes/read/count.php + :start-after: start-count-accurate + :end-before: end-count-accurate + :language: php + :dedent: + + .. output:: + + 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 as a parameter. The +following table describes some options you can set in the array: + +.. 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. + | **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:: + + .. input:: /includes/read/count.php + :start-after: start-modify-accurate + :end-before: end-modify-accurate + :language: php + :dedent: + + .. output:: + + 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 ``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:: + + .. input:: /includes/read/count.php + :start-after: start-count-estimate + :end-before: end-count-estimate + :language: php + :dedent: + + .. output:: + + 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 instructs the operation +to run for a maximum of ``1000`` milliseconds: + +.. io-code-block:: + + .. input:: /includes/read/count.php + :start-after: start-modify-estimate + :end-before: end-modify-estimate + :language: php + :dedent: + + .. output:: + + 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 From a49e8f63ed0b893d162190b09dbeb15167ae37f3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 19 Aug 2024 16:40:54 -0400 Subject: [PATCH 2/5] edits --- source/includes/read/count.php | 9 +++++---- source/read/count.txt | 4 ++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/source/includes/read/count.php b/source/includes/read/count.php index 73f4a425..fac27d40 100644 --- a/source/includes/read/count.php +++ b/source/includes/read/count.php @@ -25,8 +25,10 @@ // Counts a maximum of 100 documents that have a "number_of_employees" value of 50 // start-modify-accurate -$options = ['limit' => 100]; -$result = $collection->countDocuments(['number_of_employees' => 50], $options); +$result = $collection->countDocuments( + ['number_of_employees' => 50], + ['limit' => 100] +); echo "Number of companies with 50 employees: " . $result; // end-modify-accurate @@ -38,7 +40,6 @@ // Estimates the number of documents in the collection and sets a time limit on the operation // start-modify-estimate -$options = ['maxTimeMS' => 1000]; -$result = $collection->estimatedDocumentCount($options); +$result = $collection->estimatedDocumentCount(['maxTimeMS' => 1000]); echo "Estimated number of documents: " . $result; // end-modify-estimate diff --git a/source/read/count.txt b/source/read/count.txt index a807c15c..74e7d8c4 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -49,8 +49,8 @@ Retrieve an Accurate Count -------------------------- Use the ``MongoDB\Collection::countDocuments()`` 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 query filter to the ``countDocuments()`` method. +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. From 127f6dd9b9a1ea4d4732b0bb4977d9e894299a60 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 19 Aug 2024 16:44:04 -0400 Subject: [PATCH 3/5] code ex format --- source/read/count.txt | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/source/read/count.txt b/source/read/count.txt index 74e7d8c4..b7e6e93b 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -70,6 +70,7 @@ the ``countDocuments()`` method, as shown in the following example: :dedent: .. output:: + :visible: false Number of documents: 9500 @@ -83,6 +84,7 @@ The following example counts the number of documents that have a ``founded_year` value of ``2010``: .. io-code-block:: + :copyable: .. input:: /includes/read/count.php :start-after: start-count-accurate @@ -91,6 +93,7 @@ value of ``2010``: :dedent: .. output:: + :visible: false Number of companies founded in 2010: 33 @@ -141,6 +144,7 @@ documents in which the ``number_of_employees`` field has the value ``50`` and in operation to count a maximum of ``100`` results: .. io-code-block:: + :copyable: .. input:: /includes/read/count.php :start-after: start-modify-accurate @@ -149,6 +153,7 @@ operation to count a maximum of ``100`` results: :dedent: .. output:: + :visible: false Number of companies with 50 employees: 100 @@ -165,6 +170,7 @@ 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 @@ -173,6 +179,7 @@ The following example estimates the number of documents in a collection: :dedent: .. output:: + :visible: false Estimated number of documents: 9500 @@ -217,6 +224,7 @@ estimate of the number of documents in the collection and instructs the operatio to run for a maximum of ``1000`` milliseconds: .. io-code-block:: + :copyable: .. input:: /includes/read/count.php :start-after: start-modify-estimate @@ -225,7 +233,8 @@ to run for a maximum of ``1000`` milliseconds: :dedent: .. output:: - + :visible: false + Estimated number of documents: 9500 API Documentation From bf07b188935724aae5190bccb826082c28af2de5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 19 Aug 2024 16:45:25 -0400 Subject: [PATCH 4/5] link --- source/read/count.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/read/count.txt b/source/read/count.txt index b7e6e93b..e07390b5 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -136,7 +136,8 @@ following table describes some options you can set in the array: | **Type**: ``integer`` * - ``readPreference`` - - | The read preference to use for the operation. + - | 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 @@ -234,7 +235,7 @@ to run for a maximum of ``1000`` milliseconds: .. output:: :visible: false - + Estimated number of documents: 9500 API Documentation From 153dacc4553cbc9b5037d7e3be2d6b9f2dca5301 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 20 Aug 2024 11:11:59 -0400 Subject: [PATCH 5/5] RR feedback --- source/includes/read/count.php | 3 +-- source/read/count.txt | 32 ++++++++++++++++++-------------- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/source/includes/read/count.php b/source/includes/read/count.php index fac27d40..3167cb90 100644 --- a/source/includes/read/count.php +++ b/source/includes/read/count.php @@ -7,8 +7,7 @@ $client = new MongoDB\Client($uri); // start-db-coll -$db = $client->sample_training; -$collection = $db->companies; +$collection = $client->sample_training->companies; // end-db-coll // Counts all documents in the collection diff --git a/source/read/count.txt b/source/read/count.txt index e07390b5..5b825a78 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -21,10 +21,14 @@ 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 ``MongoDB\Collection::countDocuments()`` -method returns the exact number of documents that match a query filter or that exist in -a collection, and the ``MongoDB\Collection::estimatedDocumentCount()`` method returns -the estimated number of documents in a collection. +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 ~~~~~~~~~~~ @@ -32,7 +36,7 @@ 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 values to your ``db`` and ``collection`` variables: +and assign the following value to your ``collection`` variable: .. literalinclude:: /includes/read/count.php :language: php @@ -80,8 +84,8 @@ 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 that have a ``founded_year`` -value of ``2010``: +The following example counts the number of documents in which the value of the +``founded_year`` field is ``2010``: .. io-code-block:: :copyable: @@ -101,8 +105,8 @@ Customize Count Behavior ~~~~~~~~~~~~~~~~~~~~~~~~ You can modify the behavior of the ``countDocuments()`` method by -passing an array that specifies option values as a parameter. The -following table describes some options you can set in the array: +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 @@ -164,9 +168,9 @@ Retrieve an Estimated Count --------------------------- You can retrieve an estimate of the number of documents in a collection by calling -the ``estimatedDocumentCount()`` method. The method estimates the amount of -documents based on collection metadata, which might be faster than performing an -accurate count. +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: @@ -221,8 +225,8 @@ following table describes the options you can set in the array: | **Type**: ``MongoDB\Driver\Session`` The following example uses the ``estimatedDocumentCount()`` method to return an -estimate of the number of documents in the collection and instructs the operation -to run for a maximum of ``1000`` milliseconds: +estimate of the number of documents in the collection and sets a timeout of +``1000`` milliseconds on the operation: .. io-code-block:: :copyable: