# Préférences de lecture

MongoDB 2.2 et la version 1.3.0 du driver ajoutent le support pour les » préférences de lecture, qui autorise le contrôle sur la façon dont les requêtes sont dirigées vers les instances mongod dans un environnement de jeux de réplication. Les préférences de lecture peuvent être spécifiées soit pour chaque connexion, soit par base de données, soit par collection. Les préférences définies à un niveau plus élévé seront héritées par défaut (i.e. MongoCollection héritera des préférences définies au niveau correspondant de l'instance MongoDB).

Les préférences de lecture sont spécifiées avec des combinaison de modes et de jeu de tags. Les modes déterminent la façon dont les instances mongod sont priorisées, alors que les » jeux de tags spécifient les critères d'éligibilité des instances mongod. Les instances Mongod ne sont éligibles que si le temps du ping n'excède pas une différence de 15 ms depuis l'instance mongod la plus proche.

### Les modes des préférences de lecture

Avertissement

Tous les modes des préférences de lecture, excepté MongoClient::RP_PRIMARY peuvent retourner des données périmées sachant que les opérations de réplication des secondaires depuis le primaire peuvent prendre un certain délai. Assurez-vous que votre application peut toléler des données périmées si vous choisissez d'utiliser un mode autre que le mode MongoClient::RP_PRIMARY.

- MongoClient::RP_PRIMARY

  Toutes les opérations de lecture n'utilisent que le jeu primaire de réplication courant. C'est le comportement par défaut. Si le primaire n'est pas disponible, les opérations de lecture produiront une exception.

  Ce mode est incompatible avec l'utilisation des jeux de tags. Le fait de spécifier un jeu de tags avec le mode MongoClient::RP_PRIMARY retournera une exception.

- MongoClient::RP_PRIMARY_PREFERRED

  Dans la plupart des situations, les opérations de lecture s'effectuent depuis le membre primaire du jeu. Cependant, si le primaire n'est pas disponible, ce qui est le cas lors des situations critiques, les opérations de lecture s'effectuent depuis les membres secondaires.

  Lorsque les préférences de lecture incluent un jeu de tags, le client lit tout d'abord en utilisant le primaire, s'il est disponible, puis, en utilisant les secondaires qui correspondent aux tags spécifiés. Si aucun secondaire ne correspond aux tags spécifiés, l'opération de lecture échoue et produit une exception.

  Avertissement

  La version 2.2 de mongo ajoute un support complet des préférences de lecture. Lors de la connexion à d'anciennes instances mongo, MongoClient::RP_PRIMARY_PREFERRED enverra les requêtes aux secondaires.

- MongoClient::RP_SECONDARY

  Les opérations de lecture ne s'effectuent que sur les membres secondaires du jeu. Si aucun secondaire n'est disponible, les opérations de lecture produiront une exception.

  La plupart des jeux ont au moins un secondaire, mais il existe des situations où il peut ne pas être disponible. Par exemple, un jeu avec un primaire, un secondaire, un arbitraire peut ne pas avoir de secondaire si un membre est en cours de récupération ou indisponible.

  Lorsque les préférences de lecture incluent un jeu de tags, le client tente de trouver des membres secondaires qui correspondent au jeu de tags spécifié, et dirige les lectures vers un secondaire pris aléatoirement dans le groupe le plus proche. Si aucun secondaire ne correspond aux tags, l'opération de lecture produira une exception.

- MongoClient::RP_SECONDARY_PREFERRED

  Dans la plupart des situations, les opérations de lecture s'effectuent sur les membres secondaires, mais dans le cas où le jeu contient un seul primaire avec aucun autre membre, l'opération de lecture utilisera le primaire du jeu.

  Lorsque les préférences de lecture incluent un jeu de tags, le client tente de trouver un membre secondaire qui correspond au jeu de tags spécifié, et dirige les lectures vers un secondaire pris aléatoirement dans la groupe le plus proche. Si aucun secondaire ne correspond aux tags, l'opération de lecture produira une exception.

- MongoClient::RP_NEAREST

  Le driver lit depuis un membre aléatoire du jeu, qui a un ping inférieur à 15ms du membre avec le ping le plus bas. Une lecture en mode MongoClient::RP_NEAREST ne prend pas en compte le type du membre, et peut lire depuis les primaires mais aussi depuis les secondaires.

  Utilisez ce mode pour minimiser les effects de latence du réseau lors des opérations de lecture sans préférence pour des données courantes ou périmées.

  Si vous spécifiez un jeu de tags, le client tente de trouver un membre qui correspond au jeu de tags spécifié et dirige les lectures vers un noeud pris aléatoirement depuis le groupe le plus proche.

  > Note:

  > Toutes les opérations lisent depuis le membre le plus proche du jeu de réplication qui correspond au mode de préférence de lecture spécifié. Le mode MongoClient::RP_NEAREST préfère les faibles latences lors des lectures sur les membres au statut primaire ou secondaire.

### Jeux de tags

Les » jeux de tags vous permettent de spécifier des critères indiquant à votre application les membres spécifiques à utiliser lors des opérations de lecture, en se basant sur des paramètres personnalisés. Les jeux de tags permettent cela, permettant ainsi de s'assurer que les opérations de lecture utilisent des membres d'un centre de données particulier, ou utilisent des instances mongod désignées pour une classe particulière d'opérations, comme les rapports ou les analyses.

Vous pouvez spécifier des jeux de tags avec les modes de préférence de lecture suivants :

- MongoClient::RP_PRIMARY_PREFERRED

- MongoClient::RP_SECONDARY

- MongoClient::RP_SECONDARY_PREFERRED

- MongoClient::RP_NEAREST

Vous ne pouvez pas spécifier de jeux de tags avec le mode de préférence de lecture MongoClient::RP_PRIMARY. Les tags sont applicables que lors de la sélection d'un membre secondaire d'un jeu, excepté lors du mode utilisant le plus proche.

### Spécifier les préférences de lecture

Les préférences de lecture peuvent être spécifiées dans l'URI de connexion fourni à la méthode MongoClient::__construct(), qui utilise une syntaxe de type requête, ou via des méthodes du coeur de la classe, qui utilise un tableau pour spécifier les jeux de tags.

Lorsque les modes de préférences de lecture sont fournis via une chaîne de type requête, les jeux de tags pour la valeur de readPreferenceTags doivent être une séquence délimitée par une virgule de paires clé/valeur séparée par deux points(:).

> Note:

> Chaque jeu de tags défini dans la chaîne de requête utilisera le nom readPreferenceTags. Contrairement à la façon dont PHP gère les chaînes de type URL, les valeurs successives de readPreferenceTags n'effaceront pas les précédentes. Le driver va collecter les jeux de tags dans l'ordre de leur apparition dans la chaîne de requête.

Avertissement

Si le driver ne trouve pas de jeu de tags correspondant, la lecture échoue ! Il en est de votre responsabilité que de fournir un fallback valide, comme une valeur vide pour readPreferenceTags qui voudra dire "aucun jeu de tags de préférence".

Exemple #1 Préférences de lecture via l'URI de connexion avec une syntaxe de type requête

`<?php
// Préfère le serveur le plus proche avec aucun tag de préférence
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
// Sélectionne le serveur le plus proche dans le centre de données "east"
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
// Préfère le serveur le plus proche dans le centre de données "east", également
// utilisé pour les rapports, mais utilise le centre de données "west" en cas de problème
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east,use:reporting';
$uri .= '&readPreferenceTags=dc:west';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
// Préfère le serveur le plus proche dans le centre de données "east", puis, un
// serveur dans le centre de données "west", et pour terminer, n'avoir aucun
jeu de tags de préférence si une erreur survient
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$uri .= '&readPreferenceTags=dc:west';
$uri .= '&readPreferenceTags=';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
?>`

Exemple #2 Préférences de lecture avec une syntaxe de type tableau pour les jeux de tags

`<?php
$m = new Mongo('mongodb://rs1.example.com,rs2.example.com', array(
'replicaSet' => 'rs',
));
// Préfère le serveur le plus proche, avec aucun tag de préférence
$m->setReadPreference(MongoClient::RP_NEAREST, array());
// Sélectionne le serveur le plus proche dans le centre de données "east"
$m->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east'),
));
// Préfère le serveur le plus proche dans le centre de données "east" également
// utilisé pour les rapports, mais prend un serveur du centre de données "west"
// en cas d'erreur
$m->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
// Préfère le serveur le plus proche dans le centre de données "east", puis un
// serveur dans le centre de données "west", et pour terminer, n'avoir aucun
jeu de tags de préférence si une erreur survient
$m->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east'),
array('dc' => 'west'),
array(),
));
?>`