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 notclosed when the last data is retrieved but are kept open and the cursorlocation marks the final document position. If more data is receivediteration 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 returningthe full result set so that it can capture and return additional data addedduring the query.

• EXHAUST
• An exhaust cursor.

MongoDB will stream batched results to the client without waiting for theclient 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 - seefind() instead.

See also

The MongoDB documentation on

cursors

• c[index]

• See getitem().

• getitem(index)

• Get a single document or a slice of documents from this cursor.

Raises InvalidOperation if thiscursor 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 negativeor greater than the amount of documents in this cursor. Anylimit 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 priorlimits or skips applied to this cursor (including thoseapplied through previous calls to this method). RaisesIndexError when the slice has a step, a negativestart value, or a stop value less than or equal to the startvalue.

Parameters:

- _index_: An integer or slice index to be applied to this cursor

• addoption(_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 cursorssince they will stop iterating even though they may return moreresults in the future.

With regular cursors, simply use a for loop instead of alive:

for doc in collection.find():
    print(doc)

Note

Even if alive is True, next() can raiseStopIteration. alive can also be True while iteratinga cursor from a failed server. In this case alive willreturn False after next() fails to retrieve the next batchof results from the server.

• batchsize(_batch_size)
• Limits the number of documents returned in one batch. Each batchrequires a round trip to the server. It can be adjusted to optimizeperformance and limit data transfer.

Note

batch_size can not override MongoDB’s internal limits on theamount of data it will return to the client in a single batch (i.eif you set batch size to 1,000,000,000, MongoDB will currently onlyreturn 4-16MB of results per batch).

Raises TypeError if batch_size is not an integer.Raises ValueError if batch_size is less than 0.Raises InvalidOperation 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 havebeen set on the current instance. The clone will be completelyunevaluated, even if the current instance has been partially orcompletely 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 a dict. RaisesInvalidOperation if this Cursor hasalready been used. Only the last collation applied to this cursor hasany effect.

Parameters:

- _collation_: An instance of [<code>Collation</code>]($f10fec00031f6158.md#pymongo.collation.Collation).

• 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 to attach to the query to help interpret andtrace the operation in the server logs and in profile data.

New in version 2.7.

• count(with_limit_and_skip=False)
• DEPRECATED - Get the size of the results set for this query.

The count() method is deprecated and not supported in atransaction. Please usecount_documents() instead.

Returns the number of documents in the results set for this query. Doesnot take limit() and skip() into account by default - setwith_limit_and_skip to True if that is the desired behavior.Raises OperationFailure on a database error.

When used with MongoDB >= 2.6, count() uses any hint()applied to the query. In the following example the hint is passed tothe count command:

collection.find({‘field’: ‘value’}).hint(‘field_1’).count()

The count() method obeys theread_preference of theCollection instance on whichfind() was called.

Parameters:

- _with_limit_and_skip_ (optional): take any [<code>limit()</code>](https://api.mongodb.com/python/current/api/pymongo/#pymongo.cursor.Cursor.limit) or[<code>skip()</code>](https://api.mongodb.com/python/current/api/pymongo/#pymongo.cursor.Cursor.skip) that has been applied to this cursor into account whengetting the count

Note

The with_limit_and_skip parameter requires serverversion >= 1.1.4-

Changed in version 3.7: Deprecated.

Changed in version 2.8: The count() method now supports hint().

• cursor_id
• Returns the id of the cursor

Useful if you need to manage cursor ids and want to handle killingcursors manually usingkill_cursors()

New in version 2.2.

• distinct(key)
• Get a list of distinct values for key among all documentsin 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

See also

pymongo.collection.Collection.distinct()

• explain()
• Returns an explain plan record for this cursor.

Note

Starting with MongoDB 3.2 explain() usesthe default verbosity mode of the explain command,allPlansExecution. To use a different verbosity usecommand() to run the explaincommand directly.

See also

The MongoDB documentation on

explain

• hint(index)
• Adds a ‘hint’, telling Mongo the proper index to use for the query.

Judicious use of hints can greatly improve queryperformance. When doing a query on multiple fields (at leastone of which is indexed) pass the indexed field as a hint tothe query. Raises OperationFailure if theprovided hint requires an index that does not exist on this collection,and raises InvalidOperation if this cursor hasalready been used.

index should be an index as passed tocreate_index()(e.g. [('field', ASCENDING)]) or the name of the index.If index is None any existing hint for this query iscleared. The last hint applied to this cursor takes precedenceover 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 this Cursorhas already been used. The last limit applied to this cursortakes precedence. A limit of 0 is equivalent to no limit.

Parameters:

- _limit_: the number of results to return

See also

The MongoDB documentation on

limit

• max(spec)
• Adds max operator that specifies upper bound for specific index.

When using max, hint() should also be configured to ensurethe query uses the expected index and starting in MongoDB 4.2hint() will be required.

Parameters:

- _spec_: a list of field, limit pairs specifying the exclusiveupper bound for all keys of a specific index in order.

Changed in version 3.8: Deprecated cursors that use max without a hint().

New in version 2.7.

• maxawait_time_ms(_max_await_time_ms)
• Specifies a time limit for a getMore operation on aTAILABLE_AWAIT cursor. For all othertypes of cursor max_await_time_ms is ignored.

Raises TypeError if max_await_time_ms is not an integer orNone. Raises InvalidOperation 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 isaborted

New in version 3.2.

• maxscan(_max_scan)
• DEPRECATED - Limit the number of documents to scan whenperforming the query.

Raises InvalidOperation if thiscursor has already been used. Only the last max_scan()applied to this cursor has any effect.

Parameters:

- _max_scan_: the maximum number of documents to scan

Changed in version 3.7: Deprecated max_scan(). Support for this option is deprecated inMongoDB 4.0. Use max_time_ms() instead to limit server sideexecution time.

• maxtime_ms(_max_time_ms)
• Specifies a time limit for a query operation. If the specifiedtime is exceeded, the operation will be aborted andExecutionTimeout is raised. If _max_time_ms_is None no limit is applied.

Raises TypeError if max_time_ms is not an integer or None.Raises InvalidOperation if this Cursorhas 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.

When using min, hint() should also be configured to ensurethe query uses the expected index and starting in MongoDB 4.2hint() will be required.

Parameters:

- _spec_: a list of field, limit pairs specifying the inclusivelower bound for all keys of a specific index in order.

Changed in version 3.8: Deprecated cursors that use min without a hint().

New in version 2.7.

• next()

• Advance the cursor.

• removeoption(_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 tobe sent to the server, even if the resultant data has already beenretrieved 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 than 0. RaisesInvalidOperation if this Cursor hasalready been used. The last skip applied to this cursor takesprecedence.

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, eitherASCENDING or DESCENDING:

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 besorted 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 hasalready been used. Only the last sort() applied to thiscursor 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 singlekey, if not given [<code>ASCENDING</code>]($93912a58b0c5f9d1.md#pymongo.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) or Codecontaining a JavaScript expression. This expression will beevaluated for each document scanned. Only those documentsfor which the expression evaluates to true will be returnedas results. The keyword this refers to the object currentlybeing 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 a Cursor 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.

See also

The MongoDB documentation on

cursors