MongoDB::Cursor - A lazy cursor for Mongo query results
version v2.2.2
while (my $object = $cursor->next) {
...
}
my @objects = $cursor->all;
NOTE: Per threads documentation, use of Perl threads is discouraged by the
maintainers of Perl and the MongoDB Perl driver does not test or provide support
for use with threads.
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.
A boolean indicating if this cursor has queried the database yet. Methods
modifying the query will complain if they are called after the database is
queried.
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 indicates 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.
Note: immortal only affects the server-side timeout. If you are getting
client-side timeouts you will need to change your client configuration.
See max_time_ms in the MongoDB::MongoClient manpage and
socket_timeout_ms in the MongoDB::MongoClient manpage.
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 must be either a
hash reference or a the Tie::IxHash manpage object.
See Limit fields to return
in the MongoDB documentation for details.
Returns this cursor for chaining operations.
# sort by name, descending
$cursor->sort([name => -1]);
Adds a sort to the query. Argument is either a hash reference or a
the Tie::IxHash manpage or an array reference of key/value pairs. Because hash
references are not ordered, do not use them for more than one key.
Returns this cursor for chaining operations.
$cursor->limit(20);
Sets cursor to return a maximum of N results.
Returns this cursor for chaining operations.
$cursor->max_await_time_ms( 500 );
The maximum amount of time in milliseconds for the server to wait on new
documents to satisfy a tailable cursor query. This only applies to a
cursor of type 'tailble_await'. This is ignored if the cursor is not
a 'tailable_await' cursor or the server version is less than version 3.2.
Returns this cursor for chaining operations.
$cursor->max_time_ms( 500 );
Causes the server to abort the operation if the specified time in milliseconds
is exceeded.
Returns this cursor for chaining operations.
$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.
They are often used for getting log messages.
Boolean value, defaults to 0.
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.
Returns this cursor for chaining operations.
$cursor->tailable_await(1);
Sets a cursor to be tailable and block for a few seconds if no data
is immediately available.
Boolean value, defaults to 0.
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.
$cursor->skip( 50 );
Skips the first N results.
Returns this cursor for chaining operations.
Hint the query to use a specific index by name:
$cursor->hint("index_name");
Hint the query to use index based on individual keys and direction:
$cursor->hint([field_1 => 1, field_2 => -1, field_3 => 1]);
Use of a hash reference should be avoided except for single key indexes.
The hint must be a string or ordered document.
Returns this cursor for chaining operations.
$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.
Boolean value, defaults to 0.
Returns this cursor for chaining operations.
$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 the MongoDB::ReadPreference manpage 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 the MongoDB::ReadPreference manpage
documentation.
Returns this cursor for chaining operations.
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.
These methods allow you to iterate over results.
my $result = $cursor->result;
This method will execute the query and return a the MongoDB::QueryResult manpage object
with the results.
The has_next, next, and all methods call result internally,
which executes the query ``on demand''.
Iterating with a MongoDB::QueryResult object directly instead of a
the MongoDB::Cursor manpage will be slightly faster, since the the MongoDB::Cursor manpage
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.
while (my @batch = $cursor->batch) {
...
}
Returns the next batch of data from the cursor. Will automatically fetch more
data from the server if necessary. Returns an empty list 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
result, 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. See below for details.
-
num -- the number of results received from the server so far
-
at -- the (zero-based) index of the document that will be returned next from next
-
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.
-
start -- the index of the result that the current batch of results starts at.
If the cursor has not yet executed, only the num field will be returned with
a value of 0.
The cursor_id could appear in one of three forms:
-
MongoDB::CursorID object (a blessed reference to an 8-byte string)
-
A perl scalar (an integer)
-
A Math::BigInt object (64 bit integer on 32-bit perl)
When the cursor_id is zero, there are no more results to fetch.
Core documentation on cursors: http://dochub.mongodb.org/core/cursors.
This software is Copyright (c) 2020 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
|