La classe MongoCursor
(PECL mongo >=0.9.0)
Introduction
Un curseur est utiliser pour itérer les résultats d'une requête. Par exemple regarder tous les résultats d'une requête quelconque :
Exemple #1 Utilisation basique de MongoCursor
<?php $cursor = $collection->find(); var_dump(iterator_to_array($cursor)); ?>
En général, vous ne créez pas de MongoCursor en utilisant le constructeur mais en appelant MongoCollection::find() (comme ci-dessus).
Supposons que, dans l'exemple ci-dessus, $collection pèse 50Go. On ne voudra certainement pas tout charger en mémoire, c'est ce que permet un curseur : permettre au client d'accéder aux données au fur et à mesure.
Si nous avons des jeux de résultats très grands, nous pouvons itérer dessus, ceci chargera seulement quelques méga-octets dans la mémoire. Par exemple :
Exemple #2 Parcourt d'un MongoCursor
<?php $cursor = $collection->find(); foreach ($cursor as $doc) { // faire quelque chose avec chaque document $doc } ?>
Notez que cela signifie qu'un curseur ne contient pas les données du jeu de résultats, il ne fait que les piloter. Ainsi si vous affichez un curseur (par exemple, avec var_dump() ou print_r()), vous n'obtiendrez que l'objet curseur, pas les documents. Pour obtenir les documents, vous pouvez utiliser une des techniques ci-dessus.
Etats des curseurs
Un MongoCursor a 2 états différents : Avant et après la requête. Lorsqu'un curseur est crée, il n'a pas encore contacté la base de données, il est en état pré-requête et le client peut toujours préciser ce qu'il attend de la requête, par exemple ajouter des limites, des tris ou encore des options avancées.
Lorsque le client tente de récupérer un résultat (en appelant la fonction MongoCursor::next(), directement ou indirectement), le curseur passe à l'état post-requête. À ce moment-là, la requête a été exécutée par la base et ne peut plus être modifiée.
Exemple #3 Ajout d'options à MongoCursor
<?php $cursor = $collection->find()->limit(10); // la base n'a pas encore été interrogée, // il est donc encore temps d'ajouter des options $cursor = $cursor->sort(array("a" => 1)); var_dump($cursor->getNext()); // maintenant, la base a été interrogée, et les options ne sont plus prises en compte // Cet commnande va produire une exception : $cursor->skip(4); ?>
Synopsis de la classe
$connection
, string $ns
[, array $query
= array()
[, array $fields
= array()
]] )Variables statiques
- slaveOkay
-
Est ce que la requête doit avoir le drapeau "slaveOkay" activé, ce qui permet des lectures sur le secondaire (les secondaires sont par défaut déstinés à des sauvegardes et donc inaccessibles en lectures). Peut être surchargé avec MongoCursor::slaveOkay().
Cette fonctionalité est obsolète. Veuillez utiliser Préférences de lecture à la place.
- timeout
-
Affecte le timeout en millisecondes pour les réponses des bases de données. Pour un timeout infini, utilisez -1. Peut être surchargé avec MongoCursor::timeout(). Ceci ne provoque pas une annulation de l'opération par le serveur MongoDB mais fait en sorte que le pilote s'arrête d'attendre une réponse et envoie une exception MongoCursorTimeoutException.
Voir aussi
Documentation de MongoDB » concernant les curseurs.
Sommaire
- MongoCursor::addOption — Ajoute une paire clé/valeur de haut niveau à la requête
- MongoCursor::awaitData — Définit si le curseur doit attendre un curseur tailable pour retourner plus de données
- MongoCursor::batchSize — Limite le nombre de résultats retourné pour un lot
- MongoCursor::__construct — Crée un nouveau curseur
- MongoCursor::count — Compte le nombre de résultats pour cette requête
- MongoCursor::current — Retourne l'élément courant
- MongoCursor::dead — Vérifie s'il reste des documents non envoyés à la base de données pour ce curseur
- MongoCursor::doQuery — Exécute la requête Mongo
- MongoCursor::explain — Retourne une explication de la requête, souvent utile pour le déboguage et l'optimisation
- MongoCursor::fields — Définit les champs d'une requête
- MongoCursor::getNext — Retourne le prochain objet et avance le curseur
- MongoCursor::getReadPreference — Récupère les préférences de lecture pour cette requête
- MongoCursor::hasNext — Vérifie s'il y a encore des éléments pour ce curseur
- MongoCursor::hint — Donne des indications à la base de données pour la requête
- MongoCursor::immortal — Définit si le curseur doit s'interrompre après un certain délai
- MongoCursor::info — Récupère la requête, les champs, la limite et les exceptions de ce curseur
- MongoCursor::key — Retourne l'identifiant du résultat courant
- MongoCursor::limit — Limite le nombre de résultats retournés
- MongoCursor::next — Avance le curseur au prochain résultat
- MongoCursor::partial — Si la requête doit récupérer des résultats partiels depuis mongos si un partage est inaccessible
- MongoCursor::reset — Efface le curseur
- MongoCursor::rewind — Retourne le curseur au début du jeu de résultats
- MongoCursor::setFlag — Définit des drapeaux dans le cas où aucune méthode dédiée n'est disponible
- MongoCursor::setReadPreference — Définit les préférences de lecture pour cette requête
- MongoCursor::skip — Omet les premiers résultats
- MongoCursor::slaveOkay — Définit si la requête peut être effectuée sur un serveur secondaire
- MongoCursor::snapshot — Utilise le mode de capture pour la requête
- MongoCursor::sort — Trie les résultats par ordre de champs
- MongoCursor::tailable — Définit si le curseur doit être conservé ouvert après la récupération du dernier résultat
- MongoCursor::timeout — Définit un délai maximum d'attente côté client pour cette requête
- MongoCursor::valid — Vérifie si le curseur lit un résultat valide