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

.. versionadded:: 1.5

.. default-domain:: mongodb

.. 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
       - Specifies the batch size for the cursor, which will apply to both the
         initial ``aggregate`` command and any subsequent ``getMore`` commands.
         This determines the maximum number of documents to return in each
         response from the server.

         A batchSize of ``0`` is special in that and will only apply to the
         initial ``aggregate`` command; subsequent ``getMore`` commands will use
         the server's default batch size. 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
