cursor
– Tools for iterating over MongoDB query results¶
Cursor class to iterate over Mongo query results.
-
class
pymongo.cursor.
CursorType
¶ -
NON_TAILABLE
¶ The standard cursor type.
-
TAILABLE
¶ The tailable cursor type.
Tailable cursors are only for use with capped collections. They are not closed when the last data is retrieved but are kept open and the cursor location marks the final document position. If more data is received iteration of the cursor will continue from the last document received.
-
TAILABLE_AWAIT
¶ A tailable cursor with the await option set.
Creates a tailable cursor that will wait for a few seconds after returning the full result set so that it can capture and return additional data added during the query.
-
EXHAUST
¶ An exhaust cursor.
MongoDB will stream batched results to the client without waiting for the client to request each batch, reducing latency.
-
-
class
pymongo.cursor.
Cursor
(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, batch_size=0, manipulate=True, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None)¶ Create a new cursor.
Should not be called directly by application developers - see
find()
instead.-
c[index]
See
__getitem__()
.
-
__getitem__
(index)¶ Get a single document or a slice of documents from this cursor.
Raises
InvalidOperation
if this cursor has already been used.To get a single document use an integral index, e.g.:
>>> db.test.find()[50]
An
IndexError
will be raised if the index is negative or greater than the amount of documents in this cursor. Any limit previously 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 of20
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). RaisesIndexError
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
-
add_option
(mask)¶ Set arbitrary query flags using a bitmask.
To set the tailable flag: cursor.add_option(2)
-
address
¶ The (host, port) of the server used, or None.
Changed in version 3.0: Renamed from “conn_id”.
-
alive
¶ Does this cursor have the potential to return more data?
This is mostly useful with tailable cursors since they will stop iterating even though they may return more results in the future.
With regular cursors, simply use a for loop instead of
alive
:for doc in collection.find(): print(doc)
-
batch_size
(batch_size)¶ Limits the number of documents returned in one batch. Each batch requires a round trip to the server. It can be adjusted to optimize performance and limit data transfer.
Note
batch_size can not override MongoDB’s internal limits on the amount of data it will return to the client in a single batch (i.e if you set batch size to 1,000,000,000, MongoDB will currently only return 4-16MB of results per batch).
Raises
TypeError
if batch_size is not an integer. RaisesValueError
if batch_size is less than0
. RaisesInvalidOperation
if thisCursor
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.
-
clone
()¶ 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.
-
close
()¶ Explicitly close / kill this cursor.
-
collation
(collation)¶ Adds a
Collation
to this query.This option is only supported on MongoDB 3.4 and above.
Raises
TypeError
if collation is not an instance ofCollation
or adict
. RaisesInvalidOperation
if thisCursor
has already been used. Only the last collation applied to this cursor has any effect.Parameters: - collation: An instance of
Collation
.
- collation: An instance of
-
collection
¶ The
Collection
that thisCursor
is iterating.
-
comment
(comment)¶ Adds a ‘comment’ to the cursor.
http://docs.mongodb.org/manual/reference/operator/comment/
Parameters: - comment: A string or document
New in version 2.7.
-
count
(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
limit()
andskip()
into account by default - set with_limit_and_skip toTrue
if that is the desired behavior. RaisesOperationFailure
on a database error.When used with MongoDB >= 2.6,
count()
uses anyhint()
applied to the query. In the following example the hint is passed to the count command:collection.find({‘field’: ‘value’}).hint(‘field_1’).count()The
count()
method obeys theread_preference
of theCollection
instance on whichfind()
was called.Parameters: Note
The with_limit_and_skip parameter requires server version >= 1.1.4-
-
cursor_id
¶ Returns the id of the cursor
Useful if you need to manage cursor ids and want to handle killing cursors manually using
kill_cursors()
New in version 2.2.
-
distinct
(key)¶ Get a list of distinct values for key among all documents in the result set of this query.
Raises
TypeError
if key is not an instance ofbasestring
(str
in python 3).The
distinct()
method obeys theread_preference
of theCollection
instance on whichfind()
was called.Parameters: - key: name of key for which we want to get the distinct values
-
explain
()¶ Returns an explain plan record for this cursor.
-
hint
(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
InvalidOperation
if this cursor has already been used.index should be an index as passed to
create_index()
(e.g.[('field', ASCENDING)]
) or the name of the index. If index isNone
any existing hint for this query is cleared. The last hint applied to this cursor takes precedence over all others.Parameters: - index: index to hint on (as an index specifier)
Changed in version 2.8: The
hint()
method accepts the name of the index.
-
limit
(limit)¶ Limits the number of results to be returned by this cursor.
Raises
TypeError
if limit is not an integer. RaisesInvalidOperation
if thisCursor
has already been used. The last limit applied to this cursor takes precedence. A limit of0
is equivalent to no limit.Parameters: - limit: the number of results to return
-
max
(spec)¶ Adds max operator that specifies upper bound for specific index.
Parameters: - spec: a list of field, limit pairs specifying the exclusive upper bound for all keys of a specific index in order.
New in version 2.7.
-
max_await_time_ms
(max_await_time_ms)¶ Specifies a time limit for a getMore operation on a
TAILABLE_AWAIT
cursor. For all other types of cursor max_await_time_ms is ignored.Raises
TypeError
if max_await_time_ms is not an integer orNone
. RaisesInvalidOperation
if thisCursor
has already been used.Note
max_await_time_ms requires server version >= 3.2
Parameters: - max_await_time_ms: the time limit after which the operation is aborted
New in version 3.2.
-
max_scan
(max_scan)¶ Limit the number of documents to scan when performing the query.
Raises
InvalidOperation
if this cursor has already been used. Only the lastmax_scan()
applied to this cursor has any effect.Parameters: - max_scan: the maximum number of documents to scan
-
max_time_ms
(max_time_ms)¶ Specifies a time limit for a query operation. If the specified time is exceeded, the operation will be aborted and
ExecutionTimeout
is raised. If max_time_ms isNone
no limit is applied.Raises
TypeError
if max_time_ms is not an integer orNone
. RaisesInvalidOperation
if thisCursor
has already been used.Parameters: - max_time_ms: the time limit after which the operation is aborted
-
min
(spec)¶ Adds min operator that specifies lower bound for specific index.
Parameters: - spec: a list of field, limit pairs specifying the inclusive lower bound for all keys of a specific index in order.
New in version 2.7.
-
next
()¶ Advance the cursor.
-
remove_option
(mask)¶ Unset arbitrary query flags using a bitmask.
To unset the tailable flag: cursor.remove_option(2)
-
retrieved
¶ The number of documents retrieved so far.
-
rewind
()¶ Rewind this cursor to its 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.
-
session
¶ The cursor’s
ClientSession
, or None.New in version 3.6.
-
skip
(skip)¶ Skips the first skip results of this cursor.
Raises
TypeError
if skip is not an integer. RaisesValueError
if skip is less than0
. RaisesInvalidOperation
if thisCursor
has already been used. The last skip applied to this cursor takes precedence.Parameters: - skip: the number of results to skip
-
sort
(key_or_list, direction=None)¶ Sorts this cursor’s results.
Pass a field name and a direction, either
ASCENDING
orDESCENDING
:for doc in collection.find().sort('field', pymongo.ASCENDING): print(doc)
To sort by multiple fields, pass a list of (key, direction) pairs:
for doc in collection.find().sort([ ('field1', pymongo.ASCENDING), ('field2', pymongo.DESCENDING)]): print(doc)
Beginning with MongoDB version 2.6, text search results can be sorted by relevance:
cursor = db.test.find( {'$text': {'$search': 'some words'}}, {'score': {'$meta': 'textScore'}}) # Sort by 'score' field. cursor.sort([('score', {'$meta': 'textScore'})]) for doc in cursor: print(doc)
Raises
InvalidOperation
if this cursor has already been used. Only the lastsort()
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
ASCENDING
is assumed
-
where
(code)¶ Adds a $where clause to this query.
The code argument must be an instance of
basestring
(str
in python 3) orCode
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
TypeError
if code is not an instance ofbasestring
(str
in python 3). RaisesInvalidOperation
if thisCursor
has already been used. Only the last call towhere()
applied to aCursor
has any effect.Parameters: - code: JavaScript expression to use as a filter
-
-
class
pymongo.cursor.
RawBatchCursor
(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None)¶ Create a new cursor / iterator over raw batches of BSON data.
Should not be called directly by application developers - see
find_raw_batches()
instead.