`command_cursor` – Tools for iterating over MongoDB command results¶

Warning

This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, please file a Jira ticket in the “Python Driver” project at https://jira.mongodb.org/browse/PYTHON.

CommandCursor class to iterate over command results.

class pymongo.asynchronous.command_cursor.AsyncCommandCursor(collection, cursor_info, address, batch_size=0, max_await_time_ms=None, session=None, explicit_session=False, comment=None)¶

Create a new command cursor.

Parameters:

collection (AsyncCollection[_DocumentType])
cursor_info (Mapping[str, Any])
address (Optional[_Address])
batch_size (int)
max_await_time_ms (Optional[int])
session (Optional[AsyncClientSession])
explicit_session (bool)
comment (Any)

property address: Tuple[str, int | None] | None¶: The (host, port) of the server used, or None.

Added in version 3.0.

property alive: bool¶

Does this cursor have the potential to return more data?

Even if alive is True, next() can raise StopIteration. Best to use a for loop:

async for doc in collection.aggregate(pipeline):
    print(doc)

Note

alive can 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.

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.

Parameters:: batch_size (int) – The size of each batch of results requested.
Return type:: AsyncCommandCursor[_DocumentType]

async close()¶

Explicitly close / kill this cursor.

Return type:: None

property cursor_id: int¶: Returns the id of the cursor.

async next()¶

Advance the cursor.

Return type:: _DocumentType

property session: AsyncClientSession | None¶: The cursor’s AsyncClientSession, or None.

Added in version 3.6.

async to_list(length=None)¶

Converts the contents of this cursor to a list more efficiently than [doc async for doc in cursor].

To use:

>>> await cursor.to_list()

Or, so read at most n items from the cursor:

>>> await cursor.to_list(n)

If the cursor is empty or has no more results, an empty list will be returned.

Added in version 4.9.

Parameters:: length (int | None)
Return type:: list[_DocumentType]

async try_next()¶

Advance the cursor without blocking indefinitely.

This method returns the next document without waiting indefinitely for data.

If no document is cached locally then this method runs a single getMore command. If the getMore yields any documents, the next document is returned, otherwise, if the getMore returns no documents (because there is no additional data) then None is returned.

Returns:: The next document or None when no document is available after running a single getMore or when the cursor is closed.
Return type:: _DocumentType | None

Added in version 4.5.

class pymongo.asynchronous.command_cursor.AsyncRawBatchCommandCursor(collection, cursor_info, address, batch_size=0, max_await_time_ms=None, session=None, explicit_session=False, comment=None)¶

Create a new cursor / iterator over raw batches of BSON data.

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

command_cursor – Tools for iterating over MongoDB command results¶

`command_cursor` – Tools for iterating over MongoDB command results¶