(PECL mongo >=1.0.11)
MongoCursor::batchSize — Limite le nombre de résultats retourné pour un lot
Un curseur récupère un lot d'objets de résultats et les stocke en local. Cette méthode définit la valeur batchSize permettant de configurer la quantité de documents à récupérer en un passage, depuis le serveur. Cependant, la quantité de documents retournée ne pourra jamais être supérieure à la limite maximale (habituellement 4 Mo).
batchSize
Le nombre de résultats à retourner pour un lot. Chaque lot nécessite un aller-retour avec le serveur.
Si batchSize vaut 2 ou plus,
il représentera la taille de chaque lot d'objets récupérés.
Il peut être ajuster pour optimiser les performances et limiter les
données transférées.
Si batchSize vaut 1 ou une
valeur négative, cela va limiter le nombre de documents retournés à la
valeur absolue de batchSize, et le curseur sera fermé. Par exemple,
si batchSize vaut -10, alors le serveur retournera
un maximum de 10 documents (si ces documents tiennent dans 4Mo), puis
le curseur sera fermé.
Le fait de définir batchSize à 1
est spécial, et signifie la même chose que de le définir à
-1, i.e. une valeur de 1 rend le
curseur capable de ne retourner d'un seul document.
Notez que cette fonctionalité est différente de la méthode MongoCursor::limit() car les documents doivent tenir dans une taille maximale, et elle supprime la nécessité d'envoyer une requête pour fermer le curseur côté serveur. La taille du lot peut être changée après l'itération d'un curseur, au quel cas la configuration sera appliquée lorsque le prochain lot sera récupéré.
Cette méthode ne peut pas écraser la limite MongoDB de la quantité de données à retourner au client (i.e., si vous définissez la taille du lot à 1.000.000.000, MongoDB continuera de retourner uniquement 4-16Mo de résultats par lot).
Afin d'assurer un comportement consistent, les règles de MongoCursor::batchSize() et MongoCursor::limit() sont assez complexes mais fonctionnent "comme attendues". Les règles sont : les limites dures écrasent les limites légères avec une préférence donnée à la méthode MongoCursor::limit() sur la méthode MongoCursor::batchSize(). Après cela, tout ce qui est défini et est inférieure à ce qui précède prendra le dessus ; voir ci-dessous pour plus d'exemples.
Retourne ce curseur.
Exemple #1 Exemple avec MongoCursor::batchSize() et des combinaisons avec la fonction MongoCursor::limit()
<?php
// un lot, au maximum de 10 éléments. Le -10 fera que le serveur retournera 10 éléments,
// puis, fermera le curseur.
$cursor->limit(20)->batchSize(-10);
// premier lot : un maximum de 10 éléments
$cursor->limit(10);
// premier lot : un maximum de 10 éléments
$cursor->limit(10)->batchSize(20);
// Les résultats sont récupérés en lot de 10 éléments, avec un maximum de 20 éléments
// retournés (cela signifie deux lots de 10).
$cursor->limit(20)->batchSize(10);
// Les résultats sont récupérés en lot de 7 éléments, avec un maximum de 30 éléments
// retournés (cela signifie que le driver demandera 4 lots de 7 éléments, et un lot
// de 2).
$cursor->limit(30)->batchSize(7)
?>
La documentation coeur de MongoDB sur la fonction » batchSize.
| Version | Description |
|---|---|
| 1.4.5 |
Avant la version 1.4.5, cette méthode lançait une exception de type MongoCursorException si le curseur avait déjà commencé son itération. |