MongoDB::Cursor(3pm)

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

NAME

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

SYNOPSIS

9           while (my $object = $cursor->next) {
10               ...
11           }
12
13           my @objects = $cursor->all;
14
15   Multithreading
16       Cloning instances of this class is disabled in Perl 5.8.7+, so forked
17       threads will have to create their own database queries.
18

STATIC ATTRIBUTES

24   slave_okay
25           $MongoDB::Cursor::slave_okay = 1;
26
27       Whether it is okay to run queries on the slave.  Defaults to 0.
28
29   timeout
30       Deprecated, use MongoDB::Connection::query_timeout instead.
31
32       How many milliseconds to wait for a response from the server.  Set to
33       30000 (30 seconds) by default.  -1 waits forever (or until TCP times
34       out, which is usually a long time).
35
36       This value is overridden by "MongoDB::Connection::query_timeout" and
37       never used.
38

ATTRIBUTES

40   started_iterating
41       If this cursor has queried the database yet. Methods mofifying the
42       query will complain if they are called after the database is queried.
43
44   immortal
45           $cursor->immortal(1);
46
47       Ordinarily, a cursor "dies" on the database server after a certain
48       length of time (approximately 10 minutes), to prevent inactive cursors
49       from hogging resources.  This option sets that a cursor should not die
50       until all of its results have been fetched or it goes out of scope in
51       Perl.
52
53       Boolean value, defaults to 0.
54
55   tailable
56           $cursor->tailable(1);
57
58       If a cursor should be tailable.  Tailable cursors can only be used on
59       capped collections and are similar to the "tail -f" command: they never
60       die and keep returning new results as more is added to a collection.
61
62       They are often used for getting log messages.
63
64       Boolean value, defaults to 0.
65
66   slave_okay
67           $cursor->slave_okay(1);
68
69       If a query can be done on a slave database server.
70
71       Boolean value, defaults to 0.
72

METHODS

74   fields (\%f)
75           $coll->insert({name => "Fred", age => 20});
76           my $cursor = $coll->query->fields({ name => 1 });
77           my $obj = $cursor->next;
78           $obj->{name}; "Fred"
79           $obj->{age}; # undef
80
81       Selects which fields are returned.  The default is all fields.  _id is
82       always returned.
83
84   sort ($order)
85           # sort by name, descending
86           my $sort = {"name" => -1};
87           $cursor = $coll->query->sort($sort);
88
89       Adds a sort to the query.  Argument is either a hash reference or a
90       Tie::IxHash.  Returns this cursor for chaining operations.
91
92   limit ($num)
93           $per_page = 20;
94           $cursor = $coll->query->limit($per_page);
95
96       Returns a maximum of N results.  Returns this cursor for chaining
97       operations.
98
99   skip ($num)
100           $page_num = 7;
101           $per_page = 100;
102           $cursor = $coll->query->limit($per_page)->skip($page_num * $per_page);
103
104       Skips the first N results. Returns this cursor for chaining operations.
105
106       See also core documentation on limit:
107       <http://dochub.mongodb.org/core/limit>.
108
109   snapshot
110           my $cursor = $coll->query->snapshot;
111
112       Uses snapshot mode for the query.  Snapshot mode assures no duplicates
113       are returned, or objects missed, which were present at both the start
114       and end of the query's execution (if an object is new during the query,
115       or deleted during the query, it may or may not be returned, even with
116       snapshot mode).  Note that short query responses (less than 1MB) are
117       always effectively snapshotted.  Currently, snapshot mode may not be
118       used with sorting or explicit hints.
119
120   hint
121           my $cursor = $coll->query->hint({'x' => 1});
122
123       Force Mongo to use a specific index for a query.
124
125   explain
126           my $explanation = $cursor->explain;
127
128       This will tell you the type of cursor used, the number of records the
129       DB had to examine as part of this query, the number of records returned
130       by the query, and the time in milliseconds the query took to execute.
131       Requires boolean package.
132
133       "explain" resets the cursor, so calling "next" or "has_next" after an
134       explain will requery the database.
135
136       See also core documentation on explain:
137       <http://dochub.mongodb.org/core/explain>.
138
139   count($all?)
140           my $num = $cursor->count;
141           my $num = $cursor->skip(20)->count(1);
142
143       Returns the number of document this query will return.  Optionally
144       takes a boolean parameter, indicating that the cursor's limit and skip
145       fields should be used in calculating the count.
146
147   reset
148       Resets the cursor.  After being reset, pre-query methods can be called
149       on the cursor (sort, limit, etc.) and subsequent calls to next,
150       has_next, or all will re-query the database.
151
152   has_next
153           while ($cursor->has_next) {
154               ...
155           }
156
157       Checks if there is another result to fetch.
158
159   next
160           while (my $object = $cursor->next) {
161               ...
162           }
163
164       Returns the next object in the cursor. Will automatically fetch more
165       data from the server if necessary. Returns undef if no more data is
166       available.
167
168   all
169           my @objects = $cursor->all;
170
171       Returns a list of all objects in the result.
172

AUTHOR

174         Kristina Chodorow <kristina@mongodb.org>
175
176
177
178perl v5.12.3                      2011-01-19                MongoDB::Cursor(3)

NAME

SYNOPSIS

SEE ALSO

STATIC ATTRIBUTES

ATTRIBUTES

METHODS

AUTHOR