neosqlite.collection.temporary_table_aggregation.operators_sort_proj module

class neosqlite.collection.temporary_table_aggregation.operators_sort_proj.OperatorsSortProjMixin[source]

Bases: OperatorsBaseMixin

_process_sort_skip_limit_stage(create_temp: Callable, current_table: str, sort_spec: dict[str, Any] | None, skip_value: int = 0, limit_value: int | None = None) → str[source]

Process sort/skip/limit stages using temporary tables.

This method handles the $sort, $skip, and $limit aggregation stages, which can be used individually or in combination. It creates a temporary table with the results sorted and/or paginated according to the specifications.

The method supports sorting on both regular fields (using json_extract) and the special _id field (using the id column directly). It handles ascending and descending sort orders, as well as skip and limit operations with proper OFFSET and LIMIT clauses in the SQL query.

When multiple sort/skip/limit stages are consecutive in a pipeline, they are processed together in a single operation for efficiency.

Parameters:

  • create_temp (Callable) – Function to create temporary tables

  • current_table (str) – Name of the current temporary table containing input data

  • sort_spec (dict[str, Any] | None) – The $sort stage specification, mapping field names to sort directions (1 for ascending, -1 for descending)

  • skip_value (int) – The number of documents to skip (from $skip stage)

  • limit_value (int | None) – The maximum number of documents to return (from $limit stage)

Returns:

Name of the newly created temporary table with sorted/skipped/limited results

Return type:

str

_process_add_fields_stage(create_temp: Callable, current_table: str, add_fields_spec: dict[str, Any]) → str[source]

Process an $addFields stage using temporary tables.

This method implements the $addFields aggregation stage which adds new fields to documents. It uses SQLite’s json_set function to add fields to the JSON data.

Supports: - Simple field copying: {“newField”: “$existingField”} - $replaceOne: {$replaceOne: {input: “$text”, find: “old”, replacement: “new”}} - Literal values: {“field”: “value”}

Parameters:

  • create_temp (Callable) – Function to create temporary tables

  • current_table (str) – Name of the current temporary table containing input data

  • add_fields_spec (dict[str, Any]) – The $addFields stage specification mapping new field names to source field paths

Returns:

Name of the newly created temporary table with added fields

Return type:

str

_process_add_fields_stage_python_hybrid(create_temp: Callable, current_table: str, add_fields_spec: dict[str, Any]) → str[source]

Process $addFields stage with complex expressions using Python hybrid approach.

This method loads documents from the current temp table, applies the $addFields expressions in Python (using ExprEvaluator), and creates a new temp table. This allows us to stay in Tier 2 (temp tables) while still supporting complex expressions like $filter, $map, $reduce, etc.

Parameters:

  • create_temp (Callable) – Function to create temporary tables

  • current_table (str) – Name of the current temporary table

  • add_fields_spec (dict[str, Any]) – The $addFields stage specification

Returns:

Name of the newly created temporary table with added fields

Return type:

str

_is_expression(expr: Any) → bool[source]

Check if an expression is a complex expression (not a simple field reference or literal).

_process_project_stage(create_temp: Callable, current_table: str, project_spec: dict[str, Any]) → str[source]

Process a $project stage using temporary tables.

This method implements the $project aggregation stage which reshapes each document in the stream, by adding new fields, removing existing fields, or renaming fields. It reconstructs a unified data column using json_object / jsonb_object so that downstream stages (especially FTS5 text search via json_tree) continue to work without modification.

Supports: - Simple inclusion: {"field": 1} - Exclusion: {"field": 0} - Field references: {"alias": "$some.path"} - Expression projections: {"alias": {$concat: [...]}} - _id inclusion/exclusion

Parameters:

  • create_temp (Callable) – Function to create temporary tables

  • current_table (str) – Name of the current temporary table

  • project_spec (dict[str, Any]) – The $project stage specification

Returns:

Name of the newly created temporary table

Return type:

str

_process_project_exclusion(create_temp: Callable, current_table: str, project_spec: dict[str, Any], include_id: bool) → str[source]

Handle exclusion-mode projection by removing fields via json_remove.

_process_project_inclusion(create_temp: Callable, current_table: str, project_spec: dict[str, Any], include_id_default: bool) → str[source]

Handle inclusion-mode projection by reconstructing data via json_object.

Handles: - Simple inclusion: {"field": 1} - Field references: {"alias": "$some.path"} - Expression projections: {"alias": {$concat: [...]}}

_generate_text_score_sql() → str[source]

Generate SQL for $meta: “textScore” using stored BM25 score.

During $text search stages, the FTS5 BM25 relevance score is captured and stored in the document’s JSON data as _textScore. This method extracts that score for use in $project/$addFields stages.

Returns:

SQL expression that returns the BM25 relevance score (positive value)

_process_replace_root_stage(create_temp: Callable, current_table: str, replace_spec: Any) → str[source]

Process a $replaceRoot or $replaceWith stage using temporary tables.

This method implements the $replaceRoot/$replaceWith aggregation stage which replaces the root document with a specified field or expression.

MongoDB syntax:

{$replaceRoot: {newRoot: “$field”}} {$replaceWith: “$field”}

Parameters:

  • create_temp (Callable) – Function to create temporary tables

  • current_table (str) – Name of the current temporary table containing input data

  • replace_spec (Any) – The replace specification (field path or expression)

Returns:

Name of the newly created temporary table with replaced root documents

Return type:

str