sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-04-01 00:38:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
php-doc-en/reference/mongo/mongocollection/aggregate.xml
Derick Rethans 0d871eae6e Fixed example 
and also some typoes.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@339160 c90b9560-bf6c-de11-be94-00142212c4b1
2016-05-10 18:17:49 +00:00

579 lines
13 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.aggregate" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::aggregate</refname>
<refpurpose>Perform an aggregation using the aggregation framework</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::aggregate</methodname>
<methodparam><type>array</type><parameter>pipeline</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::aggregate</methodname>
<methodparam><type>array</type><parameter>op</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>op</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
</methodsynopsis>
<para>
The MongoDB
<link xlink:href="&url.mongodb.docs.aggregation;">aggregation framework</link>
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.
</para>
<para>
This method accepts either a variable amount of pipeline operators, or a
single array of operators constituting the pipeline.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>pipeline</parameter></term>
<listitem>
<para>
An array of pipeline operators.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>Options for the aggregation command. Valid options include:</para>
<itemizedlist>
<listitem>
<para><literal>"allowDiskUse"</literal></para>
<para>Allow aggregation stages to write to temporary files</para>
</listitem>
<listitem>
<para><literal>"cursor"</literal></para>
<para>
Options controlling the creation of the cursor object. This option
causes the command to return a result document suitable for constructing
a <classname>MongoCommandCursor</classname>. If you need to use this
option, you should consider using
<methodname>MongoCollection::aggregateCursor</methodname>.
</para>
</listitem>
<listitem>
<para><literal>"explain"</literal></para>
<para>Return information on the processing of the pipeline.</para>
</listitem>
&mongo.command.parameters.maxtimems;
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<para>Or</para>
<variablelist>
<varlistentry>
<term><parameter>op</parameter></term>
<listitem>
<para>
First pipeline operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>op</parameter></term>
<listitem>
<para>
The second pipeline operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>...</parameter></term>
<listitem>
<para>
Additional pipeline operators.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The result of the aggregation as an array. The <varname>ok</varname> will
be set to <literal>1</literal> on success, <literal>0</literal> on failure.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
When an error occurs an array with the following keys will be returned:
<itemizedlist>
<listitem>
<simpara>
<varname>errmsg</varname> - containing the reason for the failure
</simpara>
</listitem>
<listitem>
<simpara>
<varname>code</varname> - the errorcode of the failure
</simpara>
</listitem>
<listitem>
<simpara>
<varname>ok</varname> - will be set to 0.
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>1.5.0</entry>
<entry>
Added optional <parameter>options</parameter> argument
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1><!-- }}} -->
<refsect1 role="examples">
&reftitle.examples;
<example xml:id="mongocollection.aggregate.example.basic">
<title><methodname>MongoCollection::aggregate</methodname> example</title>
<para>
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:
</para>
<programlisting role="php">
<![CDATA[
<?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);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
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)
}
]]>
</screen>
</example>
<para>
The following examples use the <link xlink:href="&url.mongodb.examples.zipcode;">zipcode data set</link>.
Use mongoimport to load this data set into your mongod instance.
</para>
<example xml:id="mongocollection.aggregate.example.zipcode.population">
<title><methodname>MongoCollection::aggregate</methodname> example</title>
<para>
To return all states with a population greater than 10 million, use the following aggregation operation:
</para>
<programlisting role="php">
<![CDATA[
<?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);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
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)
}
]]>
</screen>
</example>
<example xml:id="mongocollection.aggregate.example.zipcode.population.average">
<title><methodname>MongoCollection::aggregate</methodname> example</title>
<para>
To return the average populations for cities in each state, use the following aggregation operation:
</para>
<programlisting role="php">
<![CDATA[
<?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);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
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)
}
]]>
</screen>
</example>
<example xml:id="mongocollection.aggregate.example.zipcode.explain">
<title><methodname>MongoCollection::aggregate</methodname> with command options</title>
<para>
To return information on how the pipeline will be processed we use the
<literal>explain</literal> command option:
</para>
<programlisting role="php">
<![CDATA[
<?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);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
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)
}
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoCollection::aggregateCursor</methodname></member>
<member>The MongoDB <link xlink:href="&url.mongodb.docs.aggregation;">aggregation framework</link></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Reference in a new issue View git blame Copy permalink