MongoCursor

class MongoCursor implements Iterator (View source)

Result object for database query.

Properties

static bool $slaveOkay
static int $timeout

Methods

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

Create a new cursor

MongoCursor
awaitData(bool $wait = true)

(PECL mongo >= 1.2.11)
Sets whether this cursor will wait for a while for a tailable cursor to return more data

bool
hasNext()

Checks if there are any more elements in this cursor

array
getNext()

Return the next object to which this cursor points, and advance the cursor

array
getReadPreference()

(PECL mongo >= 1.3.3)

MongoCursor
limit(int $num)

Limits the number of results returned

MongoCursor
partial(bool $okay = true)

(PECL mongo >= 1.2.0)

MongoCursor
setFlag(int $flag, bool $set = true)

(PECL mongo >= 1.2.1)

MongoCursor
setReadPreference(string $read_preference, array $tags)

(PECL mongo >= 1.3.3)

MongoCursor
skip(int $num)

Skips a number of results

MongoCursor
slaveOkay(bool $okay = true)

Sets whether this query can be done on a slave This method will override the static class variable slaveOkay.

MongoCursor
tailable(bool $tail = true)

Sets whether this cursor will be left open after fetching the last results

MongoCursor
immortal(bool $liveForever = true)

Sets whether this cursor will timeout

MongoCursor
timeout(int $ms)

Sets a client-side timeout for this query

bool
dead()

Checks if there are documents that have not been sent yet from the database for this cursor

MongoCursor
snapshot()

Use snapshot mode for the query

MongoCursor
sort(array $fields)

Sorts the results by given fields

MongoCursor
hint(mixed $key_pattern)

Gives the database a hint about the query

MongoCursor
addOption(string $key, mixed $value)

Adds a top-level key/value pair to a query

void
doQuery()

Execute the query

mixed
current()

Returns the current element

mixed
key()

Returns the current result's _id

void
next()

Advances the cursor to the next result

void
rewind()

Returns the cursor to the beginning of the result set

bool
valid()

Checks if the cursor is reading a valid result.

void
reset()

Clears the cursor

array
explain()

Return an explanation of the query, often useful for optimization and debugging

int
count(bool $all = false)

Counts the number of results for this query

MongoCursor
fields(array $f)

Sets the fields for a query

array
info()

Gets the query, fields, limit, and skip for this cursor

MongoCursor
batchSize(int $batchSize)

PECL mongo >= 1.0.11 Limits the number of elements returned in one batch.

MongoCursor
maxTimeMS(int $ms)

(PECL mongo >= 1.5.0) Sets a server-side timeout for this query

Details

at line 1316
__construct(MongoClient $connection, string $ns, array $query = [], array $fields = [])

Create a new cursor

Parameters

MongoClient $connection

Database connection.
string $ns

Full name of database and collection.
array $query

Database query.
array $fields

Fields to return.

at line 1324
MongoCursor awaitData(bool $wait = true)

(PECL mongo >= 1.2.11)
Sets whether this cursor will wait for a while for a tailable cursor to return more data

Parameters

bool $wait

[optional]

If the cursor should wait for more data to become available.

Return Value

MongoCursor

Returns this cursor.

at line 1333
bool hasNext()

Checks if there are any more elements in this cursor

Return Value

bool

Returns true if there is another element

Exceptions

MongoConnectionException
MongoCursorTimeoutException

at line 1342
array getNext()

Return the next object to which this cursor points, and advance the cursor

Return Value

array

Returns the next object

Exceptions

MongoConnectionException
MongoCursorTimeoutException

at line 1350
array getReadPreference()

(PECL mongo >= 1.3.3)

Return Value

array

This function returns an array describing the read preference. The array contains the values type for the string read preference mode (corresponding to the https://secure.php.net/manual/en/class.mongoclient.php MongoClient constants), and tagsets containing a list of all tag set criteria. If no tag sets were specified, tagsets will not be present in the array.

at line 1359
MongoCursor limit(int $num)

Limits the number of results returned

Parameters

int $num

The number of results to return.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

at line 1367
MongoCursor partial(bool $okay = true)

(PECL mongo >= 1.2.0)

Parameters

bool $okay

[optional]

If receiving partial results is okay.

Return Value

MongoCursor

Returns this cursor.

at line 1381
MongoCursor setFlag(int $flag, bool $set = true)

(PECL mongo >= 1.2.1)

Parameters

int $flag

Which flag to set. You can not set flag 6 (EXHAUST) as the driver does not know how to handle them. You will get a warning if you try to use this flag. For available flags, please refer to the wire protocol https://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-OPQUERY documentation.

bool $set

[optional]

Whether the flag should be set (TRUE) or unset (FALSE).

Return Value

MongoCursor

at line 1390
MongoCursor setReadPreference(string $read_preference, array $tags)

(PECL mongo >= 1.3.3)

Parameters

string $read_preference

The read preference mode: MongoClient::RP_PRIMARY, MongoClient::RP_PRIMARY_PREFERRED, MongoClient::RP_SECONDARY, MongoClient::RP_SECONDARY_PREFERRED, or MongoClient::RP_NEAREST.
array $tags

[optional]

The read preference mode: MongoClient::RP_PRIMARY, MongoClient::RP_PRIMARY_PREFERRED, MongoClient::RP_SECONDARY, MongoClient::RP_SECONDARY_PREFERRED, or MongoClient::RP_NEAREST.

Return Value

MongoCursor

Returns this cursor.

at line 1399
MongoCursor skip(int $num)

Skips a number of results

Parameters

int $num

The number of results to skip.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

at line 1409
MongoCursor slaveOkay(bool $okay = true)

Sets whether this query can be done on a slave This method will override the static class variable slaveOkay.

Parameters

bool $okay

If it is okay to query the slave.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

at line 1417
MongoCursor tailable(bool $tail = true)

Sets whether this cursor will be left open after fetching the last results

Parameters

bool $tail

If the cursor should be tailable.

Return Value

MongoCursor

Returns this cursor

at line 1426
MongoCursor immortal(bool $liveForever = true)

Sets whether this cursor will timeout

Parameters

bool $liveForever

If the cursor should be immortal.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

at line 1435
MongoCursor timeout(int $ms)

Sets a client-side timeout for this query

Parameters

int $ms

The number of milliseconds for the cursor to wait for a response. By default, the cursor will wait forever.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorTimeoutException

at line 1442
bool dead()

Checks if there are documents that have not been sent yet from the database for this cursor

Return Value

bool

Returns if there are more results that have not been sent to the client, yet.

at line 1450
MongoCursor snapshot()

Use snapshot mode for the query

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

at line 1459
MongoCursor sort(array $fields)

Sorts the results by given fields

Parameters

array $fields

An array of fields by which to sort. Each element in the array has as key the field name, and as value either 1 for ascending sort, or -1 for descending sort

Return Value

MongoCursor

Returns the same cursor that this method was called on

Exceptions

MongoCursorException

at line 1468
MongoCursor hint(mixed $key_pattern)

Gives the database a hint about the query

Parameters

mixed $key_pattern

Indexes to use for the query.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

at line 1478
MongoCursor addOption(string $key, mixed $value)

Adds a top-level key/value pair to a query

Parameters

string $key

Fieldname to add.
mixed $value

Value to add.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

at line 1486
protected void doQuery()

Execute the query

Return Value

void

Exceptions

MongoConnectionException

at line 1493
mixed current()

Returns the current element

Return Value

mixed

Can return any type.

at line 1500
mixed key()

Returns the current result's _id

Return Value

mixed

TKey on success, or null on failure.

at line 1509
void next()

Advances the cursor to the next result

Return Value

void

Any returned value is ignored.

Exceptions

MongoConnectionException
MongoCursorTimeoutException

at line 1517
void rewind()

Returns the cursor to the beginning of the result set

Return Value

void

Any returned value is ignored.

Exceptions

MongoConnectionException
MongoCursorTimeoutException

at line 1524
bool valid()

Checks if the cursor is reading a valid result.

Return Value

bool

The return value will be casted to boolean and then evaluated. Returns true on success or false on failure.

at line 1531
void reset()

Clears the cursor

Return Value

void

at line 1538
array explain()

Return an explanation of the query, often useful for optimization and debugging

Return Value

array

Returns an explanation of the query.

at line 1546
int count(bool $all = false)

Counts the number of results for this query

Parameters

bool $all

Send cursor limit and skip information to the count function, if applicable.

Return Value

int

The number of documents returned by this cursor's query.

at line 1555
MongoCursor fields(array $f)

Sets the fields for a query

Parameters

array $f

Fields to return (or not return).

Return Value

MongoCursor

Exceptions

MongoCursorException

at line 1562
array info()

Gets the query, fields, limit, and skip for this cursor

Return Value

array

The query, fields, limit, and skip for this cursor as an associative array.

at line 1600
MongoCursor batchSize(int $batchSize)

PECL mongo >= 1.0.11 Limits the number of elements returned in one batch.

A cursor typically fetches a batch of result objects and store them locally. This method sets the batchSize value to configure the amount of documents retrieved from the server in one data packet. However, it will never return more documents than fit in the max batch size limit (usually 4MB).

Parameters

int $batchSize

The number of results to return per batch. Each batch requires a round-trip to the server.

If batchSize is 2 or more, it represents the size of each batch of objects retrieved. It can be adjusted to optimize performance and limit data transfer.

If batchSize is 1 or negative, it will limit of number returned documents to the absolute value of batchSize, and the cursor will be closed. For example if batchSize is -10, then the server will return a maximum of 10 documents and as many as can fit in 4MB, then close the cursor.

Warning

A batchSize of 1 is special, and means the same as -1, i.e. a value of 1 makes the cursor only capable of returning one document.

Note that this feature is different from MongoCursor::limit() in that documents must fit within a maximum size, and it removes the need to send a request to close the cursor server-side. The batch size can be changed even after a cursor is iterated, in which case the setting will apply on the next batch retrieval.

This cannot override MongoDB's limit on the amount of data it will return to the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still only return 4-16MB of results per batch).

To ensure consistent behavior, the rules of MongoCursor::batchSize() and MongoCursor::limit() behave a little complex but work "as expected". The rules are: hard limits override soft limits with preference given to MongoCursor::limit() over MongoCursor::batchSize(). After that, whichever is set and lower than the other will take precedence. See below. section for some examples.

Return Value

MongoCursor

Returns this cursor.

at line 1612
MongoCursor maxTimeMS(int $ms)

(PECL mongo >= 1.5.0) Sets a server-side timeout for this query

Parameters

int $ms

Specifies a cumulative time limit in milliseconds to be allowed by the server for processing operations on the cursor.

Return Value

MongoCursor

This cursor.