|
| 1 | +.. _cpp-aggregation: |
| 2 | + |
| 3 | +==================================== |
| 4 | +Transform Your Data with Aggregation |
| 5 | +==================================== |
| 6 | + |
| 7 | +.. facet:: |
| 8 | + :name: genre |
| 9 | + :values: reference |
| 10 | + |
| 11 | +.. meta:: |
| 12 | + :keywords: code example, transform, computed, pipeline |
| 13 | + :description: Learn how to use the C++ driver to perform aggregation operations. |
| 14 | + |
| 15 | +.. contents:: On this page |
| 16 | + :local: |
| 17 | + :backlinks: none |
| 18 | + :depth: 2 |
| 19 | + :class: singlecol |
| 20 | + |
| 21 | +.. TODO: |
| 22 | + .. toctree:: |
| 23 | + :titlesonly: |
| 24 | + :maxdepth: 1 |
| 25 | + |
| 26 | + /aggregation/aggregation-tutorials |
| 27 | + |
| 28 | +Overview |
| 29 | +-------- |
| 30 | + |
| 31 | +In this guide, you can learn how to use the {+driver-short+} to perform |
| 32 | +**aggregation operations**. |
| 33 | + |
| 34 | +Aggregation operations process data in your MongoDB collections and |
| 35 | +return computed results. The MongoDB Aggregation framework, which is |
| 36 | +part of the Query API, is modeled on the concept of data processing |
| 37 | +pipelines. Documents enter a pipeline that contains one or more stages, |
| 38 | +and this pipeline transforms the documents into an aggregated result. |
| 39 | + |
| 40 | +An aggregation operation is similar to a car factory. A car factory has |
| 41 | +an assembly line, which contains assembly stations with specialized |
| 42 | +tools to do specific jobs, like drills and welders. Raw parts enter the |
| 43 | +factory, and then the assembly line transforms and assembles them into a |
| 44 | +finished product. |
| 45 | + |
| 46 | +The **aggregation pipeline** is the assembly line, **aggregation stages** are the |
| 47 | +assembly stations, and **operator expressions** are the |
| 48 | +specialized tools. |
| 49 | + |
| 50 | +Aggregation Versus Find Operations |
| 51 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 52 | + |
| 53 | +You can use find operations to perform the following actions: |
| 54 | + |
| 55 | +- Select which documents to return |
| 56 | +- Select which fields to return |
| 57 | +- Sort the results |
| 58 | + |
| 59 | +You can use aggregation operations to perform the following actions: |
| 60 | + |
| 61 | +- Run find operations |
| 62 | +- Rename fields |
| 63 | +- Calculate fields |
| 64 | +- Summarize data |
| 65 | +- Group values |
| 66 | + |
| 67 | +Limitations |
| 68 | +~~~~~~~~~~~ |
| 69 | + |
| 70 | +Keep the following limitations in mind when using aggregation operations: |
| 71 | + |
| 72 | +- Returned documents cannot violate the |
| 73 | + :manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>` |
| 74 | + of 16 megabytes. |
| 75 | +- Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this |
| 76 | + limit by setting the ``allow_disk_use`` field of a ``mongocxx::options::aggregate`` |
| 77 | + instance to ``true``. |
| 78 | + |
| 79 | +.. important:: $graphLookup Exception |
| 80 | + |
| 81 | + The :manual:`$graphLookup |
| 82 | + </reference/operator/aggregation/graphLookup/>` stage has a strict |
| 83 | + memory limit of 100 megabytes and ignores the ``allow_disk_use`` field. |
| 84 | + |
| 85 | +.. _cpp-aggregation-example: |
| 86 | + |
| 87 | +Aggregation Example |
| 88 | +------------------- |
| 89 | + |
| 90 | +.. note:: |
| 91 | + |
| 92 | + The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` |
| 93 | + database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a |
| 94 | + free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas |
| 95 | + </getting-started>` guide. |
| 96 | + |
| 97 | +To perform an aggregation, pass a ``mongocxx::pipeline`` instance containing the aggregation |
| 98 | +stages to the ``collection.aggregate()`` method. |
| 99 | + |
| 100 | +The following code example produces a count of the number of bakeries in each borough |
| 101 | +of New York. To do so, it uses an aggregation pipeline that contains the following stages: |
| 102 | + |
| 103 | +- :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents |
| 104 | + in which the ``cuisine`` field contains the value ``"Bakery"`` |
| 105 | + |
| 106 | +- :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching |
| 107 | + documents by the ``borough`` field, accumulating a count of documents for each distinct |
| 108 | + value |
| 109 | + |
| 110 | +.. io-code-block:: |
| 111 | + |
| 112 | + .. input:: /includes/aggregation.cpp |
| 113 | + :start-after: start-match-group |
| 114 | + :end-before: end-match-group |
| 115 | + :language: cpp |
| 116 | + :dedent: |
| 117 | + |
| 118 | + .. output:: |
| 119 | + |
| 120 | + { "_id" : "Brooklyn", "count" : 173 } |
| 121 | + { "_id" : "Queens", "count" : 204 } |
| 122 | + { "_id" : "Bronx", "count" : 71 } |
| 123 | + { "_id" : "Staten Island", "count" : 20 } |
| 124 | + { "_id" : "Missing", "count" : 2 } |
| 125 | + { "_id" : "Manhattan", "count" : 221 } |
| 126 | + |
| 127 | +Explain an Aggregation |
| 128 | +~~~~~~~~~~~~~~~~~~~~~~ |
| 129 | + |
| 130 | +To view information about how MongoDB executes your operation, you can |
| 131 | +instruct the MongoDB query planner to **explain** it. When MongoDB explains |
| 132 | +an operation, it returns **execution plans** and performance statistics. |
| 133 | +An execution plan is a potential way MongoDB can complete an operation. |
| 134 | +When you instruct MongoDB to explain an operation, it returns both the |
| 135 | +plan MongoDB executed and any rejected execution plans. |
| 136 | + |
| 137 | +To explain an aggregation operation, run the ``explain`` database command by specifying |
| 138 | +the command in a BSON document and passing it as an argument to the ``run_command()`` |
| 139 | +method. |
| 140 | + |
| 141 | +The following example instructs MongoDB to explain the aggregation operation from the |
| 142 | +preceding :ref:`cpp-aggregation-example`: |
| 143 | + |
| 144 | +.. io-code-block:: |
| 145 | + |
| 146 | + .. input:: /includes/aggregation.cpp |
| 147 | + :start-after: start-explain |
| 148 | + :end-before: end-explain |
| 149 | + :language: cpp |
| 150 | + :dedent: |
| 151 | + |
| 152 | + .. output:: |
| 153 | + |
| 154 | + { "explainVersion" : "2", "queryPlanner" : { "namespace" : "sample_restaurants.restaurants", |
| 155 | + "indexFilterSet" : false, "parsedQuery" : { "cuisine" : { "$eq" : "Bakery" } }, "queryHash": |
| 156 | + "...", "planCacheKey" : "...", "optimizedPipeline" : true, "maxIndexedOrSolutionsReached": |
| 157 | + false, "maxIndexedAndSolutionsReached" : false, "maxScansToExplodeReached" : false, |
| 158 | + "winningPlan" : { ... } |
| 159 | + ... } |
| 160 | + |
| 161 | + |
| 162 | +Additional Information |
| 163 | +---------------------- |
| 164 | + |
| 165 | +MongoDB Server Manual |
| 166 | +~~~~~~~~~~~~~~~~~~~~~ |
| 167 | + |
| 168 | +To view a full list of expression operators, see :manual:`Aggregation |
| 169 | +Operators. </reference/operator/aggregation/>` |
| 170 | + |
| 171 | +To learn about assembling an aggregation pipeline and view examples, see |
| 172 | +:manual:`Aggregation Pipeline. </core/aggregation-pipeline/>` |
| 173 | + |
| 174 | +To learn more about creating pipeline stages, see :manual:`Aggregation |
| 175 | +Stages. </reference/operator/aggregation-pipeline/>` |
| 176 | + |
| 177 | +To learn more about explaining MongoDB operations, see |
| 178 | +:manual:`Explain Output </reference/explain-results/>` and |
| 179 | +:manual:`Query Plans. </core/query-plans/>` |
| 180 | + |
| 181 | +.. TODO: |
| 182 | + Aggregation Tutorials |
| 183 | + ~~~~~~~~~~~~~~~~~~~~~ |
| 184 | + |
| 185 | +.. To view step-by-step explanations of common aggregation tasks, see |
| 186 | +.. :ref:`cpp-aggregation-tutorials-landing`. |
| 187 | + |
| 188 | +API Documentation |
| 189 | +~~~~~~~~~~~~~~~~~ |
| 190 | + |
| 191 | +For more information about executing aggregation operations with the {+driver-short+}, |
| 192 | +see the following API documentation: |
| 193 | + |
| 194 | +- `aggregate() <{+api+}/classmongocxx_1_1v__noabi_1_1collection.html#a480f6d0f9986d43b1d17d6ed8876941d>`__ |
| 195 | +- `mongocxx::options::aggregate <{+api+}/classmongocxx_1_1v__noabi_1_1options_1_1aggregate.html>`__ |
0 commit comments