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.2.2
10
12 while (my $object = $cursor->next) {
13 ...
14 }
15 my @objects = $cursor->all;
17
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 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
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
35 These methods modify the query to be run. An exception will be thrown
36 if they are called after results are iterated.
37 immortal
39 $cursor->immortal(1);
40 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 Boolean value, defaults to 0.
48 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 Returns this cursor for chaining operations.
55 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 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 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 Returns this cursor for chaining operations.
73 sort
75 # sort by name, descending
76 $cursor->sort([name => -1]);
77 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 Returns this cursor for chaining operations.
83 limit
85 $cursor->limit(20);
86 Sets cursor to return a maximum of N results.
88 Returns this cursor for chaining operations.
90 max_await_time_ms
92 $cursor->max_await_time_ms( 500 );
93 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 Returns this cursor for chaining operations.
101 max_time_ms
103 $cursor->max_time_ms( 500 );
104 Causes the server to abort the operation if the specified time in
106 milliseconds is exceeded.
107 Returns this cursor for chaining operations.
109 tailable
111 $cursor->tailable(1);
112 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 They are often used for getting log messages.
118 Boolean value, defaults to 0.
120 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 Returns this cursor for chaining operations.
126 tailable_await
128 $cursor->tailable_await(1);
129 Sets a cursor to be tailable and block for a few seconds if no data is
131 immediately available.
132 Boolean value, defaults to 0.
134 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 skip
140 $cursor->skip( 50 );
141 Skips the first N results.
143 Returns this cursor for chaining operations.
145 hint
147 Hint the query to use a specific index by name:
148 $cursor->hint("index_name");
150 Hint the query to use index based on individual keys and direction:
152 $cursor->hint([field_1 => 1, field_2 => -1, field_3 => 1]);
154 Use of a hash reference should be avoided except for single key
156 indexes.
157 The hint must be a string or ordered document.
159 Returns this cursor for chaining operations.
161 partial
163 $cursor->partial(1);
164 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 Boolean value, defaults to 0.
169 Returns this cursor for chaining operations.
171 read_preference
173 $cursor->read_preference($read_preference_object);
174 $cursor->read_preference('secondary', [{foo => 'bar'}]);
175 Sets read preference for the cursor's connection.
177 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 Returns this cursor for chaining operations.
185
187 These methods run introspection methods on the query conditions and
188 modifiers stored within the cursor object.
189 explain
191 my $explanation = $cursor->explain;
192 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 See also core documentation on explain:
198 <http://dochub.mongodb.org/core/explain>.
199
201 These methods allow you to iterate over results.
202 result
204 my $result = $cursor->result;
205 This method will execute the query and return a MongoDB::QueryResult
207 object with the results.
208 The "has_next", "next", and "all" methods call "result" internally,
210 which executes the query "on demand".
211 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 has_next
218 while ($cursor->has_next) {
219 ...
220 }
221 Checks if there is another result to fetch. Will automatically fetch
223 more data from the server if necessary.
224 next
226 while (my $object = $cursor->next) {
227 ...
228 }
229 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 batch
235 while (my @batch = $cursor->batch) {
236 ...
237 }
238 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 all
244 my @objects = $cursor->all;
245 Returns a list of all objects in the result.
247 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 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 • "cursor_id" -- the server-side id for this cursor. See below for
259 details.
260 • "num" -- the number of results received from the server so far
262 • "at" -- the (zero-based) index of the document that will be
264 returned next from "next"
265 • "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 • "start" -- the index of the result that the current batch of
273 results starts at.
274 If the cursor has not yet executed, only the "num" field will be
276 returned with a value of 0.
277 The "cursor_id" could appear in one of three forms:
279 • MongoDB::CursorID object (a blessed reference to an 8-byte string)
281 • A perl scalar (an integer)
283 • A Math::BigInt object (64 bit integer on 32-bit perl)
285 When the "cursor_id" is zero, there are no more results to fetch.
287
289 Core documentation on cursors:
290 <http://dochub.mongodb.org/core/cursors>.
291
293 • David Golden <david@mongodb.com>
294 • Rassi <rassi@mongodb.com>
296 • Mike Friedman <friedo@friedo.com>
298 • Kristina Chodorow <k.chodorow@gmail.com>
300 • Florian Ragwitz <rafl@debian.org>
302
304 This software is Copyright (c) 2020 by MongoDB, Inc.
305 This is free software, licensed under:
307 The Apache License, Version 2.0, January 2004
309perl v5.34.0 2021-07-22 MongoDB::Cursor(3)