MongoDBDatabase-aggregate.txt

==============================
MongoDB\\Database::aggregate()
==============================

.. versionadded:: 1.5


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

Definition
----------

.. phpmethod:: MongoDB\Database::aggregate()

   Runs a specified :manual:`admin/diagnostic pipeline
   </reference/operator/aggregation-pipeline/#db-aggregate-stages>` which does
   not require an underlying collection. For aggregations on collection data,
   see :phpmethod:`MongoDB\Collection::aggregate()`.

   .. code-block:: php

      function aggregate(
          array $pipeline,
          array $options = []
      ): Traversable

Parameters
----------

``$pipeline`` : array
  Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>`
  operation.

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

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

     * - Name
       - Type
       - Description

     * - allowDiskUse
       - boolean
       - Enables writing to temporary files. When set to ``true``, aggregation
         stages can write data to the ``_tmp`` sub-directory in the ``dbPath``
         directory.

     * - batchSize
       - integer
       - The maximum number of documents within each batch returned in a query result.
         By default, the ``aggregate`` command has an initial batch size of 
         ``101`` documents and a maximum size of 16 mebibytes (MiB) for each subsequent batch. This
         option can enforce a smaller limit than 16 MiB, but not a larger
         one. If you set ``batchSize`` to a limit that results in batches larger than
         16 MiB, this option has no effect.

         A batchSize of ``0`` means that the cursor will be established, but no documents 
         will be returned in the first batch. This may be useful for quickly returning a cursor
         or failure from ``aggregate`` without doing significant server-side work.

     * - bypassDocumentValidation
       - boolean
       - If ``true``, allows the write operation to circumvent document level
         validation. Defaults to ``false``.

         This only applies when using the :ref:`$out <agg-out>` and
         :ref:`$out <agg-merge>` stages.

     * - codec
       - MongoDB\\Codec\\DocumentCodec
       - .. include:: /includes/extracts/common-option-codec.rst

         .. versionadded:: 1.17

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

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

         The comment can be any valid BSON type for server versions 4.4 and
         above. Earlier server versions only support string values.

     * - explain
       - boolean
       - Specifies whether or not to return the information on the processing of
         the pipeline.

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

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

         .. versionadded:: 1.9

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

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

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

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

     * - typeMap
       - array
       - .. include:: /includes/extracts/database-option-typeMap.rst

     * - writeConcern
       - :php:`MongoDB\Driver\WriteConcern <class.mongodb-driver-writeconcern>`
       - .. include:: /includes/extracts/database-option-writeConcern.rst

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

A :php:`MongoDB\Driver\Cursor <class.mongodb-driver-cursor>` or
:php:`ArrayIterator <arrayiterator>` object. In both cases, the return value
will be :php:`Traversable <traversable>`.

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

.. _php-db-agg-method-behavior:

Examples
--------

The following aggregation example lists all running commands using the
``$currentOp`` aggregation pipeline stage, then filters this list to only show
running command operations.

.. code-block:: php

   <?php

   $database = (new MongoDB\Client)->admin;

   $cursor = $database->aggregate(
       [
           ['$currentOp' => []],
           ['$match' => ['op' => 'command']],
       ]
   );

See Also
--------

- :phpmethod:`MongoDB\Collection::aggregate()`
- :manual:`aggregate </reference/command/aggregate>` command reference in the
  MongoDB manual
- :manual:`Aggregation Pipeline </core/aggregation-pipeline>` documentation in
  the MongoDB Manual