File Coverage

blib/lib/MongoDB/Cursor.pm

Criterion	Covered	Total	%
statement	42	125	33.6
branch	0	52	0.0
condition	0	8	0.0
subroutine	14	35	40.0
pod	19	20	95.0
total	75	240	31.2

#  Copyright 2009 - present MongoDB, Inc.
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#  http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.

use strict;
use warnings;
package MongoDB::Cursor;


# ABSTRACT: A lazy cursor for Mongo query results

use version;
our $VERSION = 'v2.2.0';

use Moo;
use MongoDB::Error;
use MongoDB::QueryResult;
use MongoDB::ReadPreference;
use MongoDB::_Protocol;
use MongoDB::Op::_Explain;
use MongoDB::_Types -types, qw/to_IxHash is_OrderedDoc/;
use Types::Standard qw(
    InstanceOf
    is_Str
);
use boolean;
use Tie::IxHash;
use namespace::clean -except => 'meta';

#pod =attr started_iterating
#pod
#pod A boolean indicating if this cursor has queried the database yet. Methods
#pod modifying the query will complain if they are called after the database is
#pod queried.
#pod
#pod =cut

with $_ for qw(
  MongoDB::Role::_CursorAPI
  MongoDB::Role::_DeprecationWarner
);

# attributes for sending a query
has client => (
    is       => 'ro',
    required => 1,
    isa      => InstanceOf ['MongoDB::MongoClient'],
);

has _query => (
    is => 'ro',
    isa => InstanceOf['MongoDB::Op::_Query'],
    required => 1,
    init_arg => 'query',
);

# lazy result attribute
has result => (
    is        => 'lazy',
    isa       => InstanceOf['MongoDB::QueryResult'],
    builder   => '_build_result',
    predicate => 'started_iterating',
    clearer   => '_clear_result',
);

# this does the query if it hasn't been done yet
sub _build_result {
    my ($self) = @_;

    return $self->{client}->send_retryable_read_op( $self->_query );
}

#--------------------------------------------------------------------------#
# methods that modify the query
#--------------------------------------------------------------------------#

#pod =head1 QUERY MODIFIERS
#pod
#pod These methods modify the query to be run.  An exception will be thrown if
#pod they are called after results are iterated.
#pod
#pod =head2 immortal
#pod
#pod     $cursor->immortal(1);
#pod
#pod Ordinarily, a cursor "dies" on the database server after a certain length of
#pod time (approximately 10 minutes), to prevent inactive cursors from hogging
#pod resources.  This option indicates that a cursor should not die until all of its
#pod results have been fetched or it goes out of scope in Perl.
#pod
#pod Boolean value, defaults to 0.
#pod
#pod Note: C only affects the server-side timeout.  If you are getting
#pod client-side timeouts you will need to change your client configuration.
#pod See L and
#pod L.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub immortal {
    my ( $self, $bool ) = @_;
    MongoDB::UsageError->throw("cannot set immortal after querying")
        if $self->started_iterating;

    $self->_query->set_noCursorTimeout($bool);
    return $self;
}

#pod =head2 fields
#pod
#pod     $coll->insert({name => "Fred", age => 20});
#pod     my $cursor = $coll->find->fields({ name => 1 });
#pod     my $obj = $cursor->next;
#pod     $obj->{name}; "Fred"
#pod     $obj->{age}; # undef
#pod
#pod Selects which fields are returned.  The default is all fields.  When fields
#pod are specified, _id is returned by default, but this can be disabled by
#pod explicitly setting it to "0".  E.g.  C<< _id => 0 >>. Argument must be either a
#pod hash reference or a L object.
#pod
#pod See L
#pod return|http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>
#pod in the MongoDB documentation for details.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub fields {
    my ($self, $f) = @_;
    MongoDB::UsageError->throw("cannot set fields after querying")
      if $self->started_iterating;
    MongoDB::UsageError->throw("not a hash reference")
      unless ref $f eq 'HASH' || ref $f eq 'Tie::IxHash';

    $self->_query->set_projection($f);
    return $self;
}

