MongoCollection::aggregate

(PECL mongo >=1.3.0)

MongoCollection::aggregate — Realiza una acumulación usando el framework de acumulación

Descripción

public array MongoCollection::aggregate ( array $pipeline [, array $options ] )

public array MongoCollection::aggregate ( array $op [, array $op [, array $... ]] )

El » framework de agregación de MongoDB proporciona medios para calcular valores acumulados sin tener que usar MapReduce. Aunque MapReduce es potente, a menudo es más dificultoso de lo necesario para muchas tareas sencillas de acumulación, tales como totalizar o hallar la media de valores de campos.

Este método acepta tanto una cantidad variable de operadores de tubería como un único array de dichos operadores constituyendo la tubería.

Parámetros

pipeline

Un array de operadores de tubería.

options

Opciones para el comando de acumulación. Las opciones válidas son:

"allowDiskUse"

Permitir que la agregación pueda escribir ficheros temporales
"cursor"

Opciones para controlar la creación del objeto cursor. Esta opción causa que el comando devuelva un documento de resultados apto para construir un MongoCommandCursor. Si fuera necesario usar esta opción, se debería considerar el uso MongoCollection::aggregateCursor().
"explain"

Devuelve información sobre el procesamiento de la tubería.
"maxTimeMS"
Especifica un tiempo límite acumulativo en milisegundos para procesar la operación en el servdiro (no incluye el tiempo improductivo). Si la operación no la completa el servidor dentro del período de tiempo límite, se lanzará una MongoExecutionTimeoutException.

op: Primer operador de tubería.
op: Segundo operador de tubería.
...: Operadores de tubería adicionales.

Valores devueltos

Un array con el resultado de la acumulación. ok será establecido a 1 en caso de éxito, 0 en caso de error.

Errores/Excepciones

Cuando ocurre un error se devuelve un array con las siguientes claves:

errmsg - contiene la razón del fallo
code - el código de error del fallo
ok - será establecido a 0.

Historial de cambios

Versión	Descripción
1.5.0	Se añadió el parámetro opcional `options`

Ejemplos

Ejemplo #1 Ejemplo de MongoCollection::aggregate()

El siguiente ejemplo de operación acumulativa pivota datos para crear un conjunto de nombres de autores agrupados por etiquetas aplicadas a un artículo. Se llama al framework de acumulación usando el siguiente comando:


<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("examples")->selectCollection("article");
$datos = 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($datos, 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'),
        ),
    ),
);
$resultados = $c->aggregate($ops);
var_dump($resultados);
?>

El resultado del ejemplo sería:

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)
}

El siguiente ejemplo usa el » conjunto de datos de códigos zip. Utilice mongoimport para cargar este conjunto de datos en una instancia de mongod.

Ejemplo #2 Ejemplo de MongoCollection::aggregate()

Para devolver todos los estados con una población de más de 10 millones, se usa la siguiente operación acumulativa:


<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("test")->selectCollection("zips");

$tubería = array(
    array(
        '$group' => array(
            '_id' => array('state' => '$state'),
            'totalPop' => array('$sum' => '$pop')
        )
    ),
    array(
        '$match' => array(
            'totalPop' => array('$gte' => 10 * 1000 * 1000)
        )
    ),
);
$salida = $c->aggregate($tubería);
var_dump($salida);
?>

El resultado del ejemplo sería algo similar a:

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)
}

Ejemplo #3 Ejemplo de MongoCollection::aggregate()

Para devolver la población media de las ciudades de cada estado, use la siguiente operación acumulativa:


<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("test")->selectCollection("zips");

$salida = $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($salida);
?>

El resultado del ejemplo sería algo similar a:

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)
}

Ejemplo #4 MongoCollection::aggregate() con opciones de comandos

Para devolver información sobre cómo será procesada la tubería, se use la opción de comando explain


<?php
$m = new MongoClient;
$c = $m->selectDB("test")->selectCollection("zips");

$tubería = array(
    array(
        '$group' => array(
            '_id' => '$state',
           'totalPop' => array('$sum' => '$pop'),
        ),
    ),
    array(
        '$match' => array(
            'totalPop' => array('$gte' => 10 * 1000 * 1000)
        )
    ),
    array(
        '$sort' => array("totalPop" => -1),
    ),
);

$opciones = array("explain" => true);
$salida = $c->aggregate($tubería, $opciones);
var_dump($salida);
?>

El resultado del ejemplo sería algo similar a:

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)
}

Ver también

MongoCollection::aggregateCursor() - Ejecutar un comando de tubería acumulador y recuperar los resultados mediante un cursor
El » framework de acumulación de MongoDB