MongoDB::Cursor - A lazy cursor for Mongo query results
version v0.999.998.3
while (my $object = $cursor->next) { ... } my @objects = $cursor->all;
Cursors are cloned in threads, but not reset. Iterating the same cursor from multiple threads will give unpredictable results. Only iterate from a single thread.
If this cursor has queried the database yet. Methods modifying the query will complain if they are called after the database is queried.
$MongoDB::Cursor::slave_okay = 1;
Whether it is okay to run queries on the slave. Defaults to 0.
Deprecated, use MongoDB::MongoClient::query_timeout instead.
How many milliseconds to wait for a response from the server. Set to 30000 (30 seconds) by default. -1 waits forever (or until TCP times out, which is usually a long time).
This value is overridden by MongoDB::MongoClient::query_timeout and never used.
MongoDB::MongoClient::query_timeout
These methods modify the query to be run. An exception will be thrown if they are called after results are iterated.
$cursor->immortal(1);
Ordinarily, a cursor "dies" on the database server after a certain length of time (approximately 10 minutes), to prevent inactive cursors from hogging resources. This option sets that a cursor should not die until all of its results have been fetched or it goes out of scope in Perl.
Boolean value, defaults to 0.
immortal is not equivalent to setting a client-side timeout. If you are getting client-side timeouts (e.g., "recv timed out"), set query_timeout on your connection.
immortal
query_timeout
# wait forever for a query to return results $connection->query_timeout(-1);
See "query_timeout" in MongoDB::MongoClient.
Returns this cursor for chaining operations.
$coll->insert({name => "Fred", age => 20}); my $cursor = $coll->find->fields({ name => 1 }); my $obj = $cursor->next; $obj->{name}; "Fred" $obj->{age}; # undef
Selects which fields are returned. The default is all fields. When fields are specified, _id is returned by default, but this can be disabled by explicitly setting it to "0". E.g. _id => 0. Argument is either a hash reference, a Tie::IxHash or an array reference of key/value pairs.
_id => 0
See Limit fields to return in the MongoDB documentation for details.
# sort by name, descending $cursor->sort([name => -1]);
Adds a sort to the query. Argument is either a hash reference or a Tie::IxHash or an array reference of key/value pairs. Because hash references are not ordered, do not use them for more than one key.
$cursor->limit(20);
Sets cursor to return a maximum of N results.
$cursor->max_time_ms( 500 );
Causes the server to abort the operation if the specified time in milliseconds is exceeded.
$cursor->tailable(1);
If a cursor should be tailable. Tailable cursors can only be used on capped collections and are similar to the tail -f command: they never die and keep returning new results as more is added to a collection.
tail -f
They are often used for getting log messages.
If you want the tailable cursor to block for a few seconds, use "tailable_await" instead. Note calling this with a false value disables tailing, even if tailable_await was previously called.
tailable_await
$cursor->tailable_await(1);
Sets a cursor to be tailable and block for a few seconds if no data is immediately available.
If you want the tailable cursor without blocking, use "tailable" instead. Note calling this with a false value disables tailing, even if tailable was previously called.
tailable
$cursor->skip( 50 );
Skips the first N results.
$cursor->snapshot;
Uses snapshot mode for the query. Snapshot mode assures no duplicates are returned due an intervening write relocating a document. Note that if an object is inserted, updated or deleted during the query, it may or may not be returned when snapshot mode is enabled. Short query responses (less than 1MB) are always effectively snapshotted. Currently, snapshot mode may not be used with sorting or explicit hints.
$cursor->hint({'x' => 1}); $cursor->hint(['x', 1]); $cursor->hint('x_1');
Force Mongo to use a specific index for a query.
$cursor->partial(1);
If a shard is down, mongos will return an error when it tries to query that shard. If this is set, mongos will just skip that shard, instead.
$cursor->read_preference($read_preference_object); $cursor->read_preference('secondary', [{foo => 'bar'}]);
Sets read preference for the cursor's connection.
If given a single argument that is a MongoDB::ReadPreference object, the read preference is set to that object. Otherwise, it takes positional arguments: the read preference mode and a tag set list, which must be a valid mode and tag set list as described in the MongoDB::ReadPreference documentation.
$cursor->slave_okay(1);
If a query can be done on a slave database server.
These methods run introspection methods on the query conditions and modifiers stored within the cursor object.
my $explanation = $cursor->explain;
This will tell you the type of cursor used, the number of records the DB had to examine as part of this query, the number of records returned by the query, and the time in milliseconds the query took to execute.
See also core documentation on explain: http://dochub.mongodb.org/core/explain.
my $num = $cursor->count; my $num = $cursor->skip(20)->count(1);
Returns the number of document this query will return. Optionally takes a boolean parameter, indicating that the cursor's limit and skip fields should be used in calculating the count.
These methods allow you to iterate over results.
my $result = $cursor->result;
This method will return a MongoDB::QueryResult object with the result of the query. The query will be executed on demand.
Iterating with a MongoDB::QueryResult object directly instead of a MongoDB::Cursor will be slightly faster, since the MongoDB::Cursor methods below just internally call the corresponding method on the result object.
while ($cursor->has_next) { ... }
Checks if there is another result to fetch. Will automatically fetch more data from the server if necessary.
while (my $object = $cursor->next) { ... }
Returns the next object in the cursor. Will automatically fetch more data from the server if necessary. Returns undef if no more data is available.
my @objects = $cursor->all;
Returns a list of all objects in the result.
Resets the cursor. After being reset, pre-query methods can be called on the cursor (sort, limit, etc.) and subsequent calls to next, has_next, or all will re-query the database.
Returns a hash of information about this cursor. This is intended for debugging purposes and users should not rely on the contents of this method for production use. Currently the fields are:
cursor_id -- the server-side id for this cursor as. This is an opaque string. A cursor_id of "\0\0\0\0\0\0\0\0" means there are no more results on the server.
cursor_id
num -- the number of results received from the server so far
num
at -- the (zero-based) index of the document that will be returned next from "next"
at
flag -- if the database could not find the cursor or another error occurred, flag may contain a hash reference of flags set in the response (depending on the error). See http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-OPREPLY for a full list of flag values.
flag
start -- the index of the result that the current batch of results starts at.
start
If the cursor has not yet executed, only the num field will be returned with a value of 0.
Core documentation on cursors: http://dochub.mongodb.org/core/cursors.
David Golden <david@mongodb.com>
Mike Friedman <friedo@mongodb.com>
Kristina Chodorow <kristina@mongodb.com>
Florian Ragwitz <rafl@debian.org>
This software is Copyright (c) 2015 by MongoDB, Inc..
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install MongoDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MongoDB
CPAN shell
perl -MCPAN -e shell install MongoDB
For more information on module installation, please visit the detailed CPAN module installation guide.