Provided by: libmongodb-perl_1.8.1-1_amd64 bug

NAME

       MongoDB::Cursor - A lazy cursor for Mongo query results

VERSION

       version v1.8.1

SYNOPSIS

           while (my $object = $cursor->next) {
               ...
           }

           my @objects = $cursor->all;

USAGE

   Multithreading
       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.

ATTRIBUTES

   started_iterating
       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.

QUERY MODIFIERS

       These methods modify the query to be run.  An exception will be thrown if they are called
       after results are iterated.

   immortal
           $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
       MongoDB::MongoClient and "socket_timeout_ms" in MongoDB::MongoClient.

       Returns this cursor for chaining operations.

   fields
           $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 Tie::IxHash object.

       See Limit fields to return <http://docs.mongodb.org/manual/tutorial/project-fields-from-
       query-results/> in the MongoDB documentation for details.

       Returns this cursor for chaining operations.

   sort
           # 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.

       Returns this cursor for chaining operations.

   limit
           $cursor->limit(20);

       Sets cursor to return a maximum of N results.

       Returns this cursor for chaining operations.

   max_await_time_ms
           $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.

   max_time_ms
           $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.

   tailable
           $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.

   tailable_await
           $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.

   skip
           $cursor->skip( 50 );

       Skips the first N results.

       Returns this cursor for chaining operations.

   snapshot
           $cursor->snapshot(1);

       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.

       Returns this cursor for chaining operations.

   hint
           $cursor->hint({'x' => 1});
           $cursor->hint(['x', 1]);
           $cursor->hint('x_1');

       Force Mongo to use a specific index for a query.

       Returns this cursor for chaining operations.

   partial
           $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.

   read_preference
           $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.

       Returns this cursor for chaining operations.

QUERY INTROSPECTION AND RESET

       These methods run introspection methods on the query conditions and modifiers stored
       within the cursor object.

   explain
           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>.

QUERY ITERATION

       These methods allow you to iterate over results.

   result
           my $result = $cursor->result;

       This method will execute the query and return a MongoDB::QueryResult 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 MongoDB::Cursor will be
       slightly faster, since the MongoDB::Cursor methods below just internally call the
       corresponding method on the result object.

   has_next
           while ($cursor->has_next) {
               ...
           }

       Checks if there is another result to fetch.  Will automatically fetch more data from the
       server if necessary.

   next
           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.

   batch
           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.

   all
           my @objects = $cursor->all;

       Returns a list of all objects in the result.

   reset
       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.

   info
       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.

SEE ALSO

       Core documentation on cursors: <http://dochub.mongodb.org/core/cursors>.

AUTHORS

       •   David Golden <david@mongodb.com>

       •   Rassi <rassi@mongodb.com>

       •   Mike Friedman <friedo@friedo.com>

       •   Kristina Chodorow <k.chodorow@gmail.com>

       •   Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2018 by MongoDB, Inc.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004