aggregation.txt

.. _node-aggregation:
.. _nodejs-aggregation:

===========
Aggregation
===========

.. meta::
   :description: Learn to use aggregation operations in the MongoDB Node.js driver to create pipelines for data transformation and summarization.

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

.. _nodejs-aggregation-overview:

Overview
--------

In this guide, you can learn how to use **aggregation operations** in
the MongoDB Node.js driver.

Aggregation operations are expressions you can use to produce reduced
and summarized results in MongoDB. MongoDB's aggregation framework
allows you to create a pipeline that consists of one or more stages,
each of which performs a specific operation on your data.

Analogy
~~~~~~~

You can think of the aggregation pipeline as similar to an automobile factory.
Automobile manufacturing requires the use of assembly stations organized
into assembly lines. Each station has specialized tools, such as
drills and welders. The factory transforms and
assembles the initial parts and materials into finished products.

The **aggregation pipeline** is the assembly line, **aggregation
stages** are the assembly stations, and **expression operators** are the
specialized tools.

Comparing Aggregation and Query Operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using query operations, such as the ``find()`` method, you can perform the following actions:

- Select *which documents* to return
- Select *which fields* to return
- Sort the results

Using aggregation operations, you can perform the following actions:

- Perform all query operations
- Rename fields
- Calculate fields
- Summarize data
- Group values

Aggregation operations have some :manual:`limitations </core/aggregation-pipeline-limits/>`:

- Returned documents must not violate the :manual:`BSON-document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
  of 16 megabytes.

- Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
  limit by setting the ``allowDiskUse`` property of ``AggregateOptions`` to ``true``. See
  the `AggregateOptions API documentation <{+api+}/interfaces/AggregateOptions.html>`__
  for more details.

.. important:: $graphLookup exception

   The :manual:`$graphLookup
   </reference/operator/aggregation/graphLookup/>` stage has a strict
   memory limit of 100 megabytes and will ignore ``allowDiskUse``.

References
~~~~~~~~~~

To view a full list of expression operators, see :manual:`Aggregation
Operators </reference/operator/aggregation/>` in the Server manual.

To learn about assembling an aggregation pipeline and view examples, see
:manual:`Aggregation Pipeline </core/aggregation-pipeline/>` in the
Server manual.

To learn more about creating pipeline stages, see :manual:`Aggregation
Stages </reference/operator/aggregation-pipeline/>` in the Server manual.

Runnable Examples
-----------------

The example uses sample data about restaurants. The following code
inserts data into the ``restaurants`` collection of the ``aggregation``
database:

.. literalinclude:: /code-snippets/aggregation/agg.js
   :start-after: begin data insertion
   :end-before: end data insertion
   :language: javascript
   :dedent:

.. tip::

   For more information on connecting to your MongoDB deployment, see the :doc:`Connection Guide </fundamentals/connection>`.

Aggregation Example
~~~~~~~~~~~~~~~~~~~

To perform an aggregation, pass a list of aggregation stages to the
``collection.aggregate()`` method.

In the example, the aggregation pipeline uses the following aggregation stages:

- A :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents whose
  ``categories`` array field contains the element ``Bakery``.

- A :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching documents by the ``stars``
  field, accumulating a count of documents for each distinct value of ``stars``.

.. literalinclude:: /code-snippets/aggregation/agg.js
   :start-after: begin aggregation
   :end-before: end aggregation
   :language: javascript
   :dedent:

This example produces the following output:

.. code-block:: json
   :copyable: false

   { _id: 4, count: 2 }
   { _id: 3, count: 1 }
   { _id: 5, count: 1 }

For more information, see the `aggregate() API documentation <{+api+}/classes/Collection.html#aggregate>`__.

Additional Examples
~~~~~~~~~~~~~~~~~~~

To view step-by-step explanations of common aggregation tasks, see the
:ref:`node-aggregation-tutorials-landing`.

You can find another aggregation pipeline example in the `Aggregation
Framework with Node.js Tutorial
<https://www.mongodb.com/blog/post/quick-start-nodejs--mongodb--how-to-analyze-data-using-the-aggregation-framework>`_
blog post on the MongoDB website.