/ /

Count Documents

Overview

In this guide, you can learn how to use the MongoDB 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 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:

$collection = $client->sample_training->companies;

To learn how to create a free MongoDB deployment and load the sample datasets, see the MongoDB Get Started guide.

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 Specify a 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:

$result = $collection->countDocuments([]);
echo 'Number of documents: ', $result;

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:

$result = $collection->countDocuments(['founded_year' => 2010]);
echo 'Number of companies founded in 2010: ', $result;

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:

Option	Description
`collation`	The collation to use for the operation. To learn more, see the Collation section of this page. 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 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:

$result = $collection->countDocuments(
    ['number_of_employees' => 50],
    ['limit' => 100],
);
echo 'Number of companies with 50 employees: ', $result;

Number of companies with 50 employees: 100

Collation

To specify a collation for your operation, pass an $options array parameter that sets the collation option to the operation method. Assign the collation option to an array that configures the collation rules.

The following table describes the fields you can set to configure the collation:

Field	Description
`locale`	(Required) Specifies the International Components for Unicode (ICU) locale. For a list of supported locales, see Collation Locales and Default Parameters in the MongoDB Server manual. Data Type: `string`
`caseLevel`	(Optional) Specifies whether to include case comparison. When set to `true`, the comparison behavior depends on the value of the `strength` field: - If `strength` is `1`, the PHP library compares base characters and case. - If `strength` is `2`, the PHP library compares base characters, diacritics, other secondary differences, and case. - If `strength` is any other value, this field is ignored. When set to `false`, the PHP library doesn't include case comparison at strength level `1` or `2`. Data Type: `bool` Default: `false`
`caseFirst`	(Optional) Specifies the sort order of case differences during tertiary level comparisons. Data Type: `string` Default: `"off"`
`strength`	(Optional) Specifies the level of comparison to perform, as defined in the ICU documentation. Data Type: `int` Default: `3`
`numericOrdering`	(Optional) Specifies whether the driver compares numeric strings as numbers. If set to `true`, the PHP library compares numeric strings as numbers. For example, when comparing the strings "10" and "2", the library uses the strings' numeric values and treats "10" as greater than "2". If set to `false`, the PHP library compares numeric strings as strings. For example, when comparing the strings "10" and "2", the library compares one character at a time and treats "10" as less than "2". For more information, see Collation Restrictions in the MongoDB Server manual. Data Type: `bool` Default: `false`
`alternate`	(Optional) Specifies whether the library considers whitespace and punctuation as base characters for comparison purposes. Data Type: `string` Default: `"non-ignorable"`
`maxVariable`	(Optional) Specifies which characters the library considers ignorable when the `alternate` field is set to `"shifted"`. Data Type: `string` Default: `"punct"`
`backwards`	(Optional) Specifies whether strings containing diacritics sort from the back of the string to the front. Data Type: `bool` Default: `false`

To learn more about collation and the possible values for each field, see the Collation entry in the MongoDB Server manual.

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:

$result = $collection->estimatedDocumentCount();
echo 'Estimated number of documents: ', $result;

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:

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 Read Concern in the Server manual. Type: `MongoDB\Driver\ReadConcern`
`readPreference`	The read preference to use for the operation. To learn more, see 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:

$result = $collection->estimatedDocumentCount(['maxTimeMS' => 1000]);
echo 'Estimated number of documents: ', $result;

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:

Back

Specify a Query

Distinct Field Values