MongoCursor::batchSize

(PECL mongo >=1.0.11)

MongoCursor::batchSizeОграничивает количество элементов, возвращаемых в одном пакете

Описание

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

Курсор обычно выбирает пакет объектов результатов и сохраняет их локально. Этот метод устанавливает значение batchSize для настройки количества документов, полученных с сервера за один раз. Однако он никогда не вернет больше документов, чем умещается в максимальном размере пакета (обычно 4 МБ).

Список параметров

batchSize

Количество результатов, возвращаемых на пакет. Каждая партия требует отправки на сервер в оба конца.

Если batchSize равен 2 или более, он представляет размер каждой партии извлеченных объектов. Его можно настроить для оптимизации производительности и ограничения передачи данных.

Если batchSize равен 1 или отрицательному значению, он ограничит количество возвращаемых документов абсолютным значением batchSize, и курсор будет закрыт. Например, если batchSize равен -10, сервер вернет максимум 10 документов и столько, сколько может уместиться в 4 МБ, затем закроет курсор.

Внимание

Значение batchSize, равное 1, является специальным и означает то же самое, что и -1, т.е. значение 1 делает курсор способным вернуть только один документ.

Обратите внимание, что эта функция отличается от MongoCursor::limit() тем, что документы должны соответствовать максимальному размеру, и устраняет необходимость отправлять запрос на закрытие курсора на стороне сервера. Размер пакета может быть изменен даже после итерации курсора, и в этом случае настройка будет применяться при следующем получении пакета.

Это не может переопределить ограничение MongoDB на объем данных, которые он возвращает клиенту (т.е. если вы установите размер пакета в 1 000 000 000, MongoDB все равно будет возвращать только 4-16 МБ результатов на пакет).

Чтобы обеспечить согласованное поведение, правила MongoCursor::batchSize() и MongoCursor::limit() ведут себя немного сложнее, но работают "как положено". Правила таковы: жесткие ограничения переопределяют мягкие ограничения, причем MongoCursor::limit() отдается предпочтение над MongoCursor::batchSize(). После этого, тот лимит, который установлен ниже, чем другой, будет приоритетнее. Смотрите ниже раздел с примерами.

Возвращаемые значения

Возвращает курсор.

Примеры

Пример #1 Пример использования MongoCursor::batchSize() в комбинации с MongoCursor::limit()

<?php

// один пакет, максимум 10 штук. -10 заставит сервер 
// вернуть 10 элементов, а затем убрать курсор.
$cursor->limit(20)->batchSize(-10);

// первая партия: не более 10 товаров
$cursor->limit(10);

// первая партия: не более 10 товаров
$cursor->limit(10)->batchSize(20);

// результаты извлекаются партиями по 10 штук в каждой, 
// максимум возвращается 20 товаров (это означает две партии по 10 штук).
$cursor->limit(20)->batchSize(10);

// результаты извлекаются партиями по 7 штук в каждой, 
// максимум возвращается 30 элементов (это означает, что драйвер запрашивает 
// 4 партии по 7 и одну партию из 2).
$cursor->limit(30)->batchSize(7)
?>

Смотрите также

Документация MongoDB по » batchSize.

  • MongoCursor::limit() - Ограничивает количество возвращаемых результатов
  • MongoCursorInterface::batchSize() - Ограничивает количество элементов, возвращаемых в одном пакете

Список изменений

Версия Описание
PECL mongo 1.4.5

До версии 1.4.5 этот метод генерировал исключение MongoCursorException, если курсор уже начал итерацию.