MongoDBCollection-countDocuments.txt

=====================================
MongoDB\\Collection::countDocuments()
=====================================

.. meta::
   :description: Count documents in a collection matching a filter criteria with the MongoDB PHP Library, with various options for customization.

.. versionadded:: 1.4


.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. phpmethod:: MongoDB\Collection::countDocuments()

   Count the number of documents that match the filter criteria.

   .. code-block:: php

      function countDocuments(array|object $filter = [], array $options = []): integer

Parameters
----------

``$filter`` : array|object
  The filter criteria that specifies the documents to count.

``$options`` : array
  An array specifying the desired options.

  .. list-table::
     :header-rows: 1
     :widths: 20 20 80

     * - Name
       - Type
       - Description

     * - collation
       - array|object
       - .. include:: /includes/extracts/collection-option-collation.rst

     * - comment
       - mixed
       - .. include:: /includes/extracts/common-option-comment.rst

         .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst

     * - hint
       - string|array|object
       - .. include:: /includes/extracts/common-option-hint.rst

     * - limit
       - integer
       - The maximum number of matching documents to return.

     * - maxTimeMS
       - integer
       - .. include:: /includes/extracts/common-option-maxTimeMS.rst

     * - readConcern
       - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
       - .. include:: /includes/extracts/collection-option-readConcern.rst

         .. include:: /includes/extracts/common-option-readConcern-transaction.rst

     * - readPreference
       - :php:`MongoDB\Driver\ReadPreference <class.mongodb-driver-readpreference>`
       - .. include:: /includes/extracts/collection-option-readPreference.rst

     * - session
       - :php:`MongoDB\Driver\Session <class.mongodb-driver-session>`
       - .. include:: /includes/extracts/common-option-session.rst

     * - skip
       - integer
       - The number of matching documents to skip before returning results.

Return Values
-------------

The number of documents matching the filter criteria.

Errors/Exceptions
-----------------

.. include:: /includes/extracts/error-unexpectedvalueexception.rst
.. include:: /includes/extracts/error-unsupportedexception.rst
.. include:: /includes/extracts/error-invalidargumentexception.rst
.. include:: /includes/extracts/error-driver-runtimeexception.rst

Behavior
--------

Internally, this method uses the ``$group`` aggregation pipeline operator to
obtain the result. If a ``filter`` parameter is given, this is converted into
a ``$match`` pipeline operator. Optional ``$skip`` and ``$limit`` stages are
added between ``$match`` and ``group`` if present in the options.

.. note::

   This method counts documents on the server side. To obtain an approximate
   total number of documents without filters, the
   :phpmethod:`MongoDB\Collection::estimatedDocumentCount()` method can be
   used. This method estimates the number of documents based on collection
   metadata, thus sacrificing accuracy for performance.

Since this method uses an aggregation pipeline, some query operators accepted
within a :phpmethod:`MongoDB\Collection::count()` ``filter`` cannot be used.
Consider the following alternatives to these restricted operators:

.. list-table::
   :header-rows: 1

   * - Restricted
     - Alternative Syntax

   * - :query:`$near`
     - :query:`$geoWithin` with :query:`$center`

   * - :query:`$nearSphere`
     - :query:`$geoWithin` with :query:`$centerSphere`

   * - :query:`$where`
     - :query:`$expr`

.. include:: /includes/extracts/note-bson-comparison.rst

.. todo: add output and examples

See Also
--------

- :phpmethod:`MongoDB\Collection::estimatedDocumentCount()`