Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MongoDB::Cursor(3)    User Contributed Perl Documentation   MongoDB::Cursor(3)

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

VERSION
       version v1.8.0

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:

       o   "cursor_id"	-- the server-side id for this cursor.	See below for
	   details.

       o   "num" -- the	number of results received from	the server so far

       o   "at"	-- the (zero-based) index of the document that will be
	   returned next from "next"

       o   "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.

       o   "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:

       o   MongoDB::CursorID object (a blessed reference to an 8-byte string)

       o   A perl scalar (an integer)

       o   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
       o   David Golden	<david@mongodb.com>

       o   Rassi <rassi@mongodb.com>

       o   Mike	Friedman <friedo@friedo.com>

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

       o   Florian Ragwitz <rafl@debian.org>

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

       This is free software, licensed under:

	 The Apache License, Version 2.0, January 2004

perl v5.24.1			  2017-04-10		    MongoDB::Cursor(3)

NAME | VERSION | SYNOPSIS | USAGE | ATTRIBUTES | QUERY MODIFIERS | QUERY INTROSPECTION AND RESET | QUERY ITERATION | SEE ALSO | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MongoDB::Cursor&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help