MongoDB::Cursor - phpMan

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

VERSION
    version v2.2.2

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

        my @objects = $cursor->all;

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

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-resul
    ts/> 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.

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

  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#MongoWirePr
        otocol-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 AT mongodb.com>

    *   Rassi <rassi AT mongodb.com>

    *   Mike Friedman <friedo AT friedo.com>

    *   Kristina Chodorow <k.chodorow AT gmail.com>

    *   Florian Ragwitz <rafl AT debian.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2020 by MongoDB, Inc.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004