PHP: MongoCursor::batchSize

Description

public MongoCursor::batchSize ( int $batchSize ) : MongoCursor

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).

Liste de paramètres

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é.

Avertissement

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.

Valeurs de retour

Retourne ce curseur.

Exemples

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)
?>

Voir aussi

La documentation coeur de MongoDB sur la fonction » batchSize.

MongoCursor::limit() - Limite le nombre de résultats retournés
MongoCursorInterface::batchSize() - Limite le nombre d'éléments retourné dans un lot

Historique

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.

MongoCursor::batchSize