diff --git a/source/aggregation.txt b/source/aggregation.txt index 2088b42a5f5..ab352d80cbc 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -10,39 +10,41 @@ Aggregation :depth: 1 :class: singlecol -Aggregation operations process data records and return computed -results. Aggregation operations group values from multiple documents -together, and can perform a variety of operations on the grouped data -to return a single result. MongoDB provides three ways to perform -aggregation: the :ref:`aggregation pipeline -`, the :ref:`map-reduce function -`, and :ref:`single purpose aggregation methods -`. +Aggregation operations process multiple documents and return computed +results. You can use aggregation operations to: + +- Group values from multiple documents together. + +- Perform operations on the grouped data to return a single result. + +- Analyze data changes over time. + +To perform aggregation operations, you can use: + +- :ref:`Aggregation pipelines ` + +- :ref:`Single purpose aggregation methods + ` + +- :ref:`Map-reduce functions ` .. _aggregation-framework: -Aggregation Pipeline --------------------- +Aggregation Pipelines +--------------------- -MongoDB's :doc:`aggregation framework -` is modeled on the concept of data -processing pipelines. Documents enter a multi-stage pipeline that -transforms the documents into an aggregated result. For example: +.. include:: /includes/aggregation-pipeline-introduction.rst -.. code-block:: javascript +Aggregation Pipeline Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - db.orders.aggregate([ - { $match: { status: "A" } }, - { $group: { _id: "$cust_id", total: { $sum: "$amount" } } } - ]) +.. include:: /includes/aggregation-pipeline-example.rst -**First Stage**: The :pipeline:`$match` stage filters the documents by -the ``status`` field and passes to the next stage those documents that -have ``status`` equal to ``"A"``. +For a runnable example, see :ref:`Complete Aggregation Pipeline +Example `. -**Second Stage**: The :pipeline:`$group` stage groups the documents by -the ``cust_id`` field to calculate the sum of the amount for each -unique ``cust_id``. +Aggregation Pipeline Stages and Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The most basic pipeline stages provide *filters* that operate like queries and *document transformations* that modify the form diff --git a/source/core/aggregation-pipeline.txt b/source/core/aggregation-pipeline.txt index 8e75bf415f7..e9a3baafa52 100644 --- a/source/core/aggregation-pipeline.txt +++ b/source/core/aggregation-pipeline.txt @@ -1,4 +1,4 @@ -.. _aggregation-top-level-server: +.. _aggregation-pipeline: ==================== Aggregation Pipeline @@ -12,65 +12,88 @@ Aggregation Pipeline :depth: 1 :class: singlecol -The aggregation pipeline is a framework for data aggregation modeled -on the concept of data processing pipelines. Documents enter a -multi-stage pipeline that transforms the documents into aggregated -results. For example: +.. include:: /includes/aggregation-pipeline-introduction.rst + +.. _aggregation-pipeline-example: + +Complete Aggregation Pipeline Example +------------------------------------- + +Create the following collection that contains orders for products: .. code-block:: javascript - db.orders.aggregate([ - { $match: { status: "A" } }, - { $group: { _id: "$cust_id", total: { $sum: "$amount" } } } - ]) + db.orders.insertMany( [ + { _id: 0, productName: "Steel beam", status: "new", quantity: 10 }, + { _id: 1, productName: "Steel beam", status: "urgent", quantity: 20 }, + { _id: 2, productName: "Steel beam", status: "urgent", quantity: 30 }, + { _id: 3, productName: "Iron rod", status: "new", quantity: 15 }, + { _id: 4, productName: "Iron rod", status: "urgent", quantity: 50 }, + { _id: 5, productName: "Iron rod", status: "urgent", quantity: 10 } + ] ) -**First Stage**: The :pipeline:`$match` stage filters the documents by -the ``status`` field and passes to the next stage those documents that -have ``status`` equal to ``"A"``. +.. include:: /includes/aggregation-pipeline-example.rst -**Second Stage**: The :pipeline:`$group` stage groups the documents by -the ``cust_id`` field to calculate the sum of the amount for each -unique ``cust_id``. +Example output: -.. _aggregation-pipeline: +.. code-block:: javascript + :copyable: false -Pipeline --------- + [ + { _id: 'Steel beam', sumQuantity: 50 }, + { _id: 'Iron rod', sumQuantity: 60 } + ] -The MongoDB aggregation pipeline consists of :ref:`stages -`. Each stage transforms the -documents as they pass through the pipeline. Pipeline stages do not need -to produce one output document for every input document. For example, -some stages may generate new documents or filter out documents. +.. seealso:: -Pipeline stages can appear multiple times in the pipeline with the -exception of :pipeline:`$out`, :pipeline:`$merge`, and -:pipeline:`$geoNear` stages. For a list -of all available stages, see -:ref:`aggregation-pipeline-operator-reference`. + - :doc:`/tutorial/aggregation-with-user-preference-data` + - :doc:`/tutorial/aggregation-zip-code-data-set` + - :doc:`/tutorial/update-documents-with-aggregation-pipeline` -MongoDB provides the :method:`db.collection.aggregate()` shell method -and the :dbcommand:`aggregate` command to run the aggregation pipeline. +.. _aggregation-pipeline-stages: -For example usage of the aggregation pipeline, consider -:doc:`/tutorial/aggregation-with-user-preference-data` and -:doc:`/tutorial/aggregation-zip-code-data-set`. +Aggregation Pipeline Stages +--------------------------- -Starting in MongoDB 4.2, you can use the aggregation pipeline for -updates in: +An aggregation pipeline consists of one or more :ref:`stages +` that process documents: + +- Each stage transforms the documents as they pass through the pipeline. -.. include:: /includes/table-update-with-aggregation-availability.rst +- A stage does not have to output one document for every input + document. For example, some stages may produce new documents or + filter out documents. -.. seealso:: +- The same stage can appear multiple times in the pipeline with these + stage exceptions: :pipeline:`$out`, :pipeline:`$merge`, and + :pipeline:`$geoNear`. + +- For all available stages, see + :ref:`aggregation-pipeline-operator-reference`. + +Run an Aggregation Pipeline +--------------------------- + +To run an aggregation pipeline, use: - :doc:`/tutorial/update-documents-with-aggregation-pipeline` +- :method:`db.collection.aggregate()` or -.. _aggregation-pipeline-expressions: +- :dbcommand:`aggregate` + +Update Documents Using an Aggregation Pipeline +---------------------------------------------- + +Starting in MongoDB 4.2, you can use the aggregation pipeline to update +documents using these methods: + +.. include:: /includes/table-update-with-aggregation-availability.rst + .. _aggregation-pipeline-expressions: + Pipeline Expressions -------------------- -Some pipeline stages take a pipeline expression as the operand. +Some pipeline stages accept a pipeline expression as the operand. Pipeline expressions specify the transformation to apply to the input documents. Expressions have a :doc:`document ` structure and can contain other :ref:`expression diff --git a/source/includes/aggregation-pipeline-example.rst b/source/includes/aggregation-pipeline-example.rst new file mode 100644 index 00000000000..d27da46338d --- /dev/null +++ b/source/includes/aggregation-pipeline-example.rst @@ -0,0 +1,24 @@ +The following aggregation pipeline example contains two :ref:`stages +` and returns the total +quantity of urgent orders for each product: + +.. code-block:: javascript + + db.orders.aggregate( [ + { $match: { status: "urgent" } }, + { $group: { _id: "$productName", sumQuantity: { $sum: "$quantity" } } } + ] ) + +The :pipeline:`$match` stage: + +- Filters the documents to those with a ``status`` of ``urgent``. + +- Outputs the filtered documents to the :pipeline:`$group` stage. + +The :pipeline:`$group` stage: + +- Groups the input documents by ``productName``. + +- Uses :group:`$sum` to calculate the total ``quantity`` for each + ``productName``, which is stored in the ``sumQuantity`` field returned + by the aggregation pipeline. \ No newline at end of file diff --git a/source/includes/aggregation-pipeline-introduction.rst b/source/includes/aggregation-pipeline-introduction.rst new file mode 100644 index 00000000000..341e0c73e87 --- /dev/null +++ b/source/includes/aggregation-pipeline-introduction.rst @@ -0,0 +1,12 @@ +An aggregation pipeline consists of one or more :ref:`stages +` that process documents: + +- Each stage performs an operation on the input documents. + For example, a stage can filter documents, group documents, and + calculate values. + +- The documents that are output from one stage are input to the next + stage. + +- An aggregation pipeline can return results for groups of documents. + For example, return the total, average, maximum, and minimum values. \ No newline at end of file diff --git a/source/includes/table-update-with-aggregation-availability.rst b/source/includes/table-update-with-aggregation-availability.rst index 50499322efc..93a36cdeeef 100644 --- a/source/includes/table-update-with-aggregation-availability.rst +++ b/source/includes/table-update-with-aggregation-availability.rst @@ -13,7 +13,6 @@ - | :ref:`db.collection.updateOne() ` | :ref:`db.collection.updateMany() ` - | :ref:`db.collection.update() ` | :ref:`Bulk.find.update() ` | :ref:`Bulk.find.updateOne() `