neosqlite.collection.aggregation_cursor module¶

class neosqlite.collection.aggregation_cursor.AggregationCursor(collection: Collection, pipeline: list[dict[str, Any]], allowDiskUse: bool | None = None, batchSize: int | None = None, session: ClientSession | None = None, **kwargs: Any)[source]¶

Bases: object

A cursor that iterates over the results of an aggregation pipeline.

This cursor implements the same interface as PyMongo’s CommandCursor, allowing iteration over aggregation results.

__init__(collection: Collection, pipeline: list[dict[str, Any]], allowDiskUse: bool | None = None, batchSize: int | None = None, session: ClientSession | None = None, **kwargs: Any)[source]¶

Initialize the AggregationCursor.

Parameters:

collection – The collection to run the aggregation on
pipeline – The aggregation pipeline to execute
allowDiskUse – Ignored in NeoSQLite (kept for PyMongo compatibility)
batchSize – Batch size for results (kept for PyMongo compatibility)
session – A ClientSession for transactions
**kwargs – Additional keyword arguments for PyMongo compatibility

max_await_time_ms(max_await_time_ms: int | None) → AggregationCursor[source]¶

Set the maximum time to wait for new documents (for tailable cursors).

Parameters:: max_await_time_ms (int, optional) – The maximum time to wait in milliseconds.
Returns:: The cursor object with the max_await_time_ms applied.
Return type:: AggregationCursor

add_option(mask: int) → AggregationCursor[source]¶

Set query flags (bitmask) for this cursor.

Parameters:: mask (int) – The bitmask of options to set.
Returns:: The cursor object with the options applied.
Return type:: AggregationCursor

remove_option(mask: int) → AggregationCursor[source]¶

Unset query flags (bitmask) for this cursor.

Parameters:: mask (int) – The bitmask of options to unset.
Returns:: The cursor object with the options removed.
Return type:: AggregationCursor

property session: Any | None¶

Get the ClientSession associated with this cursor.

Returns:: The ClientSession, or None if no session is associated.
Return type:: Any | None

property cursor_id: int¶

Get the ID of this cursor.

Returns:: The cursor ID (always 0 for NeoSQLite).
Return type:: int

sort(key=None, reverse=False)[source]¶

Sort the results in-place.

Parameters:

key – A function to extract a comparison key from each element
reverse – If True, sort in descending order

Returns:

The cursor itself for chaining

_execute() → None[source]¶: Execute the aggregation pipeline and store the results.

_estimate_result_size() → int[source]¶

Estimate the size of the aggregation result in bytes.

Returns:: Estimated size in bytes

next() → dict[str, Any][source]¶

Get the next document in the aggregation result.

Returns:: The next document in the result set
Raises:: StopIteration – When there are no more documents

to_list() → list[dict[str, Any]][source]¶

Convert the cursor to a list of documents.

Returns:: A list containing all documents in the result set

batch_size(size: int) → AggregationCursor[source]¶

Set the batch size for memory-constrained processing.

Parameters:: size – The batch size to use
Returns:: The cursor itself for chaining

allow_disk_use(allow: bool = True) → AggregationCursor[source]¶

Enable or disable disk use for aggregation operations.

This method supports both method chaining (PyMongo fluent style) and is also settable via the allowDiskUse parameter to aggregate().

Parameters:: allow – Whether to allow disk use
Returns:: The cursor itself for chaining

use_quez(use_quez: bool = True) → AggregationCursor[source]¶

Enable or disable quez memory-constrained processing.

Parameters:: use_quez – Whether to use quez for memory-constrained processing
Returns:: The cursor itself for chaining

property retrieved: int¶

Return the number of documents retrieved from the cursor.

Returns:: The number of documents retrieved so far
Return type:: int

property alive: bool¶

Check if the cursor has more documents to iterate.

Returns:: True if the cursor may have more documents, False if exhausted
Return type:: bool

property collection¶

Return a reference to the collection this cursor is iterating over.

Returns:: The collection associated with this cursor
Return type:: Collection

property address: tuple | None¶

Return the address of the database.

Returns:

A tuple of (database_path, 0) after execution starts,: None before the cursor has been executed.

Return type:

tuple | None

get_quez_stats() → dict[str, Any] | None[source]¶

Get quez compression statistics if quez is being used.

Returns:: Dict with compression statistics or None if quez is not being used. Statistics include: - ‘count’: Number of items in the queue - ‘raw_size_bytes’: Total raw size of items in bytes - ‘compressed_size_bytes’: Total compressed size of items in bytes - ‘compression_ratio_pct’: Compression ratio as percentage (None if empty)