Effectue une agrégation en utilisant le framework dédié

# MongoCollection::aggregate

(PECL mongo >=1.3.0)

MongoCollection::aggregate — Effectue une agrégation en utilisant le framework dédié

### Description

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

Le » framework agrégation de MongoDB fournit une façon de calculer des valeurs agrégées sans avoir à utiliser MapReduce. Bien que MapReduce soit performant, il est souvent plus compliqué que nécessaire pour des tâches d'agrégation simples, comme le calcul du total ou de la moyenne des valeurs d'un champ.

Cette méthode accepte soit une variable au début du pipeline des opérateurs, ou un tableau simple d'opérateurs constituant le pipeline.

### Liste de paramètres

`pipeline`

  Un tableau d'opérateurs de pipeline.

`options`

  Options pour la commande d'agrégation. Les options valides sont :

  - "allowDiskUse"

    Autorise les opérations d'agrégation d'écrire dans les fichiers temporaires

  - "cursor"

    Options controllant la créatun d'un objet curseur. Cette option fait que la commande va retourner un document prêt pour construire un MongoCommandCursor. Si vous avez besoin d'utiliser cette option, vous devriez considérer l'utilisation de la méthode MongoCollection::aggregateCursor().

  - "explain"

    Retourne des informations quant à l'exécution du pipeline.

  - "maxTimeMS"

    Spécifie une limite cumulative de temps, en millisecondes, pour procéder à l'opération (n'inclut pas le temps d'inactivité). Si l'opération n'est pas terminée durant cette période, une exception MongoExecutionTimeoutException sera émise.

Ou

`op`

  Premier opérateur de pipeline.

`op`

  Second opérateur de pipeline.

`...`

  Opérateurs additionnels de pipeline.

### Valeurs de retour

Le résultat del'agrégation, sous la forme d'un tableau. La clé ok vaudra 1 en cas de succès, 0 si une erreur survient.

### Erreurs / Exceptions

Lorsqu'une erreur survient, un tableau contenant les clés suivantes sera retourné :

- errmsg - contient la raison de l'échec
- code - le code erreur de l'échec
- ok - vaudra 0.

### Historique

Version | Description
--- | ---
1.5.0 | Ajout de l'argument optionnel `options`

### Exemples

Exemple #1 Exemple avec MongoCollection::aggregate()

L'exemple d'agrégation suivant opère sur des données pivots pour créer un jeu de noms d'auteurs, groupé par les tags appliqués à un article. Appelez le framework d'agrégation en utilisant la commande suivante :

`<?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);
?>`

L'exemple ci-dessus va afficher :

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

L'exemple suivant utilise le » jeu de données zipcode. Utilisez mongoimport pour charger ce jeu de données dans l'instance mongod.

Exemple #2 Exemple avec MongoCollection::aggregate()

Pour retourner tous les états avec une population supérieure à 10 million, utilisez l'opération d'agrégation suivante :

`<?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);
?>`

L'exemple ci-dessus va afficher quelque chose de similaire à :

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

Exemple #3 Exemple avec MongoCollection::aggregate()

Pour retourner la moyenne de la population pour les villes de chaque état, utilisez l'opération d'agrégation suivante :

`<?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);
?>`

L'exemple ci-dessus va afficher quelque chose de similaire à :

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

Exemple #4 Exemple avec MongoCollection::aggregate() et des options de commande

Pour retourner des informations sur l'exécution de la pipeline, nous utilisons l'option de commande explain.

`<?php
$m = new MongoClient;
$c = $m->selectDB("test")->selectCollection("zips");
$pipeline = 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);
?>`

L'exemple ci-dessus va afficher quelque chose de similaire à :

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

### Voir aussi

- MongoCollection::aggregateCursor() - Exécute une commande d'agrégation, et récupère les résultats via un curseur
- Le » framework d'agrégation de MongoDB