From 7d96d2a7f7195a6b1114e723d4520714f0fa16b2 Mon Sep 17 00:00:00 2001 From: Hannes Magnusson Date: Wed, 28 Nov 2012 23:25:17 +0000 Subject: [PATCH] More Read Preferences love git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328549 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongo/queries.xml | 268 ++++++++++++++++++---------- reference/mongo/readpreferences.xml | 12 +- 2 files changed, 179 insertions(+), 101 deletions(-) diff --git a/reference/mongo/queries.xml b/reference/mongo/queries.xml index a232f27ca1..32024066e5 100644 --- a/reference/mongo/queries.xml +++ b/reference/mongo/queries.xml @@ -3,51 +3,52 @@ Querying -
+ Distributing queries to secondaries - - 1.1.0+ - - If you are using a - replica set and version - 1.1.0 or above of the driver, the driver can automatically route reads to - secondaries. This behavior does not exist in earlier versions of the driver - and cannot be used with legacy master-slave clusters. - - - - By default, the driver will send all queries to the primary. If you set the - "slaveOkay" option, the driver will send read queries to a secondary server, - if possible. The "slaveOkay" option can be set at every "level": - connection, - database, - collection, and - cursor. Each class inherits the - "slaveOkay" setting from the class above it, so if you do: + All queries (reads and writes) are only sent to the primary member of a + ReplicaSet by default. This is however easily configurable by using the + Read Preferences which allow + you to set some generic read preferences (such as allowing secondary reads + of the nearest server), and also provide ways to specifically target a + server in a specific country, datacenter, or even hardware, by the use of + ReplicaSet TagSets. - - + + Read Preferences can be configured at "every level" + + As a query parameter, or option, to MongoClient::__construct + Specifically by calling MongoClient::setReadPreference + At the Database level with MongoDB::setReadPreference + At the Collection level with MongoCollection::setReadPreference + At the Cursor level with MongoCursor::setReadPreference + + Each class inherits the Read Preference setting from the class above it, so if you do: + + + Inheriting ReadPreferences from the Database level down to the Cursor + setSlaveOkay(true); +$db->setReadPreference(MongoClient::RP_SECONDARY_PREFERRED); $c = $db->myCollection; $cursor = $c->find(); ?> ]]> - - + + then the query will be executed against a secondary (the collection inherited - "slaveOkay" from the database and the cursor inherited it from the + MongoClient::RP_SECONDARY_PREFERRED from the database and the cursor inherited it from the collection). + -
+ How secondaries are chosen @@ -56,84 +57,106 @@ $cursor = $c->find(); had a PHP client in Europe and one in Australia and we had one secondary in each of these data centers, we could do: - + + "setName", "readPreference" => MongoClient::RP_SECONDARY_PREFERRED); -// P is the primary // on the Australian client -$m1 = new MongoClient("mongodb://P", array("replicaSet" => 'setName')); -$m1->foo->bar->find()->slaveOkay()->getNext(); -echo "m1's secondary is ".$m1->getSlave()."\n"; +$m = new MongoClient("mongodb://primary,australianhost.secondary,europeanhost.secondary", $options); +$cursor = $m->foo->bar->find(); +$cursor->getNext(); +echo "Reading from: ", $cursor->info()["server"], "\n"; // on the European client -$m2 = new MongoClient("mongodb://P", array("replicaSet" => 'setName')); -$m2->foo->bar->find()->slaveOkay()->getNext(); -echo "m2's secondary is ".$m2->getSlave()."\n"; +$m = new MongoClient("mongodb://primary,australianhost.secondary,europeanhost.secondary", $options); +$cursor = $m->foo->bar->find(); +$cursor->getNext(); +echo "Reading from: ", $cursor->info()["server"], "\n"; ?> ]]> - - - we'd probably end up with something like: - - -m1's secondary is: australianHost -m2's secondary is: europeanHost - + + &example.outputs.similar; + + + + + Note that we have to do a query before a secondary is chosen: secondaries + are chosen lazily by the driver. + + - - Note that we have to do a query before a secondary is chosen: secondaries - are chosen lazily by the driver. Mongo::getSlave will - return &null; until a secondary is used. - You can see what the driver thinks is the current status of the set members - by running MongoClient::getHosts. + by running MongoClient::getHosts or + MongoClient::getConnections. - If no non-primary server is readable, the driver will send - reads to the primary (even if "slaveOkay" is set). A server is considered - readable if its state is 2 (SECONDARY) and its health is 1. You can check - this with MongoClient::getHosts. + If no secondary is readable, the driver will send reads to the + primary as we specified + MongoClient::RP_SECONDARY_PREFERRED which will + fallback to execute a query on a primary if no secondaries are available. + A server is considered readable if its state is 2 (SECONDARY) and its + health is 1. You can check this with + MongoClient::getHosts and + MongoClient::getConnections. - - If you enjoy twiddling knobs that you probably shouldn't mess with, you can - request the driver to use a different secondary by calling - Mongo::switchSlave. This may choose a new secondary - (if one is available) and shouldn't be used unless you know what you're - doing. - - -
-
+ + Random notes - Writes are always sent to the primary. Database commands, even read-only - commands, are also always sent to the primary. + Writes are always sent to the primary - and by default all reads are sent + to the primary too. + + + The following database commands can be sent to secondaries when using the + apropriate Read Preference: + + MongoCollection::group + MongoCollection::aggregate + MongoCollection::distinct + MongoCursor::count + collStats + dbStats + geoNear + geoSearch + geoWalk + inline mapreduce + + All other commands are always sent to the primary. - The health and state of a secondary is checked every 5 seconds or when the - next operation occurs after 5 seconds. It will also recheck the - configuration when the driver has a problem reaching a server. + The health and state of a secondary is checked every 5 seconds + (configurable with + mongo.ping_interval) + or when the next operation occurs after 5 seconds. It will also recheck + the configuration when the driver has a problem reaching a server. + + + ReplicaSet failovers are checked every 60seconds (configurable with + mongo.is_master_interval), + and whenever a write operation fails when using acknowledged writes. - Note that a non-primary server may be behind the primary in operations, so - your application must be okay with getting out-of-date data (or you must use - w for all writes). + Note that secondaries may be behind the primary in operations, so + your application must be okay with getting out-of-date data when using + Read Preferences other then MongoClient::RP_PRIMARY. -
+ -
- -
+ Querying by _id Every object inserted is automatically assigned a unique _id field, which is @@ -143,7 +166,8 @@ m2's secondary is: europeanHost Suppose that we wish to find the document we just inserted. Inserting adds and _id field to the document, so we can query by that: - + + findOne(array("_id" => $person['_id'])); ?> ]]> - + + Unless the user has specified otherwise, the _id field is a - MongoId. The most common mistake is attepting to use + MongoId. The most common mistake is attempting to use a string to match a MongoId. Keep in mind that these are two different datatypes, and will not match each other in the same way that the string "array()" is not the same as an empty array. For example: - + + findOne(array("_id" => $pid)); ?> ]]> - + + -
+ -
+ Arrays @@ -201,7 +228,8 @@ $joe = $people->findOne(array("_id" => $pid)); say: - + + save(array("awards" => array("gold", "silver", "bronze"))); ?> ]]> - + + Queries can reach into arrays to search for elements. Suppose that we wish @@ -217,18 +246,19 @@ $collection->save(array("awards" => array("gold", "silver", "bronze"))); documents with a "gold" award, such as: - + - + This can be done with a simple query, ignoring the fact that "awards" is an array: - + + save(array("awards" => array("gold", "silver", "bronze"))); ?> ]]> - + + Suppose we are querying for a more complex object, if each element of the array were an object itself, such as: - + save(array("awards" => array("gold", "silver", "bronze"))); ] } ]]> - + Still ignoring that this is an array, we can use dot notation to query the subobject: - + + find(array("awards.first place" => "gold")); ?> ]]> - + + Notice that it doesn't matter that there is a space in the field name @@ -289,7 +322,8 @@ $cursor = $collection->find(array("awards.first place" => "gold")); instance, if we were looking for documents "gold" or "copper", we could do: - + + find(array("awards" => array('$in' => array("gold", "copp ?> ]]> - + + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 1.3.1 + + Several database commands can now be executed on secondaries. + + + + 1.3.0 + + Introduced the Read + Preferences framework to allow more fine grained controlled over + secondary reads. + + + + 1.3.0 + + Deprecated slaveOkay usage. + + + + 1.1.0 + + Introduced the possiblity of routing reads to secondaries of ReplicaSet + members using Mongo::setSlaveOkay + + + + + + -