neosqlite.collection.query_engine package

Submodules

• neosqlite.collection.query_engine.base module
  • QueryEngineProtocol
    • QueryEngineProtocol.collection
    • QueryEngineProtocol.helpers
    • QueryEngineProtocol.sql_translator
    • QueryEngineProtocol._jsonb_supported
    • QueryEngineProtocol._get_integer_id_for_oid()
    • QueryEngineProtocol.find()
    • QueryEngineProtocol.find_one()
    • QueryEngineProtocol.insert_one()
    • QueryEngineProtocol.update_one()
    • QueryEngineProtocol.delete_one()
    • QueryEngineProtocol.__init__()
    • QueryEngineProtocol._abc_impl
    • QueryEngineProtocol._is_protocol
• neosqlite.collection.query_engine.crud_operations module
  • CRUDOperationsMixin
    • CRUDOperationsMixin.insert_one()
    • CRUDOperationsMixin.insert_many()
    • CRUDOperationsMixin.update_one()
    • CRUDOperationsMixin._update_gridfs_file()
    • CRUDOperationsMixin._get_integer_id_for_oid()
    • CRUDOperationsMixin._try_fast_update_one()
    • CRUDOperationsMixin.update_many()
    • CRUDOperationsMixin.delete_one()
    • CRUDOperationsMixin.delete_many()
    • CRUDOperationsMixin.replace_one()
    • CRUDOperationsMixin._abc_impl
    • CRUDOperationsMixin._is_protocol
• neosqlite.collection.query_engine.find_operations module
  • FindOperationsMixin
    • FindOperationsMixin.find()
    • FindOperationsMixin.find_raw_batches()
    • FindOperationsMixin.find_one()
    • FindOperationsMixin.find_one_and_delete()
    • FindOperationsMixin.find_one_and_replace()
    • FindOperationsMixin.find_one_and_update()
    • FindOperationsMixin._abc_impl
    • FindOperationsMixin._is_protocol
• neosqlite.collection.query_engine.query_methods module
  • QueryMethodsMixin
    • QueryMethodsMixin.count_documents()
    • QueryMethodsMixin.estimated_document_count()
    • QueryMethodsMixin.distinct()
    • QueryMethodsMixin._abc_impl
    • QueryMethodsMixin._is_protocol

Module contents

class neosqlite.collection.query_engine.QueryEngine(collection)

Bases: CRUDOperationsMixin, FindOperationsMixin, QueryMethodsMixin

A class that provides methods for querying and manipulating documents in a collection.

The QueryEngine handles all database operations including inserting, updating, deleting, and finding documents. It also supports aggregation pipelines, bulk operations, and various utility methods for counting and retrieving distinct values.

__init__(collection)

Initialize the QueryEngine with a collection.

Parameters:

collection – The collection instance this QueryEngine will operate on.

add_tier_change_callback(callback: Callable[[str | None, str, list], None]) → None

Add a callback to be notified when query tier changes.

Callback receives: (previous_tier: str | None, new_tier: str, pipeline: list) where tier is one of: - “tier1” (SQL CTE - new aggregation optimizer) - “tier1_standard” (non-CTE SQL aggregation) - “tier2” (temp table for complex $expr) - “tier3” (Python fallback) - None (before any query)

remove_tier_change_callback(callback: Callable[[str | None, str, list], None]) → bool

Remove a tier change callback. Returns True if found.

get_last_tier() → str | None

Get the last tier that was used for query execution.

clear_tier_callbacks() → None

Clear all tier change callbacks.

_notify_tier_change(new_tier: str, pipeline: list) → None

Notify all callbacks of a tier change.

cleanup() → None

Clean up resources used by the QueryEngine.

aggregate(pipeline: list[dict[str, Any]], batch_size: int = 101, session: ClientSession | None = None) → list[dict[str, Any]]

Applies a list of aggregation pipeline stages to the collection.

This method handles both simple and complex queries. For simpler queries, it leverages the database’s native indexing capabilities to optimize performance. For more complex queries, it falls back to a Python-based processing mechanism.

Parameters:

• pipeline (list[dict[str, Any]]) – A list of aggregation pipeline stages to apply.

• batch_size (int) – The batch size for fetching results from database.

• session (ClientSession, optional) – A ClientSession for transactions.

Returns:

The list of documents after applying the aggregation pipeline.

Return type:

list[dict[str, Any]]

aggregate_with_constraints(pipeline: list[dict[str, Any]], batch_size: int = 101, memory_constrained: bool = False, session: ClientSession | None = None) → list[dict[str, Any]] | 'CompressedQueue'

Applies a list of aggregation pipeline stages with memory constraints.

Parameters:

• pipeline (list[dict[str, Any]]) – A list of aggregation pipeline stages to apply.

• batch_size (int) – The batch size for processing large result sets.

• memory_constrained (bool) – Whether to use memory-constrained processing.

• session (ClientSession, optional) – A ClientSession for transactions.

Returns:

The results as either a list or compressed queue.

Return type:

list[dict[str, Any]] | CompressedQueue

explain_aggregation(pipeline: list[dict[str, Any]], session: ClientSession | None = None) → dict[str, Any]

Explain the execution plan for an aggregation pipeline.

Parameters:

• pipeline (list[dict[str, Any]]) – The aggregation pipeline to explain.

• session (ClientSession, optional) – A ClientSession for transactions.

Returns:

The execution plan explanation.

Return type:

dict[str, Any]

aggregate_raw_batches(pipeline: list[dict[str, Any]], batch_size: int = 100, session: ClientSession | None = None) → RawBatchCursor

Perform aggregation and retrieve batches of raw JSON.

Similar to the aggregate() method but returns a RawBatchCursor.

This method returns raw JSON batches which can be more efficient for certain use cases where you want to process data in batches rather than individual documents.

Parameters:

• pipeline (list[dict[str, Any]]) – A list of aggregation pipeline stages to apply.

• batch_size (int) – The number of documents to include in each batch.

• session (ClientSession, optional) – A ClientSession for transactions.

Returns:

RawBatchCursor instance.

bulk_write(requests: list[Any], ordered: bool = True, session: ClientSession | None = None) → BulkWriteResult

Execute bulk write operations on the collection.

Parameters:

• requests – List of write operations to execute.

• ordered – If true, operations will be performed in order and will raise an exception if a single operation fails.

• session (ClientSession, optional) – A ClientSession for transactions.

Returns:

A result object containing the number of matched,

modified, and inserted documents.

Return type:

BulkWriteResult

_aggregate_with_quez(pipeline: list[dict[str, Any]], batch_size: int = 101) → CompressedQueue

Process aggregation pipeline with quez compressed queue for memory efficiency.

Parameters:

• pipeline (list[dict[str, Any]]) – A list of aggregation pipeline stages to apply.

• batch_size (int) – The batch size for quez queue processing.

Returns:

A compressed queue containing the results.

Return type:

CompressedQueue

initialize_ordered_bulk_op() → BulkOperationExecutor

Initialize an ordered bulk operation.

Returns:

An executor for ordered bulk operations.

Return type:

BulkOperationExecutor

initialize_unordered_bulk_op() → BulkOperationExecutor

Initialize an unordered bulk operation.

Returns:

An executor for unordered bulk operations.

Return type:

BulkOperationExecutor

_abc_impl = <_abc._abc_data object>

_is_protocol = False