Класс MongoCursor

(PECL mongo >=0.9.0)

Введение

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

Пример #1 Пример использования MongoCursor


<?php

$cursor = $collection->find();
var_dump(iterator_to_array($cursor));

?>

Обычно курсоры не создаются с помощью конструктора MongoCursor. Вы получаете новый курсор, вызывая MongoCollection::find() (как показано выше).

Предположим, что в приведенном выше примере $collection была коллекцией 50 Гб. Мы, конечно, не хотим загружать все сразу в память, для этого нужен курсор: позволить клиенту получить доступ к коллекции по частям.

Если у нас большой набор результатов, мы можем выполнить итерацию, загружая несколько мегабайт результатов в память за раз. Например, мы могли бы сделать:

Пример #2 Итерации MongoCursor


<?php

$cursor = $collection->find();

foreach ($cursor as $doc) {
    // делаем что-нибудь с каждым документом
}

?>

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

Обратите внимание, это означает, что курсор не содержит результаты базы данных, он просто управляет ими. Таким образом, если вы печатаете курсор (скажем, с помощью var_dump() или print_r()), вы просто получите объект курсора, а не документы. Чтобы получить сами документы, вы можете использовать один из способов, показанных выше.

Стадии курсора

MongoCursor имеет две "жизненные стадии": до и после выполнения запроса. Когда курсор создан, он еще не связался с базой данных, поэтому он находится в состоянии перед выполнением запроса. В этом состоянии клиент может дополнительно указать, что он хочет сделать запросом, включая добавление ограничений, пропусков, сортировок и более сложных параметров.

Когда клиент пытается получить результат (вызывая MongoCursor::next(), прямо или косвенно), курсор перемещается в стадию после выполнения запроса. На данный момент запрос был выполнен базой данных и больше не может быть изменен.

Пример #3 Добавление параметров в MongoCursor


<?php

$cursor = $collection->find()->limit(10);

// База данных еще не опрошена, поэтому можно добавить дополнительные параметры поиска
$cursor = $cursor->sort(array("a" => 1));

var_dump($cursor->getNext());
// теперь база данных была опрошена и больше опций не может быть добавлено

// так что это вызовет исключение:
$cursor->skip(4);
?>

Обзор классов

MongoCursor implements MongoCursorInterface , Iterator {

/* Статичные поля */

static boolean slaveOkay = FALSE ;

static integer timeout = 30000 ;

/* Методы */

public addOption ( string $key , mixed $value ) : MongoCursor

public awaitData ([ bool $wait = TRUE ] ) : MongoCursor

public batchSize ( int $batchSize ) : MongoCursor

public __construct ( MongoClient $connection , string $ns [, array $query = array() [, array $fields = array() ]] )

public count ([ bool $foundOnly = FALSE ] ) : int

public current ( void ) : array

public dead ( void ) : bool

protected doQuery ( void ) : void

public explain ( void ) : array

public fields ( array $f ) : MongoCursor

public getNext ( void ) : array

public getReadPreference ( void ) : array

public hasNext ( void ) : bool

public hint ( mixed $index ) : MongoCursor

public immortal ([ bool $liveForever = TRUE ] ) : MongoCursor

public info ( void ) : array

public key ( void ) : string|int

public limit ( int $num ) : MongoCursor

public maxTimeMS ( int $ms ) : MongoCursor

public next ( void ) : array

public partial ([ bool $okay = TRUE ] ) : MongoCursor

public reset ( void ) : void

public rewind ( void ) : void

public setFlag ( int $flag [, bool $set = TRUE ] ) : MongoCursor

public setReadPreference ( string $read_preference [, array $tags ] ) : MongoCursor

public skip ( int $num ) : MongoCursor

public slaveOkay ([ bool $okay = TRUE ] ) : MongoCursor

public snapshot ( void ) : MongoCursor

public sort ( array $fields ) : MongoCursor

public tailable ([ bool $tail = TRUE ] ) : MongoCursor

public timeout ( int $ms ) : MongoCursor

public valid ( void ) : bool

}

Статические переменные

slaveOkay

Установленный в запросе флаг "slaveOkay", позволяет выполнять чтение на вторичном сервере (вторичные по умолчанию предназначены только для резервного копирования и не запрашиваются). Может быть переопределен с помощью MongoCursor::slaveOkay().

