1MongoDB::Cursor(3)    User Contributed Perl Documentation   MongoDB::Cursor(3)
2
3
4

NAME

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

VERSION

9       version v2.2.2
10

SYNOPSIS

12           while (my $object = $cursor->next) {
13               ...
14           }
15
16           my @objects = $cursor->all;
17

USAGE

19   Multithreading
20       NOTE: Per threads documentation, use of Perl threads is discouraged by
21       the maintainers of Perl and the MongoDB Perl driver does not test or
22       provide support for use with threads.
23
24       Cursors are cloned in threads, but not reset.  Iterating the same
25       cursor from multiple threads will give unpredictable results.  Only
26       iterate from a single thread.
27

ATTRIBUTES

29   started_iterating
30       A boolean indicating if this cursor has queried the database yet.
31       Methods modifying the query will complain if they are called after the
32       database is queried.
33

QUERY MODIFIERS

35       These methods modify the query to be run.  An exception will be thrown
36       if they are called after results are iterated.
37
38   immortal
39           $cursor->immortal(1);
40
41       Ordinarily, a cursor "dies" on the database server after a certain
42       length of time (approximately 10 minutes), to prevent inactive cursors
43       from hogging resources.  This option indicates that a cursor should not
44       die until all of its results have been fetched or it goes out of scope
45       in Perl.
46
47       Boolean value, defaults to 0.
48
49       Note: "immortal" only affects the server-side timeout.  If you are
50       getting client-side timeouts you will need to change your client
51       configuration.  See "max_time_ms" in MongoDB::MongoClient and
52       "socket_timeout_ms" in MongoDB::MongoClient.
53
54       Returns this cursor for chaining operations.
55
56   fields
57           $coll->insert({name => "Fred", age => 20});
58           my $cursor = $coll->find->fields({ name => 1 });
59           my $obj = $cursor->next;
60           $obj->{name}; "Fred"
61           $obj->{age}; # undef
62
63       Selects which fields are returned.  The default is all fields.  When
64       fields are specified, _id is returned by default, but this can be
65       disabled by explicitly setting it to "0".  E.g.  "_id => 0". Argument
66       must be either a hash reference or a Tie::IxHash object.
67
68       See Limit fields to return
69       <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-
70       results/> in the MongoDB documentation for details.
71
72       Returns this cursor for chaining operations.
73
74   sort
75           # sort by name, descending
76           $cursor->sort([name => -1]);
77
78       Adds a sort to the query.  Argument is either a hash reference or a
79       Tie::IxHash or an array reference of key/value pairs.  Because hash
80       references are not ordered, do not use them for more than one key.
81
82       Returns this cursor for chaining operations.
83
84   limit
85           $cursor->limit(20);
86
87       Sets cursor to return a maximum of N results.
88
89       Returns this cursor for chaining operations.
90
91   max_await_time_ms
92           $cursor->max_await_time_ms( 500 );
93
94       The maximum amount of time in milliseconds for the server to wait on
95       new documents to satisfy a tailable cursor query. This only applies to
96       a cursor of type 'tailble_await'.  This is ignored if the cursor is not
97       a 'tailable_await' cursor or the server version is less than version
98       3.2.
99
100       Returns this cursor for chaining operations.
101
102   max_time_ms
103           $cursor->max_time_ms( 500 );
104
105       Causes the server to abort the operation if the specified time in
106       milliseconds is exceeded.
107
108       Returns this cursor for chaining operations.
109
110   tailable
111           $cursor->tailable(1);
112
113       If a cursor should be tailable.  Tailable cursors can only be used on
114       capped collections and are similar to the "tail -f" command: they never
115       die and keep returning new results as more is added to a collection.
116
117       They are often used for getting log messages.
118
119       Boolean value, defaults to 0.
120
121       If you want the tailable cursor to block for a few seconds, use
122       "tailable_await" instead.  Note calling this with a false value
123       disables tailing, even if "tailable_await" was previously called.
124
125       Returns this cursor for chaining operations.
126
127   tailable_await
128           $cursor->tailable_await(1);
129
130       Sets a cursor to be tailable and block for a few seconds if no data is
131       immediately available.
132
133       Boolean value, defaults to 0.
134
135       If you want the tailable cursor without blocking, use "tailable"
136       instead.  Note calling this with a false value disables tailing, even
137       if "tailable" was previously called.
138
139   skip
140           $cursor->skip( 50 );
141
142       Skips the first N results.
143
144       Returns this cursor for chaining operations.
145
146   hint
147       Hint the query to use a specific index by name:
148
149           $cursor->hint("index_name");
150
151       Hint the query to use index based on individual keys and direction:
152
153           $cursor->hint([field_1 => 1, field_2 => -1, field_3 => 1]);
154
155       Use of a hash reference should be avoided except for single key
156       indexes.
157
158       The hint must be a string or ordered document.
159
160       Returns this cursor for chaining operations.
161
162   partial
163           $cursor->partial(1);
164
165       If a shard is down, mongos will return an error when it tries to query
166       that shard.  If this is set, mongos will just skip that shard, instead.
167
168       Boolean value, defaults to 0.
169
170       Returns this cursor for chaining operations.
171
172   read_preference
173           $cursor->read_preference($read_preference_object);
174           $cursor->read_preference('secondary', [{foo => 'bar'}]);
175
176       Sets read preference for the cursor's connection.
177
178       If given a single argument that is a MongoDB::ReadPreference object,
179       the read preference is set to that object.  Otherwise, it takes
180       positional arguments: the read preference mode and a tag set list,
181       which must be a valid mode and tag set list as described in the
182       MongoDB::ReadPreference documentation.
183
184       Returns this cursor for chaining operations.
185

