PHP 7.4.0RC6 Released!

Класс 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 add a note

User Contributed Notes 4 notes

up
9
adrian dot zurek at netmedia dot com dot pl
8 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!
up
2
alex
2 years ago
Deprecated:
$cursor = $collection->find();
$cursor->limit(1);

Use instead:
$collection->find([], [ 'limit' => 1 ]);
up
1
Adil Baig @ AiDezigns
8 years ago
If you want to know whether a cursor returned any results it is faster to use 'hasNext()' than 'count'
up
0
Adil Baig
4 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"
To Top