Php/docs/mongocursor.addoption
MongoCursor::addOption
(PECL mongo >=1.0.4)
MongoCursor::addOption — Adds a top-level key/value pair to a query
Description
public MongoCursor::addOption
( string $key
, mixed $value
) : MongoCursor
This is an advanced function and should not be used unless you know what you're doing.
A query can optionally be nested in a "query" field if other options, such as a sort or hint, are given. For instance, adding a sort causes the query to become a subfield of a bigger query object, like:
<?php$query = array("query" => $query, "orderby" => $sort);?>
This method is for adding a top-level field to a query. It makes the query a subobject (if it isn't already) and adds the key/value pair of your chosing to the top level.
Warning It cannot be used to add extra criteria to a query on the fly. For instance, this will not work:
<?php// NOT CORRECT$cursor = $users->find()->addOption("name", "joe")->addOption("age", 20);?>
This does not query for a user named "joe" with an age of 20.
Parameters
key- Fieldname to add.
value- Value to add.
Return Values
Returns this cursor.
Examples
Example #1 Adding a comment with MongoCursor::addOption() example
MongoDB supports special options to be send to the server. The shell uses
the _addSpecial option to send a
$comment to the server. This comment will show up in
the profiling log (for slow queries f.e.). In the PHP driver, you use the
MongoCursor::addOption() method.
<?php$m = new MongoClient;$c = $m->demo->demo;$cursor = $c->find();$cursor->addOption('$comment', "This comment will show up in the profiling log");foreach ($cursor as $document) { /* empty */ }?>
The above example will output something similar to:
{
"op" : "query",
"ns" : "demo.demo",
"query" : {
"$query" : {
},
"$comment" : "This comment will show up in the profiling log"
},
"cursorid" : 168463566447,
"ntoreturn" : 0,
"ntoskip" : 0,
"nscanned" : 101,
"nscannedObjects" : 101,
"keyUpdates" : 0,
"numYield" : 0,
…
Example #2 MongoCursor::addOption() example
Using MongoCursor::skip() to skip over millions of
results can become slow. One way around this is to use
$min or $max options for the query.
These can be handy, but they require an index on exactly the fields being
searched for. This is an example of how to use $min as
an alternative to MongoCursor::skip().
<?php// make sure we have an index$c->ensureIndex(array("ts" => 1));// you may have to modify this to run in a reasonable amount of time on slow // machines (should take about 30 seconds on a good machine)for ($i = 0; $i < 30000000; $i++) { $c->insert(array("ts" => new MongoDate(), "i" => $i));}$now = strtotime("now");// find documents inserted in the last 2 seconds$cursor = $c->find()->addOption('$min', array("ts" => $now-2));?>
