MONGOCURSOR.SLAVEOKAY(3) 1 MONGOCURSOR.SLAVEOKAY(3)MongoCursor::slaveOkay - Sets whether this query can be done on a secondary [deprecated]
SYNOPSIS
public MongoCursor MongoCursor::slaveOkay ([bool $okay = true])
DESCRIPTION
Warning
This method is deprecated since version 1.5.0. Instead, please use MongoCursor::setReadPreference and "Read Preferences".
Calling this will make the driver route reads to secondaries if:
o You are using a replica set, and
o You created a MongoClient instance using the option
"replicaSet" => "setName", and
o There is a healthy secondary that can be reached by the driver.
You can check which server was used for this query by calling MongoCursor.info(3) after running the query. It's server field will show
which server the query was sent to.
Note that you should use this function even if you do not use the automatic routing to secondaries. If you connect directly to a secondary
in a replica set, you still need to call this function, which basically tells the database that you are aware that you might be getting
older data and you're okay with that. If you do not call this, you'll get "not master" errors when you try to query.
This method will override the static class variable $MongoCursor::$slaveOkay. It will also override Mongo.setSlaveOkay(3), MongoDB.set-
SlaveOkay(3) and MongoCollection.setSlaveOkay(3).
PARAMETERS
o $okay
- If it is okay to query the secondary.
RETURN VALUES
Returns this cursor.
ERRORS /EXCEPTIONS
Throws MongoCursorException if this cursor has started iterating.
EXAMPLES
Example #1
MongoCursor.slaveOkay(3) example
<?php
MongoCursor::$slaveOkay = false;
// cannot query secondary
$cursor = $collection->find();
// can query secondary
$cursor = $collection->find()->slaveOkay();
MongoCursor::$slaveOkay = true;
// can query secondary
$cursor = $collection->find();
// cannot query secondary
$cursor = $collection->find()->slaveOkay(false);
?>
SEE ALSO";Read Preferences ,
MongoCursor::setReadPreference, MongoCursor::getReadPreference.
CHANGELOG
+--------+---------------------------------------------------+
|Version | |
| | |
| | Description |
| | |
+--------+---------------------------------------------------+
| 1.5.0 | |
| | |
| | This method has been deprecated in favour of |
| | MongoCursor::setReadPreference and "Read Prefer- |
| | ences". |
| | |
+--------+---------------------------------------------------+
PHP Documentation Group MONGOCURSOR.SLAVEOKAY(3)
Check Out this Related Man Page
MONGOCURSOR(3) 1 MONGOCURSOR(3)The MongoCursor classINTRODUCTION
A cursor is used to iterate through the results of a database query. For example, to query the database and see all results, you could do:
Example #1
MongoCursor basic usage
<?php
$cursor = $collection->find();
var_dump(iterator_to_array($cursor));
?>
You don't generally create cursors using the MongoCursor constructor, you get a new cursor by calling MongoCollection.find(3) (as shown
above).
Suppose that, in the example above, $collection was a 50GB collection. We certainly wouldn't want to load that into memory all at once,
which is what a cursor is for: allowing the client to access the collection in dribs and drabs.
If we have a large result set, we can iterate through it, loading a few megabytes of results into memory at a time. For example, we could
do:
Example #2
Iterating over MongoCursor
<?php
$cursor = $collection->find();
foreach ($cursor as $doc) {
// do something to each document
}
?>
This will go through each document in the collection, loading and garbage collecting documents as needed.
Note that this means that a cursor does not "contain" the database results, it just manages them. Thus, if you print a cursor (with, say,
var_dump(3) or print_r(3)), you'll just get the cursor object, not your documents. To get the documents themselves, you can use one of the
methods shown above.
CURSOR STAGES
A MongoCursor has two "life stages": pre- and post- query. When a cursor is created, it has not yet contacted the database, so it is in
its pre-query state. In this state, the client can further specify what they want the query to do, including adding limits, skips, sorts,
and more advanced options.
When the client attempts to get a result (by calling MongoCursor.next(3), directly or indirectly), the cursor moves into the post-query
stage. At this point, the query has been executed by the database and cannot be modified anymore.
Example #3
Adding options to MongoCursor
<?php
$cursor = $collection->find()->limit(10);
// database has not yet been queried, so more search options can be added
$cursor = $cursor->sort(array("a" => 1));
var_dump($cursor->getNext());
// now database has been queried and more options cannot be added
// so this will throw an exception:
$cursor->skip(4);
?>
CLASS SYNOPSIS
MongoCursor
MongoCursorMongoCursorInterfaceIterator
Static Fields
o static boolean$slaveOkay FALSE
o static integer$timeout30000
Methods
o public MongoCursor MongoCursor::addOption (string $key, mixed $value)
o public MongoCursor MongoCursor::awaitData ([bool $wait = true])
o public MongoCursor MongoCursor::batchSize (int $batchSize)
o public MongoCursor::__construct (MongoClient $connection, string $ns, [array $query = array()], [array $fields = array()])
o public int MongoCursor::count FALSE ([bool $foundOnly])
o public array MongoCursor::current (void )
o public bool MongoCursor::dead (void )
o protected void MongoCursor::doQuery (void )
o public array MongoCursor::explain (void )
o public MongoCursor MongoCursor::fields (array $f)
o public array MongoCursor::getNext (void )
o public array MongoCursor::getReadPreference (void )
o public bool MongoCursor::hasNext (void )
o public MongoCursor MongoCursor::hint (mixed $index)
o public MongoCursor MongoCursor::immortal ([bool $liveForever = true])
o public array MongoCursor::info (void )
o public string|int MongoCursor::key (void )
o public MongoCursor MongoCursor::limit (int $num)
o public MongoCursor MongoCursor::maxTimeMS (int $ms)
o public array MongoCursor::next (void )
o public MongoCursor MongoCursor::partial ([bool $okay = true])
o public void MongoCursor::reset (void )
o public void MongoCursor::rewind (void )
o public MongoCursor MongoCursor::setFlag (int $flag, [bool $set = true])
o public MongoCursor MongoCursor::setReadPreference (string $read_preference, [array $tags])
o public MongoCursor MongoCursor::skip (int $num)
o public MongoCursor MongoCursor::slaveOkay ([bool $okay = true])
o public MongoCursor MongoCursor::snapshot (void )
o public MongoCursor MongoCursor::sort (array $fields)
o public MongoCursor MongoCursor::tailable ([bool $tail = true])
o public MongoCursor MongoCursor::timeout (int $ms)
o public bool MongoCursor::valid (void )
STATIC VARIABLES
o $slaveOkay
- If the query should have the "slaveOkay" flag set, which allows reads on the secondary (secondaries are, by default, just for
backup and not queried). Can be overridden with MongoCursor.slaveOkay(3). This functionality is deprecated. Please use "Read
Preferences" instead.
o $timeout
- Set timeout in milliseconds for all database responses. Use -1 to wait forever. Can be overridden with MongoCursor.timeout(3).
This does not cause the MongoDB server to cancel the operation; it only instructs the driver to stop waiting for a response and
throw a MongoCursorTimeoutException after a set time.
SEE ALSO
MongoDB core docs on cursors.
PHP Documentation Group MONGOCURSOR(3)