#pod =head2 sort
#pod
#pod     # sort by name, descending
#pod     $cursor->sort([name => -1]);
#pod
#pod Adds a sort to the query.  Argument is either a hash reference or a
#pod L or an array reference of key/value pairs.  Because hash
#pod references are not ordered, do not use them for more than one key.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub sort {
    my ( $self, $order ) = @_;
    MongoDB::UsageError->throw("cannot set sort after querying")
      if $self->started_iterating;

    $self->_query->set_sort($order);
    return $self;
}


#pod =head2 limit
#pod
#pod     $cursor->limit(20);
#pod
#pod Sets cursor to return a maximum of N results.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub limit {
    my ( $self, $num ) = @_;
    MongoDB::UsageError->throw("cannot set limit after querying")
      if $self->started_iterating;
    $self->_query->set_limit($num);
    return $self;
}


#pod =head2 max_await_time_ms
#pod
#pod     $cursor->max_await_time_ms( 500 );
#pod
#pod The maximum amount of time in milliseconds for the server to wait on new
#pod documents to satisfy a tailable cursor query. This only applies to a
#pod cursor of type 'tailble_await'.  This is ignored if the cursor is not
#pod a 'tailable_await' cursor or the server version is less than version 3.2.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub max_await_time_ms {
    my ( $self, $num ) = @_;
    $num = 0 unless defined $num;
    MongoDB::UsageError->throw("max_await_time_ms must be non-negative")
      if $num < 0;
    MongoDB::UsageError->throw("can not set max_await_time_ms after querying")
      if $self->started_iterating;

    $self->_query->set_maxAwaitTimeMS( $num );
    return $self;
}

#pod =head2 max_time_ms
#pod
#pod     $cursor->max_time_ms( 500 );
#pod
#pod Causes the server to abort the operation if the specified time in milliseconds
#pod is exceeded.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub max_time_ms {
    my ( $self, $num ) = @_;
    $num = 0 unless defined $num;
    MongoDB::UsageError->throw("max_time_ms must be non-negative")
      if $num < 0;
    MongoDB::UsageError->throw("can not set max_time_ms after querying")
      if $self->started_iterating;

    $self->_query->set_maxTimeMS( $num );
    return $self;

}

#pod =head2 tailable
#pod
#pod     $cursor->tailable(1);
#pod
#pod If a cursor should be tailable.  Tailable cursors can only be used on capped
#pod collections and are similar to the C command: they never die and keep
#pod returning new results as more is added to a collection.
#pod
#pod They are often used for getting log messages.
#pod
#pod Boolean value, defaults to 0.
#pod
#pod If you want the tailable cursor to block for a few seconds, use
#pod L instead.  B calling this with a false value
#pod disables tailing, even if C was previously called.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub tailable {
    my ( $self, $bool ) = @_;
    MongoDB::UsageError->throw("cannot set tailable after querying")
        if $self->started_iterating;

    $self->_query->set_cursorType($bool ? 'tailable' : 'non_tailable');
    return $self;
}

#pod =head2 tailable_await
#pod
#pod     $cursor->tailable_await(1);
#pod
#pod Sets a cursor to be tailable and block for a few seconds if no data
#pod is immediately available.
#pod
#pod Boolean value, defaults to 0.
#pod
#pod If you want the tailable cursor without blocking, use L instead.
#pod B calling this with a false value disables tailing, even if C
#pod was previously called.
#pod
#pod =cut

sub tailable_await {
    my ( $self, $bool ) = @_;
    MongoDB::UsageError->throw("cannot set tailable_await after querying")
        if $self->started_iterating;

    $self->_query->set_cursorType($bool ? 'tailable_await' : 'non_tailable');
    return $self;
}

