Skip to content

Commit baa60ec

Browse files
norareidynorareidy
committed
DOCSP-41988: Aggregation
1 parent 474fc1f commit baa60ec

File tree

2 files changed

+235
-0
lines changed

2 files changed

+235
-0
lines changed

‎source/aggregation.txt

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
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+
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 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 aggregation pipeline
98+
stages to 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+
112+
.. input:: /includes/aggregation.php
113+
:start-after: start-match-group
114+
:end-before: end-match-group
115+
:language: php
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 passing
138+
the command information to the ``MongoDB\Database::command()`` method. You must set the
139+
``aggregate``, ``pipeline``, and ``cursor`` fields of the ``explain`` command document
140+
to explain the aggregation.
141+
142+
The following example instructs MongoDB to explain the aggregation operation from the
143+
preceding :ref:`php-aggregation-example`:
144+
145+
.. io-code-block::
146+
147+
.. input:: /includes/aggregation.php
148+
:start-after: start-explain
149+
:end-before: end-explain
150+
:language: php
151+
:dedent:
152+
153+
.. output::
154+
155+
{"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants",
156+
"indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3",
157+
"planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false,
158+
"maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"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:`php-aggregation-tutorials-landing`.
187+
188+
API Documentation
189+
~~~~~~~~~~~~~~~~~
190+
191+
For more information about executing aggregation operations by using the {+php-library+},
192+
see `MongoDB\\Collection::aggregate() <{+api+}/method/MongoDBCollection-aggregate/>`__ in
193+
the API documentation.

‎source/includes/aggregation.php

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<?php
2+
require 'vendor/autoload.php';
3+
4+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
5+
$client = new MongoDB\Client($uri);
6+
7+
$collection = $client->sample_restaurants->restaurants;
8+
9+
// Retrieves documents with a cuisine value of "Bakery", groups them by "borough", and
10+
// counts each borough's matching documents
11+
// start-match-group
12+
$pipeline = [
13+
['$match' => ['cuisine' => 'Bakery']],
14+
['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]]
15+
];
16+
17+
$cursor = $collection->aggregate($pipeline);
18+
19+
foreach ($cursor as $doc) {
20+
echo json_encode($doc) . PHP_EOL;
21+
}
22+
// end-match-group
23+
24+
// Performs the same aggregation operation as above but asks MongoDB to explain it
25+
// start-explain
26+
$pipeline = [
27+
['$match' => ['cuisine' => 'Bakery']],
28+
['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]]
29+
];
30+
31+
$command = [
32+
'explain' => [
33+
'aggregate' => 'restaurants',
34+
'pipeline' => $pipeline,
35+
'cursor' => new stdClass()
36+
]
37+
];
38+
39+
$result = $db->command($command)->toArray();
40+
echo json_encode($result[0]) . PHP_EOL;
41+
// end-explain
42+

0 commit comments

Comments
 (0)