MONGOCOLLECTION.AGGREGATECURSOR(3) 1 MONGOCOLLECTION.AGGREGATECURSOR(3)
MongoCollection::aggregateCursor - Execute an aggregation pipeline command and retrieve results through a cursor
SYNOPSIS
public MongoCommandCursor MongoCollection::aggregateCursor (array $command, [array $options])
DESCRIPTION
With this method you can execute Aggregation Framework pipelines and retrieve the results through a cursor, instead of getting just one
document back as you would with MongoCollection::aggregate. This method returns a MongoCommandCursor object. This cursor object implements
the Iterator interface just like the MongoCursor objects that are returned by the MongoCollection::find method.
Note
The resulting MongoCommandCursor will inherit this collection's read preference. MongoCommandCursor::setReadPreference may be used
to change the read preference before iterating on the cursor.
PARAMETERS
o $pipeline
- The Aggregation Framework pipeline to execute.
o $options
-Options for the aggregation command. Valid options include:
o "allowDiskUse"Allow aggregation stages to write to temporary files
o "cursor" It is possible to configure how many initial documents the server should return with the first result set. The
default initial batch size is 101. You can change it by adding the batchSize option:
<?php
$collection->aggregateCursor(
$pipeline,
[ "cursor" => [ "batchSize" => 4 ] ]
);
MongoCommandCursor::batchSize method on the returned MongoCommandCursor object.
o "explain" Return information on the processing of the pipeline. This option may cause the command to return a result docu-
ment that is unsuitable for constructing a MongoCommandCursor. If you need to use this option, you should consider using
MongoCollection::aggregate.
o "maxTimeMS"Specifies a cumulative time limit in milliseconds for processing the operation (does not include idle time). If
the operation is not completed within the timeout period, a MongoExecutionTimeoutException will be thrown.
RETURN VALUES
Returns a MongoCommandCursor object. Because this implements the Iterator interface you can iterate over each of the results as returned
by the command query. The MongoCommandCursor also implements the MongoCursorInterface interface which adds the MongoCommandCursor::batch-
Size, MongoCommandCursor::dead, MongoCommandCursor::info methods.
EXAMPLES
Example #1
MongoCollection.aggregateCursor(3) example
Finding all of the distinct values for a key.
<?php
$m = new MongoClient;
$db = $m->test;
$people = $db->people;
$people->drop();
$people->insert(array("name" => "Joe", "points" => 4));
$people->insert(array("name" => "Molly", "points" => 43));
$people->insert(array("name" => "Sally", "points" => 22));
$people->insert(array("name" => "Joe", "points" => 22));
$people->insert(array("name" => "Molly", "points" => 87));
$ages = $people->aggregateCursor( [
[ '$group' => [ '_id' => '$name', 'points' => [ '$sum' => '$points' ] ] ],
[ '$sort' => [ 'points' => -1 ] ],
] );
foreach ($ages as $person) {
echo "{$person['_id']}: {$person['points']}
";
}
?>
The above example will output something similar to:
Joe: 26 Sally: 22
Example #2
MongoCollection.aggregateCursor(3) example with different initial batch size
Finding all of the distinct values for a key.
<?php
$m = new MongoClient;
$db = $m->test;
$people = $db->people;
$people->drop();
/* Insert some sample data */
$people->insert(array("name" => "Joe", "points" => 4));
$people->insert(array("name" => "Molly", "points" => 43));
$people->insert(array("name" => "Sally", "points" => 22));
$people->insert(array("name" => "Joe", "points" => 22));
$people->insert(array("name" => "Molly", "points" => 87));
/* Run the command cursor */
$ages = $people->aggregateCursor(
[
[ '$group' => [ '_id' => '$name', 'points' => [ '$sum' => '$points' ] ] ],
[ '$sort' => [ 'points' => -1 ] ],
],
[ "cursor" => [ "batchSize" => 4 ] ]
);
foreach ($ages as $person) {
echo "{$person['_id']}: {$person['points']}
";
}
?>
The above example will output something similar to:
Joe: 26 Sally: 22
SEE ALSO
MongoDB::command, MongoCommandCursor, MongoCommandCursor::batchSize, MongoCollection::aggregate, The MongoDB aggregation framework.
PHP Documentation Group MONGOCOLLECTION.AGGREGATECURSOR(3)