#pod =head2 skip
#pod
#pod     $cursor->skip( 50 );
#pod
#pod Skips the first N results.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub skip {
    my ( $self, $num ) = @_;
    MongoDB::UsageError->throw("skip must be non-negative")
      if $num < 0;
    MongoDB::UsageError->throw("cannot set skip after querying")
      if $self->started_iterating;

    $self->_query->set_skip($num);
    return $self;
}

#pod =head2 hint
#pod
#pod Hint the query to use a specific index by name:
#pod
#pod     $cursor->hint("index_name");
#pod
#pod Hint the query to use index based on individual keys and direction:
#pod
#pod     $cursor->hint([field_1 => 1, field_2 => -1, field_3 => 1]);
#pod
#pod Use of a hash reference should be avoided except for single key indexes.
#pod
#pod The hint must be a string or L
#pod document>.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub hint {
    my ( $self, $index ) = @_;
    MongoDB::UsageError->throw("cannot set hint after querying")
      if $self->started_iterating;
    MongoDB::UsageError->throw("hint must be string or ordered document, not '$index'")
      if ! (is_Str($index) || is_OrderedDoc($index));

    $self->_query->set_hint( $index );

    return $self;
}

#pod =head2 partial
#pod
#pod     $cursor->partial(1);
#pod
#pod If a shard is down, mongos will return an error when it tries to query that
#pod shard.  If this is set, mongos will just skip that shard, instead.
#pod
#pod Boolean value, defaults to 0.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub partial {
    my ($self, $value) = @_;
    MongoDB::UsageError->throw("cannot set partial after querying")
      if $self->started_iterating;

    $self->_query->set_allowPartialResults( $value );

    # returning self is an API change but more consistent with other cursor methods
    return $self;
}

#pod =head2 read_preference
#pod
#pod     $cursor->read_preference($read_preference_object);
#pod     $cursor->read_preference('secondary', [{foo => 'bar'}]);
#pod
#pod Sets read preference for the cursor's connection.
#pod
#pod If given a single argument that is a L object, the
#pod read preference is set to that object.  Otherwise, it takes positional
#pod arguments: the read preference mode and a tag set list, which must be a valid
#pod mode and tag set list as described in the L
#pod documentation.
#pod
#pod Returns this cursor for chaining operations.
#pod
#pod =cut

sub read_preference {
    my $self = shift;
    MongoDB::UsageError->throw("cannot set read preference after querying")
      if $self->started_iterating;

    my $type = ref $_[0];
    if ( $type eq 'MongoDB::ReadPreference' ) {
        $self->_query->read_preference( $_[0] );
    }
    else {
        my $mode     = shift || 'primary';
        my $tag_sets = shift;
        my $rp       = MongoDB::ReadPreference->new(
            mode => $mode,
            ( $tag_sets ? ( tag_sets => $tag_sets ) : () )
        );
        $self->_query->read_preference($rp);
    }

    return $self;
}

#pod =head1 QUERY INTROSPECTION AND RESET
#pod
#pod These methods run introspection methods on the query conditions and modifiers
#pod stored within the cursor object.
#pod
#pod =head2 explain
#pod
#pod     my $explanation = $cursor->explain;
#pod
#pod This will tell you the type of cursor used, the number of records the DB had to
#pod examine as part of this query, the number of records returned by the query, and
#pod the time in milliseconds the query took to execute.
#pod
#pod See also core documentation on explain:
#pod L.
#pod
#pod =cut

sub explain {
    my ($self) = @_;

    my $explain_op = MongoDB::Op::_Explain->_new(
        db_name             => $self->_query->db_name,
        coll_name           => $self->_query->coll_name,
        full_name           => $self->_query->full_name,
        bson_codec          => $self->_query->bson_codec,
        query               => $self->_query,
        read_preference     => $self->_query->read_preference,
        read_concern        => $self->_query->read_concern,
        session             => $self->_query->session,
        monitoring_callback => $self->client->monitoring_callback,
    );

    return $self->_query->client->send_retryable_read_op($explain_op);
}

