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, 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, session=None, allow_disk_use=None)

Create a new cursor.

Should not be called directly by application developers - see find() instead.

See also

The MongoDB documentation on cursors.

Parameters:

  • collection (Collection[_DocumentType])

  • filter (Optional[Mapping[str, Any]])

  • projection (Optional[Union[Mapping[str, Any], Iterable[str]]])

  • skip (int)

  • limit (int)

  • no_cursor_timeout (bool)

  • cursor_type (int)

  • sort (Optional[_Sort])

  • allow_partial_results (bool)

  • oplog_replay (bool)

  • batch_size (int)

  • collation (Optional[_CollationIn])

  • hint (Optional[_Hint])

  • max_scan (Optional[int])

  • max_time_ms (Optional[int])

  • max (Optional[_Sort])

  • min (Optional[_Sort])

  • return_key (Optional[bool])

  • show_record_id (Optional[bool])

  • snapshot (Optional[bool])

  • comment (Optional[Any])

  • session (Optional[ClientSession])

  • allow_disk_use (Optional[bool])

  • let (Optional[bool])

c[index]

See __getitem__() and read the warning.

__getitem__(index: int) → _DocumentType
__getitem__(index: slice) → Cursor[_DocumentType]

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

Warning

A Cursor is not a Python list. Each index access or slice requires that a new query be run using skip and limit. Do not iterate the cursor using index accesses. The following example is extremely inefficient and may return surprising results:

cursor = db.collection.find()
# Warning: This runs a new query for each document.
# Don't do this!
for idx in range(10):
    print(cursor[idx])

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 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 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

add_option(mask)

Set arbitrary query flags using a bitmask.

To set the tailable flag: cursor.add_option(2)

Parameters:

mask (int)

Return type:

Cursor[_DocumentType]

property address: Tuple[str, int | None] | None

The (host, port) of the server used, or None.

Changed in version 3.0: Renamed from “conn_id”.

property alive: bool

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 an asynchronous for loop instead of alive:

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

Note

Even if alive is True, next() can raise StopIteration. alive can also be True while iterating a cursor from a failed server. In this case alive will return False after next() fails to retrieve the next batch of results from the server.

allow_disk_use(allow_disk_use)

Specifies whether MongoDB can use temporary disk files while processing a blocking sort operation.

Raises TypeError if allow_disk_use is not a boolean.

Note

allow_disk_use requires server version >= 4.4

Parameters:

allow_disk_use (bool) – if True, MongoDB may use temporary disk files to store data exceeding the system memory limit while processing a blocking sort operation.

Return type:

Cursor[_DocumentType]

Added in version 3.11.

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. Raises ValueError if batch_size is less than 0. Raises InvalidOperation if this Cursor has already been used. The last batch_size applied to this cursor takes precedence.

Parameters:

batch_size (int) – The size of each batch of results requested.

Return type:

Cursor[_DocumentType]

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.

Return type:

Cursor[_DocumentType]

close()

Explicitly close / kill this cursor.

Return type:

None

collation(collation)

Adds a Collation to this query.

Raises TypeError if collation is not an instance of Collation or a dict. Raises InvalidOperation if this Cursor has already been used. Only the last collation applied to this cursor has any effect.

Parameters:

collation (Optional[_CollationIn]) – An instance of Collation.

Return type:

Cursor[_DocumentType]

property collection: Collection[_DocumentType]

The Collection that this Cursor is iterating.

comment(comment)

Adds a ‘comment’ to the cursor.

http://mongodb.com/docs/manual/reference/operator/comment/

Parameters:

comment (Any) – A string to attach to the query to help interpret and trace the operation in the server logs and in profile data.

Return type:

Cursor[_DocumentType]

Added in version 2.7.

property cursor_id: int | None

Returns the id of the cursor.

Added 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 of str.

The distinct() method obeys the read_preference of the Collection instance on which find() was called.

Parameters:

key (str) – name of key for which we want to get the distinct values

Return type:

list[Any]

See also

pymongo.collection.Collection.distinct()

explain()

Returns an explain plan record for this cursor.

Note

This method uses the default verbosity mode of the explain command, allPlansExecution. To use a different verbosity use command() to run the explain command directly.

Note

The timeout of this method can be set using pymongo.timeout().

See also

The MongoDB documentation on explain.

Return type: