PHP - Manual: MongoCursor

2024-12-22

The MongoCursor class

(PECL mongo >=0.9.0)

简介

A cursor is used to iterate through the results of a database query. For example, to query the database and see all results, you could do:

Example #1 MongoCursor basic usage


<?php

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

?>

You don't generally create cursors using the MongoCursor constructor, you get a new cursor by calling MongoCollection::find() (as shown above).

Suppose that, in the example above, $collection was a 50GB collection. We certainly wouldn't want to load that into memory all at once, which is what a cursor is for: allowing the client to access the collection in dribs and drabs.

If we have a large result set, we can iterate through it, loading a few megabytes of results into memory at a time. For example, we could do:

Example #2 Iterating over MongoCursor


<?php

$cursor = $collection->find();

foreach ($cursor as $doc) {
    // do something to each document
}

?>

This will go through each document in the collection, loading and garbage collecting documents as needed.

Note that this means that a cursor does not "contain" the database results, it just manages them. Thus, if you print a cursor (with, say, var_dump() or print_r()), you'll just get the cursor object, not your documents. To get the documents themselves, you can use one of the methods shown above.

Cursor Stages

A MongoCursor has two "life stages": pre- and post- query. When a cursor is created, it has not yet contacted the database, so it is in its pre-query state. In this state, the client can further specify what they want the query to do, including adding limits, skips, sorts, and more advanced options.

When the client attempts to get a result (by calling MongoCursor::next(), directly or indirectly), the cursor moves into the post-query stage. At this point, the query has been executed by the database and cannot be modified anymore.

Example #3 Adding options to MongoCursor


<?php

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

// database has not yet been queried, so more search options can be added
$cursor = $cursor->sort(array("a" => 1));

var_dump($cursor->getNext());
// now database has been queried and more options cannot be added

// so this will throw an exception:
$cursor->skip(4);
?>

类摘要

MongoCursor implements MongoCursorInterface , Iterator {

/* Static Fields */

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

}

Static Variables

slaveOkay

If the query should have the "slaveOkay" flag set, which allows reads on the secondary (secondaries are, by default, just for backup and not queried). Can be overridden with MongoCursor::slaveOkay().

This functionality is deprecated. Please use 读取首选项 instead.

timeout

Set timeout in milliseconds for all database responses. Use -1 to wait forever. Can be overridden with MongoCursor::timeout(). This does not cause the MongoDB server to cancel the operation; it only instructs the driver to stop waiting for a response and throw a MongoCursorTimeoutException after a set time.

参见

MongoDB core docs on » cursors.

MongoCursor::addOption — Adds a top-level key/value pair to a query
MongoCursor::awaitData — Sets whether this cursor will wait for a while for a tailable cursor to return more data
MongoCursor::batchSize — Limits the number of elements returned in one batch
MongoCursor::__construct — Create a new cursor
MongoCursor::count — Counts the number of results for this query
MongoCursor::current — Returns the current element
MongoCursor::dead — Checks if there are results that have not yet been sent from the database
MongoCursor::doQuery — Execute the query
MongoCursor::explain — Return an explanation of the query, often useful for optimization and debugging
MongoCursor::fields — Sets the fields for a query
MongoCursor::getNext — Advances the cursor to the next result, and returns that result
MongoCursor::getReadPreference — Get the read preference for this query
MongoCursor::hasNext — Checks if there are any more elements in this cursor
MongoCursor::hint — Gives the database a hint about the query
MongoCursor::immortal — Sets whether this cursor will timeout
MongoCursor::info — Gets information about the cursor's creation and iteration
MongoCursor::key — Returns the current result's _id, or its index within the result set
MongoCursor::limit — Limits the number of results returned
MongoCursor::maxTimeMS — Sets a server-side timeout for this query
MongoCursor::next — Advances the cursor to the next result, and returns that result
MongoCursor::partial — If this query should fetch partial results from mongos if a shard is down
MongoCursor::reset — Clears the cursor
MongoCursor::rewind — Returns the cursor to the beginning of the result set
MongoCursor::setFlag — Sets arbitrary flags in case there is no method available the specific flag
MongoCursor::setReadPreference — Set the read preference for this query
MongoCursor::skip — Skips a number of results
MongoCursor::slaveOkay — Sets whether this query can be done on a secondary [deprecated]
MongoCursor::snapshot — Use snapshot mode for the query
MongoCursor::sort — Sorts the results by given fields
MongoCursor::tailable — Sets whether this cursor will be left open after fetching the last results
MongoCursor::timeout — Sets a client-side timeout for this query
MongoCursor::valid — Checks if the cursor is reading a valid result

add a note

User Contributed Notes 4 notes

down

adrian dot zurek at netmedia dot com dot pl ¶

7 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

Adil Baig @ AiDezigns ¶

7 years ago


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

down

alex ¶

1 year ago


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

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

down

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"

add a note

官方地址：https://www.php.net/manual/en/class.mongocursor.php

有任何技术问题请点击这里网站运营推广招聘

IT PHP 编程语言 Linux 开发编程科技 Elasticsearch HTML/CSS/XML 网络数据库 JAVA 面试 NoSQL C/C++ Golang Git 算法操作系统正则表达式 Redis 互联网 MySql JavaScript 运维软件国际架构设计 Mac OS TCP/IP Excel Vim Windows Socket Oracle VR MongoDB Python 运营 MemCache 商业硬件电子娱乐设计 nginx 摄影游戏 WordPress HTTP 团建数码电器

php7 安装fileinfo扩展 preg_split — 通过一个正则表达式分隔字符串 php位值,解决 PHP 中 usort 在值相同时改变原始位置的问题 [PHP] inet_pton/inet_ntop IP地址转换函数 PHP 8.1 [鸟哥]PHP_INT_MIN 和 -9223372036854775808 ADORecordSet对象 adodb手册 opcache预加载 Composer的Packagist资源 array_multisort() 多字段排序 PHPMailer设置utf8 PHPMailer字符集CharSet mysql面试题 PHP json解析（json_decode）页面工具 php中几种注释规范纯php实现DES以及TripleDES加密算法 [鸟哥]PHP FFI详解 - 一种全新的PHP扩展方式 [原创]诡异的php-fpm超时问题两千行PHP学习笔记 PHP5 扩展SOAP 调用 webservice

略微加速

PHP官方手册 - 互联网笔记

The MongoCursor class

简介

Cursor Stages

类摘要

Static Variables

参见

Table of Contents

User Contributed Notes 4 notes