#pod =head1 QUERY ITERATION
#pod
#pod These methods allow you to iterate over results.
#pod
#pod =head2 result
#pod
#pod     my $result = $cursor->result;
#pod
#pod This method will execute the query and return a L object
#pod with the results.
#pod
#pod The C, C, and C methods call C internally,
#pod which executes the query "on demand".
#pod
#pod Iterating with a MongoDB::QueryResult object directly instead of a
#pod L will be slightly faster, since the L
#pod methods below just internally call the corresponding method on the result
#pod object.
#pod
#pod =cut

#--------------------------------------------------------------------------#
# methods delgated to result object
#--------------------------------------------------------------------------#

#pod =head2 has_next
#pod
#pod     while ($cursor->has_next) {
#pod         ...
#pod     }
#pod
#pod Checks if there is another result to fetch.  Will automatically fetch more
#pod data from the server if necessary.
#pod
#pod =cut

sub has_next { $_[0]->result->has_next }

#pod =head2 next
#pod
#pod     while (my $object = $cursor->next) {
#pod         ...
#pod     }
#pod
#pod Returns the next object in the cursor. Will automatically fetch more data from
#pod the server if necessary. Returns undef if no more data is available.
#pod
#pod =cut

sub next { $_[0]->result->next }

#pod =head2 batch
#pod
#pod     while (my @batch = $cursor->batch) {
#pod         ...
#pod     }
#pod
#pod Returns the next batch of data from the cursor. Will automatically fetch more
#pod data from the server if necessary. Returns an empty list if no more data is available.
#pod
#pod =cut

sub batch { $_[0]->result->batch }

#pod =head2 all
#pod
#pod     my @objects = $cursor->all;
#pod
#pod Returns a list of all objects in the result.
#pod
#pod =cut

sub all { $_[0]->result->all }

#pod =head2 reset
#pod
#pod Resets the cursor.  After being reset, pre-query methods can be
#pod called on the cursor (sort, limit, etc.) and subsequent calls to
#pod result, next, has_next, or all will re-query the database.
#pod
#pod =cut

sub reset {
    my ($self) = @_;
    $self->_clear_result;
    return $self;
}

#pod =head2 info
#pod
#pod Returns a hash of information about this cursor.  This is intended for
#pod debugging purposes and users should not rely on the contents of this method for
#pod production use.  Currently the fields are:
#pod
#pod =for :list
#pod * C  -- the server-side id for this cursor.  See below for details.
#pod * C -- the number of results received from the server so far
#pod * C -- the (zero-based) index of the document that will be returned next from L
#pod * C -- if the database could not find the cursor or another error occurred, C may
#pod   contain a hash reference of flags set in the response (depending on the error).  See
#pod   L
#pod   for a full list of flag values.
#pod * C -- the index of the result that the current batch of results starts at.
#pod
#pod If the cursor has not yet executed, only the C field will be returned with
#pod a value of 0.
#pod
#pod The C could appear in one of three forms:
#pod
#pod =for :list
#pod * MongoDB::CursorID object (a blessed reference to an 8-byte string)
#pod * A perl scalar (an integer)
#pod * A Math::BigInt object (64 bit integer on 32-bit perl)
#pod
#pod When the C is zero, there are no more results to fetch.
#pod
#pod =cut

sub info {
    my $self = shift;
    if ( $self->started_iterating ) {
        return $self->result->_info;
    }
    else {
        return { num => 0 };
    }
}

#--------------------------------------------------------------------------#
# Deprecated methods
#--------------------------------------------------------------------------#

sub snapshot {
    my ($self, $bool) = @_;

    $self->_warn_deprecated_method(
        'snapshot' => "Snapshot is deprecated as of MongoDB 3.6" );

    MongoDB::UsageError->throw("cannot set snapshot after querying")
      if $self->started_iterating;

    MongoDB::UsageError->throw("snapshot requires a defined, boolean argument")
      unless defined $bool;

    $self->_query->set_snapshot($bool);
    return $self;
}

1;



# vim: ts=4 sts=4 sw=4 et tw=75:

__END__