MongoCollection::aggregate
(PECL mongo >=1.3.0)
MongoCollection::aggregate — Perform an aggregation using the aggregation framework
Description
$pipeline
[, array $options
] ) : array$op
[, array $op
[, array $...
]] ) : arrayThe MongoDB » aggregation framework provides a means to calculate aggregated values without having to use MapReduce. While MapReduce is powerful, it is often more difficult than necessary for many simple aggregation tasks, such as totaling or averaging field values.
This method accepts either a variable amount of pipeline operators, or a single array of operators constituting the pipeline.
Parameters
-
pipeline -
An array of pipeline operators.
-
options -
Options for the aggregation command. Valid options include:
-
"allowDiskUse"
Allow aggregation stages to write to temporary files
-
"cursor"
Options controlling the creation of the cursor object. This option causes the command to return a result document suitable for constructing a MongoCommandCursor. If you need to use this option, you should consider using MongoCollection::aggregateCursor().
-
"explain"
Return information on the processing of the pipeline.
"maxTimeMS"
Specifies a cumulative time limit in milliseconds for processing the operation on the server (does not include idle time). If the operation is not completed by the server within the timeout period, a MongoExecutionTimeoutException will be thrown.
-
Or
-
op -
First pipeline operator.
-
op -
The second pipeline operator.
-
... -
Additional pipeline operators.
Return Values
The result of the aggregation as an array. The ok will be set to 1 on success, 0 on failure.
Errors/Exceptions
When an error occurs an array with the following keys will be returned:
- errmsg - containing the reason for the failure
- code - the errorcode of the failure
- ok - will be set to 0.
Examples
Example #1 MongoCollection::aggregate() example
The following example aggregation operation pivots data to create a set of author names grouped by tags applied to an article. Call the aggregation framework by issuing the following command:
<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("examples")->selectCollection("article");
$data = array (
'title' => 'this is my title',
'author' => 'bob',
'posted' => new MongoDate,
'pageViews' => 5,
'tags' => array ( 'fun', 'good', 'fun' ),
'comments' => array (
array (
'author' => 'joe',
'text' => 'this is cool',
),
array (
'author' => 'sam',
'text' => 'this is bad',
),
),
'other' =>array (
'foo' => 5,
),
);
$d = $c->insert($data, array("w" => 1));
$ops = array(
array(
'$project' => array(
"author" => 1,
"tags" => 1,
)
),
array('$unwind' => '$tags'),
array(
'$group' => array(
"_id" => array("tags" => '$tags'),
"authors" => array('$addToSet' => '$author'),
),
),
);
$results = $c->aggregate($ops);
var_dump($results);
?>
The above example will output:
array(2) {
["result"]=>
array(2) {
[0]=>
array(2) {
["_id"]=>
array(1) {
["tags"]=>
string(4) "good"
}
["authors"]=>
array(1) {
[0]=>
string(3) "bob"
}
}
[1]=>
array(2) {
["_id"]=>
array(1) {
["tags"]=>
string(3) "fun"
}
["authors"]=>
array(1) {
[0]=>
string(3) "bob"
}
}
}
["ok"]=>
float(1)
}
The following examples use the » zipcode data set. Use mongoimport to load this data set into your mongod instance.
Example #2 MongoCollection::aggregate() example
To return all states with a population greater than 10 million, use the following aggregation operation:
<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("test")->selectCollection("zips");
$pipeline = array(
array(
'$group' => array(
'_id' => array('state' => '$state'),
'totalPop' => array('$sum' => '$pop')
)
),
array(
'$match' => array(
'totalPop' => array('$gte' => 10 * 1000 * 1000)
)
),
);
$out = $c->aggregate($pipeline);
var_dump($out);
?>
The above example will output something similar to:
array(2) {
["result"]=>
array(7) {
[0]=>
array(2) {
["_id"]=>
string(2) "TX"
["totalPop"]=>
int(16986510)
}
[1]=>
array(2) {
["_id"]=>
string(2) "PA"
["totalPop"]=>
int(11881643)
}
[2]=>
array(2) {
["_id"]=>
string(2) "NY"
["totalPop"]=>
int(17990455)
}
[3]=>
array(2) {
["_id"]=>
string(2) "IL"
["totalPop"]=>
int(11430602)
}
[4]=>
array(2) {
["_id"]=>
string(2) "CA"
["totalPop"]=>
int(29760021)
}
[5]=>
array(2) {
["_id"]=>
string(2) "OH"
["totalPop"]=>
int(10847115)
}
[6]=>
array(2) {
["_id"]=>
string(2) "FL"
["totalPop"]=>
int(12937926)
}
}
["ok"]=>
float(1)
}
Example #3 MongoCollection::aggregate() example
To return the average populations for cities in each state, use the following aggregation operation:
<?php
$m = new MongoClient;
$c = $m->selectDB("test")->selectCollection("zips");
$out = $c->aggregate(
array(
'$group' => array(
'_id' => array('state' => '$state', 'city' => '$city' ),
'pop' => array('$sum' => '$pop' )
)
),
array(
'$group' => array(
'_id' => '$_id.state',
'avgCityPop' => array('$avg' => '$pop')
)
)
);
var_dump($out);
?>
The above example will output something similar to:
array(2) {
["result"]=>
array(51) {
[0]=>
array(2) {
["_id"]=>
string(2) "DC"
["avgCityPop"]=>
float(303450)
}
[1]=>
array(2) {
["_id"]=>
string(2) "DE"
["avgCityPop"]=>
float(14481.913043478)
}
...
[49]=>
array(2) {
["_id"]=>
string(2) "WI"
["avgCityPop"]=>
float(7323.0074850299)
}
[50]=>
array(2) {
["_id"]=>
string(2) "WV"
["avgCityPop"]=>
float(2759.1953846154)
}
}
["ok"]=>
float(1)
}
Example #4 MongoCollection::aggregate() with command options
To return information on how the pipeline will be processed we use the explain command option:
<?php
$m = new MongoClient;
$c = $m->selectDB("test")->selectCollection("zips");
$pipeline = array(
array(
'$group' => array(
'_id' => '$state',
'totalPop' => array('$sum' => '$pop'),
),
),
array(
'$match' => array(
'totalPop' => array('$gte' => 10 * 1000 * 1000)
)
),
array(
'$sort' => array("totalPop" => -1),
),
);
$options = array("explain" => true);
$out = $c->aggregate($pipeline, $options);
var_dump($out);
?>
The above example will output something similar to:
array(2) {
["stages"]=>
array(4) {
[0]=>
array(1) {
["$cursor"]=>
array(3) {
["query"]=>
array(0) {
}
["fields"]=>
array(3) {
["pop"]=>
int(1)
["state"]=>
int(1)
["_id"]=>
int(0)
}
["plan"]=>
array(4) {
["cursor"]=>
string(11) "BasicCursor"
["isMultiKey"]=>
bool(false)
["scanAndOrder"]=>
bool(false)
["allPlans"]=>
array(1) {
[0]=>
array(3) {
["cursor"]=>
string(11) "BasicCursor"
["isMultiKey"]=>
bool(false)
["scanAndOrder"]=>
bool(false)
}
}
}
}
}
[1]=>
array(1) {
["$group"]=>
array(2) {
["_id"]=>
string(6) "$state"
["totalPop"]=>
array(1) {
["$sum"]=>
string(4) "$pop"
}
}
}
[2]=>
array(1) {
["$match"]=>
array(1) {
["totalPop"]=>
array(1) {
["$gte"]=>
int(10000000)
}
}
}
[3]=>
array(1) {
["$sort"]=>
array(1) {
["sortKey"]=>
array(1) {
["totalPop"]=>
int(-1)
}
}
}
}
["ok"]=>
float(1)
}
See Also
- MongoCollection::aggregateCursor() - Execute an aggregation pipeline command and retrieve results through a cursor
- The MongoDB » aggregation framework
English translation
You have asked to visit this site in English. For now, only the interface is translated, but not all the content yet.If you want to help me in translations, your contribution is welcome. All you need to do is register on the site, and send me a message asking me to add you to the group of translators, which will give you the opportunity to translate the pages you want. A link at the bottom of each translated page indicates that you are the translator, and has a link to your profile.
Thank you in advance.
Document created the 30/01/2003, last modified the 26/10/2018
Source of the printed document:https://www.gaudry.be/en/php-rf-mongocollection.aggregate.html
The infobrol is a personal site whose content is my sole responsibility. The text is available under CreativeCommons license (BY-NC-SA). More info on the terms of use and the author.
References
These references and links indicate documents consulted during the writing of this page, or which may provide additional information, but the authors of these sources can not be held responsible for the content of this page.
The author This site is solely responsible for the way in which the various concepts, and the freedoms that are taken with the reference works, are presented here. Remember that you must cross multiple source information to reduce the risk of errors.