QUERY INTROSPECTION AND RESET

187       These methods run introspection methods on the query conditions and
188       modifiers stored within the cursor object.
189
190   explain
191           my $explanation = $cursor->explain;
192
193       This will tell you the type of cursor used, the number of records the
194       DB had to examine as part of this query, the number of records returned
195       by the query, and the time in milliseconds the query took to execute.
196
197       See also core documentation on explain:
198       <http://dochub.mongodb.org/core/explain>.
199

QUERY ITERATION

201       These methods allow you to iterate over results.
202
203   result
204           my $result = $cursor->result;
205
206       This method will execute the query and return a MongoDB::QueryResult
207       object with the results.
208
209       The "has_next", "next", and "all" methods call "result" internally,
210       which executes the query "on demand".
211
212       Iterating with a MongoDB::QueryResult object directly instead of a
213       MongoDB::Cursor will be slightly faster, since the MongoDB::Cursor
214       methods below just internally call the corresponding method on the
215       result object.
216
217   has_next
218           while ($cursor->has_next) {
219               ...
220           }
221
222       Checks if there is another result to fetch.  Will automatically fetch
223       more data from the server if necessary.
224
225   next
226           while (my $object = $cursor->next) {
227               ...
228           }
229
230       Returns the next object in the cursor. Will automatically fetch more
231       data from the server if necessary. Returns undef if no more data is
232       available.
233
234   batch
235           while (my @batch = $cursor->batch) {
236               ...
237           }
238
239       Returns the next batch of data from the cursor. Will automatically
240       fetch more data from the server if necessary. Returns an empty list if
241       no more data is available.
242
243   all
244           my @objects = $cursor->all;
245
246       Returns a list of all objects in the result.
247
248   reset
249       Resets the cursor.  After being reset, pre-query methods can be called
250       on the cursor (sort, limit, etc.) and subsequent calls to result, next,
251       has_next, or all will re-query the database.
252
253   info
254       Returns a hash of information about this cursor.  This is intended for
255       debugging purposes and users should not rely on the contents of this
256       method for production use.  Currently the fields are:
257
258       •   "cursor_id"  -- the server-side id for this cursor.  See below for
259           details.
260
261       •   "num" -- the number of results received from the server so far
262
263       •   "at" -- the (zero-based) index of the document that will be
264           returned next from "next"
265
266       •   "flag" -- if the database could not find the cursor or another
267           error occurred, "flag" may contain a hash reference of flags set in
268           the response (depending on the error).  See
269           <http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-OPREPLY>
270           for a full list of flag values.
271
272       •   "start" -- the index of the result that the current batch of
273           results starts at.
274
275       If the cursor has not yet executed, only the "num" field will be
276       returned with a value of 0.
277
278       The "cursor_id" could appear in one of three forms:
279
280       •   MongoDB::CursorID object (a blessed reference to an 8-byte string)
281
282       •   A perl scalar (an integer)
283
284       •   A Math::BigInt object (64 bit integer on 32-bit perl)
285
286       When the "cursor_id" is zero, there are no more results to fetch.
287

SEE ALSO

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

AUTHORS

293       •   David Golden <david@mongodb.com>
294
295       •   Rassi <rassi@mongodb.com>
296
297       •   Mike Friedman <friedo@friedo.com>
298
299       •   Kristina Chodorow <k.chodorow@gmail.com>
300
301       •   Florian Ragwitz <rafl@debian.org>
302
304       This software is Copyright (c) 2020 by MongoDB, Inc.
305
306       This is free software, licensed under:
307
308         The Apache License, Version 2.0, January 2004
309
310
311
312perl v5.36.0                      2023-01-20                MongoDB::Cursor(3)
Impressum