<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision: 329620 $ -->
<refentry xml:id="mongocollection.group" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoCollection::group</refname>
  <refpurpose>Performs an operation similar to SQL's GROUP BY command</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>array</type><methodname>MongoCollection::group</methodname>
   <methodparam><type>mixed</type><parameter>keys</parameter></methodparam>
   <methodparam><type>array</type><parameter>initial</parameter></methodparam>
   <methodparam><type>MongoCode</type><parameter>reduce</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
  </methodsynopsis>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;  
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>keys</parameter>
     </term>
     <listitem>
      <para>
       Fields to group by.  If an array or non-code object is passed, it will be
       the key used to group results. 
      </para>
      <para>1.0.4+: If <parameter>keys</parameter> is an instance of 
       <classname>MongoCode</classname>, <parameter>keys</parameter> will be treated as
       a function that returns the key to group by (see the "Passing a 
       <parameter>keys</parameter> function" example below).  
      </para>
     </listitem>
    </varlistentry>   
    <varlistentry>
     <term>
      <parameter>initial</parameter>
     </term>
     <listitem>
      <para>
       Initial value of the aggregation counter object.
      </para>
     </listitem>
    </varlistentry>   
    <varlistentry>
     <term>
      <parameter>reduce</parameter>
     </term>
     <listitem>
      <para>
       A function that takes two arguments (the current document and the 
       aggregation to this point) and does the aggregation.
      </para>
     </listitem>
    </varlistentry>   
    <varlistentry>
     <term>
      <parameter>options</parameter>
     </term>
     <listitem>
      <para>
       Optional parameters to the group command.  Valid options include:
      </para>
      <itemizedlist>
       <listitem>
        <para>
         <literal>"condition"</literal>
        </para>
        <para>
         Criteria for including a document in the aggregation.
        </para>
       </listitem>
       <listitem>
        <para>
         <literal>"finalize"</literal>
        </para>
        <para>
         Function called once per unique key that takes the final output of the
         reduce function.
        </para>
       </listitem>
      </itemizedlist>
     </listitem>
    </varlistentry>   
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array containing the result.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>1.2.11</entry>
       <entry>
        Emits <constant>E_DEPRECATED</constant> when
        <parameter>options</parameter> is <type>scalar</type>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>MongoCollection::group</function> example</title>
   <para>
    This groups documents by category and creates a list of names within that
    category.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$collection->insert(array("category" => "fruit", "name" => "apple"));
$collection->insert(array("category" => "fruit", "name" => "peach"));
$collection->insert(array("category" => "fruit", "name" => "banana"));
$collection->insert(array("category" => "veggie", "name" => "corn"));
$collection->insert(array("category" => "veggie", "name" => "broccoli"));

$keys = array("category" => 1);

$initial = array("items" => array());

$reduce = "function (obj, prev) { prev.items.push(obj.name); }";

$g = $collection->group($keys, $initial, $reduce);

echo json_encode($g['retval']);

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
[{"category":"fruit","items":["apple","peach","banana"]},{"category":"veggie","items":["corn","broccoli"]}]
]]>
   </screen>
  </example>

  <example>
   <title><function>MongoCollection::group</function> example</title>
   <para>
    This example doesn't use any key, so every document will be its own group.
    It also uses a condition: only documents that match this condition will be
    processed by the grouping function.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$collection->save(array("a" => 2));
$collection->save(array("b" => 5));
$collection->save(array("a" => 1));

// use all fields
$keys = array();

// set intial values
$initial = array("count" => 0);

// JavaScript function to perform
$reduce = "function (obj, prev) { prev.count++; }";

// only use documents where the "a" field is greater than 1
$condition = array('condition' => array("a" => array( '$gt' => 1)));

$g = $collection->group($keys, $initial, $reduce, $condition);

var_dump($g);

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
array(4) {
  ["retval"]=>
  array(1) {
    [0]=>
    array(1) {
      ["count"]=>
      float(1)
    }
  }
  ["count"]=>
  float(1)
  ["keys"]=>
  int(1)
  ["ok"]=>
  float(1)
}
]]>
   </screen>
  </example>

  <example>
   <title>Passing a <parameter>keys</parameter> function</title>
   <para>
    If you want to group by something other than a field name, you can pass
    a function as the first parameter of 
    <function>MongoCollection::group</function> and it will be run against each
    document.  The return value of the function will be used as its grouping 
    value.
   </para>
   <para>
    This example demonstrates grouping by the num field modulo 4.
   </para>

   <programlisting role="php">
<![CDATA[
<?php

$c->group(new MongoCode('function(doc) { return {mod : doc.num % 4}; }'),
     array("count" => 0),
     new MongoCode('function(current, total) { total.count++; }'));

?>
]]>
   </programlisting>
  </example>
 </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
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
-->