Эта функциональность устарела. Пожалуйста, используйте вместо этого Предпочтения чтения.

timeout

Установите время ожидания в миллисекундах для ответов базы данных. Используйте -1, чтобы ждать вечно. Может быть переопределено с помощью MongoCursor::timeout(). Не приводит к тому, что сервер MongoDB отменяет операцию; только к указанию драйверу прекратить ждать ответа и выдать исключение MongoCursorTimeoutException по истечении заданного времени.

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

Для получения дополнительной информации о курсорах в MongoDB смотрите » документацию.

Содержание

MongoCursor::addOption — Добавляет пару ключ/значение верхнего уровня в запрос
MongoCursor::awaitData — Устанавливает, будет ли этот курсор некоторое время ждать, пока настраиваемый курсор вернет больше данных
MongoCursor::batchSize — Ограничивает количество элементов, возвращаемых в одном пакете
MongoCursor::__construct — Создает новый курсор
MongoCursor::count — Подсчитывает количество результатов для запроса
MongoCursor::current — Возвращает текущий элемент
MongoCursor::dead — Проверяет, есть ли результаты, которые еще не были отправлены из базы данных
MongoCursor::doQuery — Выполняет запрос
MongoCursor::explain — Возвращает объяснение запроса, часто полезное для оптимизации и отладки
MongoCursor::fields — Устанавливает поля для запроса
MongoCursor::getNext — Перемещает курсор к следующему результату и возвращает этот результат
MongoCursor::getReadPreference — Получает предпочтения чтения для запроса
MongoCursor::hasNext — Проверяет, есть ли еще элементы в этом курсоре
MongoCursor::hint — Дает базе данных подсказку о запросе
MongoCursor::immortal — Устанавливает, будет ли курсор отключен
MongoCursor::info — Получает информацию о создании и итерации курсора
MongoCursor::key — Возвращает _id текущего результата или его индекс в наборе результатов
MongoCursor::limit — Ограничивает количество возвращаемых результатов
MongoCursor::maxTimeMS — Устанавливает время ожидания на стороне сервера для этого запроса
MongoCursor::next — Перемещает курсор к следующему результату и возвращает этот результат
MongoCursor::partial — Если этот запрос должен получить частичные результаты от mongos, если шард недоступен
MongoCursor::reset — Очищает курсор
MongoCursor::rewind — Возвращает курсор в начало набора результатов
MongoCursor::setFlag — Устанавливает произвольные флаги, если нет метода, доступного конкретному флагу
MongoCursor::setReadPreference — Устанавливает предпочтения чтения для запроса
MongoCursor::skip — Пропускает ряд результатов
MongoCursor::slaveOkay — Устанавливает, может ли этот запрос быть выполнен на вторичном сервере [устарел]
MongoCursor::snapshot — Использует режим снимка для запроса
MongoCursor::sort — Сортирует результаты по заданным полям
MongoCursor::tailable — Устанавливает, останется ли этот курсор открытым после извлечения последних результатов
MongoCursor::timeout — Устанавливает время ожидания на стороне клиента для запроса
MongoCursor::valid — Проверяет, читает ли курсор правильный результат

add a note

User Contributed Notes 4 notes

down

adrian dot zurek at netmedia dot com dot pl ¶

13 years ago


One *VERY* important note, if You do:
$cursor = $collection->find(array(), array('_id' => 0)); // ommit '_id' field in result 

then:
var_dump(iterator_to_array($cursor));

will return only *ONE* document, not all!

down

alex ¶

7 years ago


Deprecated:
$cursor = $collection->find();
$cursor->limit(1);

Use instead:
$collection->find([], [ 'limit' => 1 ]);

down

Adil Baig @ AiDezigns ¶

13 years ago


If you want to know whether a cursor returned any results it is faster to use 'hasNext()' than 'count'

down

Adil Baig ¶

9 years ago


The documentation says $timeout is a static variable that can be set:

"Set timeout in milliseconds for all database responses."

This feature has been deprecated. Attempting to set it will result in a warning :

"PHP Deprecated:  MongoCollection::find(): The 'MongoCursor::$timeout' static property is deprecated, please call MongoCursor->timeout() instead"

add a note