pymongo::cursor::Cursor Class Reference
List of all members.
Detailed Description
A cursor / iterator over Mongo query results.
Definition at line 34 of file cursor.py.
Member Function Documentation
| def pymongo::cursor::Cursor::__check_okay_to_chain |
( |
|
self |
) |
[private] |
Check if it is okay to chain more options onto this cursor.
Definition at line 201 of file cursor.py.
| def pymongo::cursor::Cursor::__del__ |
( |
|
self |
) |
|
| def pymongo::cursor::Cursor::__die |
( |
|
self |
) |
[private] |
| def pymongo::cursor::Cursor::__getitem__ |
( |
|
self, |
|
|
|
index | |
|
) |
| | |
Get a single document or a slice of documents from this cursor.
Raises :class:`~pymongo.errors.InvalidOperation` if this
cursor has already been used.
To get a single document use an integral index, e.g.::
>>> db.test.find()[50]
An :class:`IndexError` will be raised if the index is negative
or greater than the amount of documents in this cursor. Any
limit applied to this cursor will be ignored.
To get a slice of documents use a slice index, e.g.::
>>> db.test.find()[20:25]
This will return this cursor with a limit of ``5`` and skip of
``20`` applied. Using a slice index will override any prior
limits or skips applied to this cursor (including those
applied through previous calls to this method). Raises
:class:`IndexError` when the slice has a step, a negative
start value, or a stop value less than or equal to the start
value.
:Parameters:
- `index`: An integer or slice index to be applied to this cursor
Definition at line 269 of file cursor.py.
| def pymongo::cursor::Cursor::__init__ |
( |
|
self, |
|
|
|
collection, |
|
|
|
spec = None, |
|
|
|
fields = None, |
|
|
|
skip = 0, |
|
|
|
limit = 0, |
|
|
|
timeout = True, |
|
|
|
snapshot = False, |
|
|
|
tailable = False, |
|
|
|
sort = None, |
|
|
|
max_scan = None, |
|
|
|
as_class = None, |
|
|
|
_must_use_master = False, |
|
|
|
_is_command = False, |
|
|
|
kwargs | |
|
) |
| | |
Create a new cursor.
Should not be called directly by application developers - see
:meth:`~pymongo.collection.Collection.find` instead.
.. mongodoc:: cursors
Definition at line 38 of file cursor.py.
| def pymongo::cursor::Cursor::__iter__ |
( |
|
self |
) |
|
| def pymongo::cursor::Cursor::__query_options |
( |
|
self |
) |
[private] |
Get the query options string to use for this query.
Definition at line 189 of file cursor.py.
| def pymongo::cursor::Cursor::__query_spec |
( |
|
self |
) |
[private] |
Get the spec to use for a query.
Definition at line 171 of file cursor.py.
| def pymongo::cursor::Cursor::__send_message |
( |
|
self, |
|
|
|
message | |
|
) |
| | [private] |
Send a query or getmore message and handles the response.
Definition at line 511 of file cursor.py.
| def pymongo::cursor::Cursor::_refresh |
( |
|
self |
) |
[private] |
Refreshes the cursor with more data from Mongo.
Returns the length of self.__data after refresh. Will exit early if
self.__data is already non-empty. Raises OperationFailure when the
cursor cannot be refreshed due to an error on the query.
Definition at line 549 of file cursor.py.
| def pymongo::cursor::Cursor::alive |
( |
|
self |
) |
|
Does this cursor have the potential to return more data?
This is mostly useful with `tailable cursors
<http://www.mongodb.org/display/DOCS/Tailable+Cursors>`_
since they will stop iterating even though they *may* return more
results in the future.
.. versionadded:: 1.5
Definition at line 582 of file cursor.py.
| def pymongo::cursor::Cursor::batch_size |
( |
|
self, |
|
|
|
batch_size | |
|
) |
| | |
Set the size for batches of results returned by this cursor.
Raises :class:`TypeError` if `batch_size` is not an instance
of :class:`int`. Raises :class:`ValueError` if `batch_size` is
less than ``0``. Raises
:class:`~pymongo.errors.InvalidOperation` if this
:class:`Cursor` has already been used. The last `batch_size`
applied to this cursor takes precedence.
:Parameters:
- `batch_size`: The size of each batch of results requested.
.. versionadded:: 1.9
Definition at line 228 of file cursor.py.
| def pymongo::cursor::Cursor::clone |
( |
|
self |
) |
|
Get a clone of this cursor.
Returns a new Cursor instance with options matching those that have
been set on the current instance. The clone will be completely
unevaluated, even if the current instance has been partially or
completely evaluated.
Definition at line 143 of file cursor.py.
| def pymongo::cursor::Cursor::collection |
( |
|
self |
) |
|
The :class:`~pymongo.collection.Collection` that this
:class:`Cursor` is iterating.
.. versionadded:: 1.1
Definition at line 114 of file cursor.py.
| def pymongo::cursor::Cursor::count |
( |
|
self, |
|
|
|
with_limit_and_skip = False | |
|
) |
| | |
Get the size of the results set for this query.
Returns the number of documents in the results set for this query. Does
not take :meth:`limit` and :meth:`skip` into account by default - set
`with_limit_and_skip` to ``True`` if that is the desired behavior.
Raises :class:`~pymongo.errors.OperationFailure` on a database error.
:Parameters:
- `with_limit_and_skip` (optional): take any :meth:`limit` or
:meth:`skip` that has been applied to this cursor into account when
getting the count
.. note:: The `with_limit_and_skip` parameter requires server
version **>= 1.1.4-**
.. versionadded:: 1.1.1
The `with_limit_and_skip` parameter.
:meth:`~pymongo.cursor.Cursor.__len__` was deprecated in favor of
calling :meth:`count` with `with_limit_and_skip` set to ``True``.
Definition at line 379 of file cursor.py.
| def pymongo::cursor::Cursor::distinct |
( |
|
self, |
|
|
|
key | |
|
) |
| | |
Get a list of distinct values for `key` among all documents
in the result set of this query.
Raises :class:`TypeError` if `key` is not an instance of
:class:`basestring`.
:Parameters:
- `key`: name of key for which we want to get the distinct values
.. note:: Requires server version **>= 1.1.3+**
.. seealso:: :meth:`pymongo.collection.Collection.distinct`
.. versionadded:: 1.2
Definition at line 415 of file cursor.py.
| def pymongo::cursor::Cursor::explain |
( |
|
self |
) |
|
Returns an explain plan record for this cursor.
.. mongodoc:: explain
Definition at line 442 of file cursor.py.
| def pymongo::cursor::Cursor::hint |
( |
|
self, |
|
|
|
index | |
|
) |
| | |
Adds a 'hint', telling Mongo the proper index to use for the query.
Judicious use of hints can greatly improve query
performance. When doing a query on multiple fields (at least
one of which is indexed) pass the indexed field as a hint to
the query. Hinting will not do anything if the corresponding
index does not exist. Raises
:class:`~pymongo.errors.InvalidOperation` if this cursor has
already been used.
`index` should be an index as passed to
:meth:`~pymongo.collection.Collection.create_index`
(e.g. ``[('field', ASCENDING)]``). If `index`
is ``None`` any existing hints for this query are cleared. The
last hint applied to this cursor takes precedence over all
others.
:Parameters:
- `index`: index to hint on (as an index specifier)
Definition at line 455 of file cursor.py.
| def pymongo::cursor::Cursor::limit |
( |
|
self, |
|
|
|
limit | |
|
) |
| | |
Limits the number of results to be returned by this cursor.
Raises TypeError if limit is not an instance of int. Raises
InvalidOperation if this cursor has already been used. The
last `limit` applied to this cursor takes precedence. A limit
of ``0`` is equivalent to no limit.
:Parameters:
- `limit`: the number of results to return
.. mongodoc:: limit
Definition at line 207 of file cursor.py.
| def pymongo::cursor::Cursor::max_scan |
( |
|
self, |
|
|
|
max_scan | |
|
) |
| | |
Limit the number of documents to scan when performing the query.
Raises :class:`~pymongo.errors.InvalidOperation` if this
cursor has already been used. Only the last :meth:`max_scan`
applied to this cursor has any effect.
:Parameters:
- `max_scan`: the maximum number of documents to scan
.. note:: Requires server version **>= 1.5.1**
.. versionadded:: 1.7
Definition at line 338 of file cursor.py.
| def pymongo::cursor::Cursor::next |
( |
|
self |
) |
|
| def pymongo::cursor::Cursor::rewind |
( |
|
self |
) |
|
Rewind this cursor to it's unevaluated state.
Reset this cursor if it has been partially or completely evaluated.
Any options that are present on the cursor will remain in effect.
Future iterating performed on this cursor will cause new queries to
be sent to the server, even if the resultant data has already been
retrieved by this cursor.
Definition at line 126 of file cursor.py.
| def pymongo::cursor::Cursor::skip |
( |
|
self, |
|
|
|
skip | |
|
) |
| | |
Skips the first `skip` results of this cursor.
Raises TypeError if skip is not an instance of int. Raises
InvalidOperation if this cursor has already been used. The last `skip`
applied to this cursor takes precedence.
:Parameters:
- `skip`: the number of results to skip
Definition at line 252 of file cursor.py.
| def pymongo::cursor::Cursor::sort |
( |
|
self, |
|
|
|
key_or_list, |
|
|
|
direction = None | |
|
) |
| | |
Sorts this cursor's results.
Takes either a single key and a direction, or a list of (key,
direction) pairs. The key(s) must be an instance of ``(str,
unicode)``, and the direction(s) must be one of
(:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`). Raises
:class:`~pymongo.errors.InvalidOperation` if this cursor has
already been used. Only the last :meth:`sort` applied to this
cursor has any effect.
:Parameters:
- `key_or_list`: a single key or a list of (key, direction)
pairs specifying the keys to sort on
- `direction` (optional): only used if `key_or_list` is a single
key, if not given :data:`~pymongo.ASCENDING` is assumed
Definition at line 356 of file cursor.py.
| def pymongo::cursor::Cursor::where |
( |
|
self, |
|
|
|
code | |
|
) |
| | |
Adds a $where clause to this query.
The `code` argument must be an instance of :class:`basestring`
or :class:`~bson.code.Code` containing a JavaScript
expression. This expression will be evaluated for each
document scanned. Only those documents for which the
expression evaluates to *true* will be returned as
results. The keyword *this* refers to the object currently
being scanned.
Raises :class:`TypeError` if `code` is not an instance of
:class:`basestring`. Raises
:class:`~pymongo.errors.InvalidOperation` if this
:class:`Cursor` has already been used. Only the last call to
:meth:`where` applied to a :class:`Cursor` has any effect.
:Parameters:
- `code`: JavaScript expression to use as a filter
Definition at line 484 of file cursor.py.
Member Data Documentation
The documentation for this class was generated from the following file:
