|
| 1 | +.. _php-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 PHP library 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 {+php-library+} 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 | +Consider the following limitations when performing 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 creating an options array that sets the ``allowDiskUse`` option to ``true`` |
| 77 | + and passing the array to the ``MongoDB\Collection::aggregate()`` method. |
| 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 ``allowDiskUse`` option. |
| 84 | + |
| 85 | +.. _php-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 an array containing the pipeline stages to |
| 98 | +the ``MongoDB\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 | + :copyable: |
| 112 | + |
| 113 | + .. input:: /includes/aggregation.php |
| 114 | + :start-after: start-match-group |
| 115 | + :end-before: end-match-group |
| 116 | + :language: php |
| 117 | + :dedent: |
| 118 | + |
| 119 | + .. output:: |
| 120 | + :visible: false |
| 121 | + |
| 122 | + {"_id":"Brooklyn","count":173} |
| 123 | + {"_id":"Queens","count":204} |
| 124 | + {"_id":"Bronx","count":71} |
| 125 | + {"_id":"Staten Island","count":20} |
| 126 | + {"_id":"Missing","count":2} |
| 127 | + {"_id":"Manhattan","count":221} |
| 128 | + |
| 129 | +Explain an Aggregation |
| 130 | +~~~~~~~~~~~~~~~~~~~~~~ |
| 131 | + |
| 132 | +To view information about how MongoDB executes your operation, you can |
| 133 | +instruct the MongoDB query planner to **explain** it. When MongoDB explains |
| 134 | +an operation, it returns **execution plans** and performance statistics. |
| 135 | +An execution plan is a potential way in which MongoDB can complete an operation. |
| 136 | +When you instruct MongoDB to explain an operation, it returns both the |
| 137 | +plan MongoDB executed and any rejected execution plans. |
| 138 | + |
| 139 | +To explain an aggregation operation, construct a ``MongoDB\Operation\Aggregate`` object |
| 140 | +and pass the database, collection, and pipeline stages as parameters. Then, pass the |
| 141 | +``MongoDB\Operation\Aggregate`` object to the ``MongoDB\Collection::explain()`` method. |
| 142 | + |
| 143 | +The following example instructs MongoDB to explain the aggregation operation |
| 144 | +from the preceding :ref:`php-aggregation-example`: |
| 145 | + |
| 146 | +.. io-code-block:: |
| 147 | + :copyable: |
| 148 | + |
| 149 | + .. input:: /includes/aggregation.php |
| 150 | + :start-after: start-explain |
| 151 | + :end-before: end-explain |
| 152 | + :language: php |
| 153 | + :dedent: |
| 154 | + |
| 155 | + .. output:: |
| 156 | + :visible: false |
| 157 | + |
| 158 | + {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", |
| 159 | + "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", |
| 160 | + "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, |
| 161 | + "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ |
| 162 | + ... } |
| 163 | + |
| 164 | +Additional Information |
| 165 | +---------------------- |
| 166 | + |
| 167 | +To view a tutorial that uses the {+php-library+} to create complex aggregation |
| 168 | +pipelines, see `Complex Aggregation Pipelines with Vanilla PHP and MongoDB |
| 169 | +<https://www.mongodb.com/developer/products/mongodb/aggregations-php-mongodb/>`__ |
| 170 | +in the MongoDB Developer Center. |
| 171 | + |
| 172 | +MongoDB Server Manual |
| 173 | +~~~~~~~~~~~~~~~~~~~~~ |
| 174 | + |
| 175 | +To learn more about the topics discussed in this guide, see the following |
| 176 | +pages in the {+mdb-server+} manual: |
| 177 | + |
| 178 | +- To view a full list of expression operators, see :manual:`Aggregation |
| 179 | + Operators </reference/operator/aggregation/>`. |
| 180 | + |
| 181 | +- To learn about assembling an aggregation pipeline and to view examples, see |
| 182 | + :manual:`Aggregation Pipeline </core/aggregation-pipeline/>`. |
| 183 | + |
| 184 | +- To learn more about creating pipeline stages, see :manual:`Aggregation |
| 185 | + Stages </reference/operator/aggregation-pipeline/>`. |
| 186 | + |
| 187 | +- To learn more about explaining MongoDB operations, see |
| 188 | + :manual:`Explain Output </reference/explain-results/>` and |
| 189 | + :manual:`Query Plans </core/query-plans/>`. |
| 190 | + |
| 191 | +.. TODO: |
| 192 | + Aggregation Tutorials |
| 193 | + ~~~~~~~~~~~~~~~~~~~~~ |
| 194 | + |
| 195 | +.. To view step-by-step explanations of common aggregation tasks, see |
| 196 | +.. :ref:`php-aggregation-tutorials-landing`. |
| 197 | + |
| 198 | +API Documentation |
| 199 | +~~~~~~~~~~~~~~~~~ |
| 200 | + |
| 201 | +To learn more about the methods discussed in this guide, see the |
| 202 | +following API documentation: |
| 203 | + |
| 204 | +- `MongoDB\\Collection::aggregate() <{+api+}/method/MongoDBCollection-aggregate/>`__ |
| 205 | +- `MongoDB\\Collection::explain() <{+api+}/method/MongoDBCollection-explain/>`__ |
0 commit comments