MongoCollection::group

(PECL mongo >=0.9.2)

MongoCollection::group — Lleva a cabo una operación similar al comando GROUP BY de SQL

Descripción

public array MongoCollection::group ( mixed $keys , array $initial , MongoCode $reduce [, array $options = array() ] )

Parámetros

keys

Campos a agrupar. Si se pasa un array o un objeto que no es de código, será la clave usada para agrupar resultados.

1.0.4+: Si keys es una instancia de MongoCode, keys será tratado como una función que devuelve la clave con la que agrupar (revise el ejemplo de abajo sobre "Pasar una función a keys").

initial

Valor inicial del objeto contador de acumulación.

reduce

Una función que toma dos argumentos (el documento actual y la acumulación en este punto) y realiza la acumulación.

options

Parámetros opcionales para el comando group. Las opciones válidas son:

  • "condition"

    Condición para incluir un documento a la acumulación.

  • "finalize"

    Función que se invoca por cada clave única que toma la salida de la función reduce.

  • "maxTimeMS"

    Especifica un tiempo límite acumulativo en milisegundos para procesar la operación (no incluye el tiempo improductivo). Si la operación no se completa dentro del período de tiempo límite, se lanzará una MongoExecutionTimeoutException.

Valores devueltos

Devuelve un array que contiene el resultado.

Historial de cambios

Versión Descripción
1.5.0 Se añadió la opción "maxTimeMS".
1.2.11 Emite un error de nivel E_DEPRECATED cuando options es de tipo scalar.

Ejemplos

Ejemplo #1 Ejemplo de MongoCollection::group()

Agrupa los documentos por categoría y crea una lista de los nombres que hay dentro de dicha categoría.

<?php

$colección->insert(array("categoria" => "fruta", "nombre" => "manzana"));
$colección->insert(array("categoria" => "fruta", "nombre" => "melocoton"));
$colección->insert(array("categoria" => "fruta", "nombre" => "platano"));
$colección->insert(array("categoria" => "verdura", "nombre" => "maiz"));
$colección->insert(array("categoria" => "verdura", "nombre" => "brocoli"));

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

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

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

$g = $colección->group($keys, $initial, $reduce);

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

?>

El resultado del ejemplo sería algo similar a:

[{"categoria":"fruta","items":["manzana","melocoton","platano"]},{"categoria":"verdura","items":["maiz","brocoli"]}]

Ejemplo #2 Ejemplo de MongoCollection::group()

Este ejemplo no utiliza ninguna clave, por lo que cada documento será su propio grupo. Además, usa una condición: sólo los documentos que la cumplan serán procesados por la función de agrupación.

<?php

$colección->save(array("a" => 2));
$colección->save(array("b" => 5));
$colección->save(array("a" => 1));

// usar todos los campos
$claves = array();

// establecer valores iniciales
$inicial = array("count" => 0);

// función JavaScript a realizar
$reduce = "function (obj, prev) { prev.count++; }";

// usar sólo los documentos donde el campo "a" es mayor que 1
$condicion = array('condition' => array("a" => array( '$gt' => 1)));

$g = $colección->group($claves, $inicial, $reduce, $condicion);

var_dump($g);

?>

El resultado del ejemplo sería algo similar a:

array(4) {
  ["retval"]=>
  array(1) {
    [0]=>
    array(1) {
      ["count"]=>
      float(1)
    }
  }
  ["count"]=>
  float(1)
  ["claves"]=>
  int(1)
  ["ok"]=>
  float(1)
}

Ejemplo #3 Pasar una función a keys

Si se desea agrupar por algo distinto a un nombre de campo, se puede pasar una función como primer parámetro de MongoCollection::group(), y así se ejecutará con cada documento. Se usará el valor devuelto de la función como valor de agrupación.

Este ejemplo demuestra cómo agrupar por el campo num módulo 4 (num % 4).

<?php

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

?>