1MongoDB::Cursor(3) User Contributed Perl Documentation MongoDB::Cursor(3)
2
6 MongoDB::Cursor - A lazy cursor for Mongo query results
7
9 version v2.0.3
10
12 while (my $object = $cursor->next) {
13 ...
14 }
15 my @objects = $cursor->all;
17
19 Multithreading
20 Cursors are cloned in threads, but not reset. Iterating the same
21 cursor from multiple threads will give unpredictable results. Only
22 iterate from a single thread.
23
25 started_iterating
26 A boolean indicating if this cursor has queried the database yet.
27 Methods modifying the query will complain if they are called after the
28 database is queried.
29
31 These methods modify the query to be run. An exception will be thrown
32 if they are called after results are iterated.
33 immortal
35 $cursor->immortal(1);
36 Ordinarily, a cursor "dies" on the database server after a certain
38 length of time (approximately 10 minutes), to prevent inactive cursors
39 from hogging resources. This option indicates that a cursor should not
40 die until all of its results have been fetched or it goes out of scope
41 in Perl.
42 Boolean value, defaults to 0.
44 Note: "immortal" only affects the server-side timeout. If you are
46 getting client-side timeouts you will need to change your client
47 configuration. See "max_time_ms" in MongoDB::MongoClient and
48 "socket_timeout_ms" in MongoDB::MongoClient.
49 Returns this cursor for chaining operations.
51 fields
53 $coll->insert({name => "Fred", age => 20});
54 my $cursor = $coll->find->fields({ name => 1 });
55 my $obj = $cursor->next;
56 $obj->{name}; "Fred"
57 $obj->{age}; # undef
58 Selects which fields are returned. The default is all fields. When
60 fields are specified, _id is returned by default, but this can be
61 disabled by explicitly setting it to "0". E.g. "_id => 0". Argument
62 must be either a hash reference or a Tie::IxHash object.
63 See Limit fields to return
65 <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-
66 results/> in the MongoDB documentation for details.
67 Returns this cursor for chaining operations.
69 sort
71 # sort by name, descending
72 $cursor->sort([name => -1]);
73 Adds a sort to the query. Argument is either a hash reference or a
75 Tie::IxHash or an array reference of key/value pairs. Because hash
76 references are not ordered, do not use them for more than one key.
77 Returns this cursor for chaining operations.
79 limit
81 $cursor->limit(20);
82 Sets cursor to return a maximum of N results.
84 Returns this cursor for chaining operations.
86 max_await_time_ms
88 $cursor->max_await_time_ms( 500 );
89 The maximum amount of time in milliseconds for the server to wait on
91 new documents to satisfy a tailable cursor query. This only applies to
92 a cursor of type 'tailble_await'. This is ignored if the cursor is not
93 a 'tailable_await' cursor or the server version is less than version
94 3.2.
95 Returns this cursor for chaining operations.
97 max_time_ms
99 $cursor->max_time_ms( 500 );
100 Causes the server to abort the operation if the specified time in
102 milliseconds is exceeded.
103 Returns this cursor for chaining operations.
105 tailable
107 $cursor->tailable(1);
108 If a cursor should be tailable. Tailable cursors can only be used on
110 capped collections and are similar to the "tail -f" command: they never
111 die and keep returning new results as more is added to a collection.
112 They are often used for getting log messages.
114 Boolean value, defaults to 0.
116 If you want the tailable cursor to block for a few seconds, use
118 "tailable_await" instead. Note calling this with a false value
119 disables tailing, even if "tailable_await" was previously called.
120 Returns this cursor for chaining operations.
122 tailable_await
124 $cursor->tailable_await(1);
125 Sets a cursor to be tailable and block for a few seconds if no data is
127 immediately available.
128 Boolean value, defaults to 0.
130 If you want the tailable cursor without blocking, use "tailable"
132 instead. Note calling this with a false value disables tailing, even
133 if "tailable" was previously called.
134 skip
136 $cursor->skip( 50 );
137 Skips the first N results.
139 Returns this cursor for chaining operations.
141 hint
143 Hint the query to use a specific index by name:
144 $cursor->hint("index_name");
146 Hint the query to use index based on individual keys and direction:
148 $cursor->hint([field_1 => 1, field_2 => -1, field_3 => 1]);
150 Use of a hash reference should be avoided except for single key
152 indexes.
153 The hint must be a string or ordered document.
155 Returns this cursor for chaining operations.
157 partial
159 $cursor->partial(1);
160 If a shard is down, mongos will return an error when it tries to query
162 that shard. If this is set, mongos will just skip that shard, instead.
163 Boolean value, defaults to 0.
165 Returns this cursor for chaining operations.
167 read_preference
169 $cursor->read_preference($read_preference_object);
170 $cursor->read_preference('secondary', [{foo => 'bar'}]);
171 Sets read preference for the cursor's connection.
173 If given a single argument that is a MongoDB::ReadPreference object,
175 the read preference is set to that object. Otherwise, it takes
176 positional arguments: the read preference mode and a tag set list,
177 which must be a valid mode and tag set list as described in the
178 MongoDB::ReadPreference documentation.
179 Returns this cursor for chaining operations.
181
183 These methods run introspection methods on the query conditions and
184 modifiers stored within the cursor object.
185 explain
187 my $explanation = $cursor->explain;
188 This will tell you the type of cursor used, the number of records the
190 DB had to examine as part of this query, the number of records returned
191 by the query, and the time in milliseconds the query took to execute.
192 See also core documentation on explain:
194 <http://dochub.mongodb.org/core/explain>.
195
197 These methods allow you to iterate over results.
198 result
200 my $result = $cursor->result;
201 This method will execute the query and return a MongoDB::QueryResult
203 object with the results.
204 The "has_next", "next", and "all" methods call "result" internally,
206 which executes the query "on demand".
207 Iterating with a MongoDB::QueryResult object directly instead of a
209 MongoDB::Cursor will be slightly faster, since the MongoDB::Cursor
210 methods below just internally call the corresponding method on the
211 result object.
212 has_next
214 while ($cursor->has_next) {
215 ...
216 }
217 Checks if there is another result to fetch. Will automatically fetch
219 more data from the server if necessary.
220 next
222 while (my $object = $cursor->next) {
223 ...
224 }
225 Returns the next object in the cursor. Will automatically fetch more
227 data from the server if necessary. Returns undef if no more data is
228 available.
229 batch
231 while (my @batch = $cursor->batch) {
232 ...
233 }
234 Returns the next batch of data from the cursor. Will automatically
236 fetch more data from the server if necessary. Returns an empty list if
237 no more data is available.
238 all
240 my @objects = $cursor->all;
241 Returns a list of all objects in the result.
243 reset
245 Resets the cursor. After being reset, pre-query methods can be called
246 on the cursor (sort, limit, etc.) and subsequent calls to result, next,
247 has_next, or all will re-query the database.
248 info
250 Returns a hash of information about this cursor. This is intended for
251 debugging purposes and users should not rely on the contents of this
252 method for production use. Currently the fields are:
253 · "cursor_id" -- the server-side id for this cursor. See below for
255 details.
256 · "num" -- the number of results received from the server so far
258 · "at" -- the (zero-based) index of the document that will be
260 returned next from "next"
261 · "flag" -- if the database could not find the cursor or another
263 error occurred, "flag" may contain a hash reference of flags set in
264 the response (depending on the error). See
265 <http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-OPREPLY>
266 for a full list of flag values.
267 · "start" -- the index of the result that the current batch of
269 results starts at.
270 If the cursor has not yet executed, only the "num" field will be
272 returned with a value of 0.
273 The "cursor_id" could appear in one of three forms:
275 · MongoDB::CursorID object (a blessed reference to an 8-byte string)
277 · A perl scalar (an integer)
279 · A Math::BigInt object (64 bit integer on 32-bit perl)
281 When the "cursor_id" is zero, there are no more results to fetch.
283
285 Core documentation on cursors:
286 <http://dochub.mongodb.org/core/cursors>.
287
289 · David Golden <david@mongodb.com>
290 · Rassi <rassi@mongodb.com>
292 · Mike Friedman <friedo@friedo.com>
294 · Kristina Chodorow <k.chodorow@gmail.com>
296 · Florian Ragwitz <rafl@debian.org>
298
300 This software is Copyright (c) 2019 by MongoDB, Inc.
301 This is free software, licensed under:
303 The Apache License, Version 2.0, January 2004
305perl v5.28.1 2019-02-07 MongoDB::Cursor(3)