# `cursor` – Tools for iterating over MongoDB query results

Cursor class to iterate over Mongo query results.

class pymongo.cursor.CursorType
  NON_TAILABLE = 0

    The standard cursor type.

  TAILABLE = 2

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

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

    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 (int | slice) – An integer or slice index to be applied to this cursor

    Return type:

      _DocumentType | Cursor[_DocumentType]

  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:

      _DocumentType

  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. Raises `OperationFailure` if the provided hint requires an index that does not exist on this collection, and 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 is `None` any existing hint for this query is cleared. The last hint applied to this cursor takes precedence over all others.

    Parameters:

      index (str | Sequence[str | Tuple[str, int | str | Mapping[str, Any]]] | Mapping[str, Any] | None) – index to hint on (as an index specifier)

    Return type:

      Cursor[_DocumentType]

  limit(limit)

    Limits the number of results to be returned by this cursor.

    Raises `TypeError` if limit is not an integer. 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 (int) – the number of results to return

    Return type:

      Cursor[_DocumentType]

    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 ensure the query uses the expected index and starting in MongoDB 4.2 `hint()` will be required.

    Parameters:

      spec (Sequence[str | Tuple[str, int | str | Mapping[str, Any]]] | Mapping[str, Any]) – a list of field, limit pairs specifying the exclusive upper bound for all keys of a specific index in order.

    Return type:

      Cursor[_DocumentType]

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

    Added 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 or `None`. Raises `InvalidOperation` if this `Cursor` has already been used.

    Note

    max_await_time_ms requires server version >= 3.2

    Parameters:

      max_await_time_ms (int | None) – the time limit after which the operation is aborted

    Return type:

      Cursor[_DocumentType]

    Added in version 3.2.

  max_scan(max_scan)

    DEPRECATED - Limit the number of documents to scan when performing the query.

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

    Parameters:

      max_scan (int | None) – the maximum number of documents to scan

    Return type:

      Cursor[_DocumentType]

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

  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 is `None` no limit is applied.

    Raises `TypeError` if max_time_ms is not an integer or `None`. Raises `InvalidOperation` if this `Cursor` has already been used.

    Parameters:

      max_time_ms (int | None) – the time limit after which the operation is aborted

    Return type:

      Cursor[_DocumentType]

  min(spec)

    Adds `min` operator that specifies lower bound for specific index.

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

    Parameters:

      spec (Sequence[str | Tuple[str, int | str | Mapping[str, Any]]] | Mapping[str, Any]) – a list of field, limit pairs specifying the inclusive lower bound for all keys of a specific index in order.

    Return type:

      Cursor[_DocumentType]

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

    Added in version 2.7.

  next()

    Advance the cursor.

    Return type:

      _DocumentType

  remove_option(mask)

    Unset arbitrary query flags using a bitmask.

    To unset the tailable flag: cursor.remove_option(2)

    Parameters:

      mask (int)

    Return type:

      Cursor[_DocumentType]

  property retrieved: int

    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.

    Return type:

      Cursor[_DocumentType]

  property session: ClientSession | None

    The cursor’s `ClientSession`, or None.

    Added in version 3.6.

  skip(skip)

    Skips the first skip results of this cursor.

    Raises `TypeError` if skip is not an integer. Raises `ValueError` if skip is less than `0`. Raises `InvalidOperation` if this `Cursor` has already been used. The last skip applied to this cursor takes precedence.

    Parameters:

      skip (int) – the number of results to skip

    Return type:

      Cursor[_DocumentType]

  sort(key_or_list, direction=None)

    Sorts this cursor’s results.

    Pass a field name and a direction, either `ASCENDING` 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. If just a name is given, `ASCENDING` will be inferred:

        for doc in collection.find().sort([
                'field1',
                ('field2', pymongo.DESCENDING)]):
            print(doc)

    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)

    For more advanced text search functionality, see MongoDB’s Atlas Search.

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

    Parameters:

      - key_or_list (str | Sequence[str | Tuple[str, int | str | Mapping[str, Any]]] | Mapping[str, Any]) – a single key or a list of (key, direction) pairs specifying the keys to sort on

      - direction (int | str | None) – only used if key_or_list is a single key, if not given `ASCENDING` is assumed

    Return type:

      Cursor[_DocumentType]

  to_list(length=None)

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

    To use:

        >>> cursor.to_list()

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

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

  where(code)

    Adds a $where clause to this query.

    The code argument must be an instance of `str` or `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. For example:

        # Find all documents where field "a" is less than "b" plus "c".
        for doc in db.test.find().where('this.a < (this.b + this.c)'):
            print(doc)

    Raises `TypeError` if code is not an instance of `str`. Raises `InvalidOperation` if this `Cursor` has already been used. Only the last call to `where()` applied to a `Cursor` has any effect.

    Note

    MongoDB 4.4 drops support for `Code` with scope variables. Consider using $expr instead.

    Parameters:

      code (str | Code) – JavaScript expression to use as a filter

    Return type:

      Cursor[_DocumentType]

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, 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, allow_disk_use=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.

  Parameters:

    - collection (Collection[_DocumentType])

    - args (Any)

    - kwargs (Any)