================================
MongoDB\\Collection::aggregate()
================================

.. default-domain:: mongodb

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

Definition
----------

.. phpmethod:: MongoDB\\Collection::aggregate($pipeline, $options)

   Executes an :manual:`aggregation framework pipeline
   </core/aggregation-pipeline/>` operation on the collection.

   .. code-block:: php

      function aggregate(array $pipeline, array $options = []): Traversable
      
   :phpmethod:`MongoDB\\Collection::aggregate` has the following
   parameters:

   .. include:: /includes/apiargs/MongoDBCollection-method-aggregate-param.rst
   
   :phpmethod:`MongoDB\\Collection::aggregate` supports the following
   options:

   .. include:: /includes/apiargs/MongoDBCollection-method-aggregate-option.rst

.. _php-agg-method-output:

Output
------

:phpmethod:`MongoDB\\Collection::aggregate`'s return value depends on
the MongoDB server version and whether the ``useCursor`` option is
specified. If ``useCursor`` is true,
:phpmethod:`MongoDB\\Collection::aggregate` returns a
``MongoDB\Driver\Cursor`` object. If ``useCursor`` is false,
:phpmethod:`MongoDB\\Collection::aggregate` returns an
``ArrayIterator`` that wraps the ``result`` array from the command
response document.

.. note::

   BSON deserialization of inline aggregation results (i.e. not using a
   command cursor) does not yet support a ``typeMap`` option. Classes
   implementing :php:`MongoDB\\BSON\\Persistable
   <mongodb-bson-persistable>` will still be deserialized according to
   the :php:`Persistence <mongodb.persistence.deserialization>`
   specification.

.. todo: add examples

.. seealso::

   - :manual:`aggregate command reference
     </reference/command/aggregate>` in the MongoDB manual and

   - :manual:`Aggregation Pipeline </core/aggregation-pipeline>`
     documentation in the MongoDB Manual.