neosqlite.collection.query_helper package

Submodules

• neosqlite.collection.query_helper.aggregation module
  • AggregationMixin
    • AggregationMixin.self.collection
    • AggregationMixin.self._jsonb_supported
    • AggregationMixin.self._json_function_prefix
    • AggregationMixin.self._json_each_function
    • AggregationMixin.self._build_simple_where_clause
    • AggregationMixin.self._reorder_pipeline_for_indexes
    • AggregationMixin.self._estimate_pipeline_cost
    • AggregationMixin.self._optimize_match_pushdown
    • AggregationMixin.self._is_datetime_indexed_field
    • AggregationMixin.self._build_group_query
    • AggregationMixin.self._apply_query
    • AggregationMixin.collection
    • AggregationMixin._jsonb_supported
    • AggregationMixin._json_function_prefix
    • AggregationMixin._json_each_function
    • AggregationMixin._build_simple_where_clause
    • AggregationMixin._reorder_pipeline_for_indexes
    • AggregationMixin._estimate_pipeline_cost
    • AggregationMixin._optimize_match_pushdown
    • AggregationMixin._is_datetime_indexed_field
    • AggregationMixin._apply_query
    • AggregationMixin._build_aggregation_query()
    • AggregationMixin._optimize_unwind_group_pattern()
    • AggregationMixin._build_unwind_query()
    • AggregationMixin._build_unwind_from_clause()
    • AggregationMixin._build_unwind_from_clause_impl()
    • AggregationMixin._find_parent_unwind()
    • AggregationMixin._build_sort_skip_limit_clauses()
    • AggregationMixin._build_group_query()
    • AggregationMixin._process_group_stage()
    • AggregationMixin._run_subpipeline()
    • AggregationMixin._apply_projection()
• neosqlite.collection.query_helper.crud_operations module
  • CRUDOperationsMixin
    • CRUDOperationsMixin.collection
    • CRUDOperationsMixin._get_integer_id_for_oid
    • CRUDOperationsMixin._validate_json_document
    • CRUDOperationsMixin._get_json_error_position
    • CRUDOperationsMixin._internal_insert()
    • CRUDOperationsMixin._internal_replace()
    • CRUDOperationsMixin._internal_delete()
• neosqlite.collection.query_helper.fill_stage module
  • process_fill()
  • _fill_constant()
  • _fill_locf()
  • _fill_linear()
• neosqlite.collection.query_helper.graph_lookup module
  • process_graph_lookup()
• neosqlite.collection.query_helper.helpers module
  • _get_integer_id_for_oid()
  • _validate_json_document()
  • _get_json_error_position()
• neosqlite.collection.query_helper.positional_update module
  • _apply_positional_update()
  • _apply_positional_recursive()
  • _matches_filter()
  • _matches_query_operators()
  • _set_nested_field()
• neosqlite.collection.query_helper.query_builder module
  • QueryBuilderMixin
    • QueryBuilderMixin.collection
    • QueryBuilderMixin._jsonb_supported
    • QueryBuilderMixin._json_function_prefix
    • QueryBuilderMixin._build_expr_where_clause
    • QueryBuilderMixin._is_text_search_query()
    • QueryBuilderMixin._build_text_search_query()
    • QueryBuilderMixin._build_other_fields_clause()
    • QueryBuilderMixin._categorize_ids()
    • QueryBuilderMixin._build_id_operator_clause()
    • QueryBuilderMixin._categorize_id_value()
    • QueryBuilderMixin._build_field_clause()
    • QueryBuilderMixin._build_simple_where_clause()
    • QueryBuilderMixin._build_sort_clause()
    • QueryBuilderMixin._build_pagination_clause()
    • QueryBuilderMixin._build_operator_clause()
    • QueryBuilderMixin._search_in_value()
    • QueryBuilderMixin._apply_query()
    • QueryBuilderMixin._get_operator_fn()
• neosqlite.collection.query_helper.query_optimizer module
  • QueryOptimizerMixin
    • QueryOptimizerMixin.collection
    • QueryOptimizerMixin._jsonb_supported
    • QueryOptimizerMixin._json_function_prefix
    • QueryOptimizerMixin._get_indexed_fields()
    • QueryOptimizerMixin._estimate_result_size()
    • QueryOptimizerMixin._estimate_query_cost()
    • QueryOptimizerMixin._estimate_pipeline_cost()
    • QueryOptimizerMixin._optimize_match_pushdown()
    • QueryOptimizerMixin._is_datetime_indexed_field()
    • QueryOptimizerMixin._reorder_pipeline_for_indexes()
• neosqlite.collection.query_helper.schema_compiler module
  • compile_schema_to_sql()
  • _compile_node()
  • _compile_type_check()
• neosqlite.collection.query_helper.schema_validator module
  • matches_json_schema()
  • _validate_node()
  • _check_type()
  • _check_single_type()
• neosqlite.collection.query_helper.translation_cache module
  • CacheEntry
    • CacheEntry.__init__()
    • CacheEntry.sql_template
    • CacheEntry.param_names
    • CacheEntry.hit_count
  • TranslationCache
    • TranslationCache.DEFAULT_MAX_SIZE
    • TranslationCache.__init__()
    • TranslationCache.get()
    • TranslationCache.put()
    • TranslationCache.make_key()
    • TranslationCache._extract_structure()
    • TranslationCache.get_stats()
    • TranslationCache.clear()
    • TranslationCache.resize()
    • TranslationCache.evict()
    • TranslationCache.contains()
    • TranslationCache.get_entry()
    • TranslationCache._get_entry_hit_count()
    • TranslationCache.dump()
    • TranslationCache.is_enabled()
• neosqlite.collection.query_helper.update_operations module
  • UpdateOperationsMixin
    • UpdateOperationsMixin.collection
    • UpdateOperationsMixin._jsonb_supported
    • UpdateOperationsMixin._json_function_prefix
    • UpdateOperationsMixin._get_integer_id_for_oid
    • UpdateOperationsMixin._internal_update()
    • UpdateOperationsMixin._can_use_sql_updates()
    • UpdateOperationsMixin._perform_sql_update()
    • UpdateOperationsMixin._perform_enhanced_sql_update()
    • UpdateOperationsMixin._get_document_fields()
    • UpdateOperationsMixin._build_update_clause()
    • UpdateOperationsMixin._build_sql_update_clause()
    • UpdateOperationsMixin._perform_python_update()
    • UpdateOperationsMixin._validate_inc_mul_types_sql()
• neosqlite.collection.query_helper.utils module
  • _check_sqlite_version()
  • _supports_relative_json_indexing()
  • _supports_returning_clause()
  • _get_json_function()
  • _convert_bytes_to_binary()
  • set_force_fallback()
  • get_force_fallback()
  • _validate_inc_mul_field_value()
• neosqlite.collection.query_helper.window_operators module
  • process_set_window_fields()
  • _get_window_frame()
  • _apply_window_operator()
  • _get_sort_key()
  • _calculate_all_ranks()
  • _calculate_all_dense_ranks()

Module contents

class neosqlite.collection.query_helper.QueryHelper(collection)

Bases: CRUDOperationsMixin, UpdateOperationsMixin, QueryBuilderMixin, AggregationMixin, QueryOptimizerMixin

A helper class for the QueryEngine that provides methods for building queries, performing updates, and processing aggregation pipelines.

This class contains the core logic for translating MongoDB-like queries and operations into SQL statements that can be executed against the SQLite database. It handles both simple operations that can be done directly with SQL JSON functions and complex operations that require Python-based processing.

The class is composed of several mixins: - CRUDOperationsMixin: Insert, replace, delete operations - UpdateOperationsMixin: Update operations (SQL and Python-based) - QueryBuilderMixin: WHERE clause building and query application - AggregationMixin: Aggregation pipeline processing - QueryOptimizerMixin: Query optimization and cost estimation

__init__(collection)

Initialize the QueryHelper with a collection.

Parameters:

collection – The collection instance this QueryHelper will operate on.

cleanup() → None

Clean up resources used by the QueryHelper.

_normalize_id_query(query: dict[str, Any]) → dict[str, Any]

Normalize ID types in a query dictionary to correct common mismatches.

This method delegates to the centralized normalize_id_query_for_db function to ensure consistent ID handling across all NeoSQLite components.

Parameters:

query – The query dictionary to process

Returns:

A new query dictionary with corrected ID types

_get_integer_id_for_oid(oid: Any) → int

Get the integer ID for a given ObjectId or other ID type.

Parameters:

oid – The ID value (can be ObjectId, int, str, etc.)

Returns:

The integer ID from the database

Return type:

int

_validate_json_document(json_str: str) → bool

Validate JSON document using SQLite’s json_valid function.

Parameters:

json_str – The JSON string to validate

Returns:

True if valid, False otherwise

Return type:

bool

_get_json_error_position(json_str: str) → int

Get position of JSON error using json_error_position().

Parameters:

json_str – The JSON string to check

Returns:

Position of error, or -1 if valid/not supported

Return type:

int

_build_expr_where_clause(query: dict[str, Any]) → tuple[str, list[Any], list[str]] | None

Build a SQL WHERE clause for $expr queries using the 3-tier approach. Also handles other query fields combined with $expr.

Tier Selection Logic: - Tier 1 (Simple): Direct SQL WHERE with json_extract/jsonb_extract - Tier 2 (Complex): Temporary tables with pre-computed field extractions - Tier 3 (Fallback): Python evaluation for unsupported operations

Parameters:

query – Query dictionary containing $expr and potentially other fields

Returns:

Tuple of (SQL WHERE clause, parameters, tables) or None for Python fallback

_build_other_fields_clause(query: dict[str, Any], expr: dict[str, Any]) → tuple[str, list[Any]] | None

Helper to build WHERE clause for non-$expr fields.

_analyze_expr_complexity(expr: dict[str, Any]) → int

Analyze expression complexity to determine appropriate tier.

Complexity scoring: - Base expression: 1 point - Each nested operator: +1 point - Arithmetic operators: +1 point each - Conditional operators: +2 points each - Array operators: +2 points each - Type conversion: +1 point each

Tier thresholds: - 1-2: Tier 1 (simple SQL WHERE) - 3-8: Tier 2 (temporary tables) - 9+: Tier 3 (Python fallback)

Parameters:

expr – The $expr expression

Returns:

Complexity score

Return type:

int

_combine_expr_with_other_fields(sql_expr: str, params: list[Any], query: dict[str, Any], expr: dict[str, Any]) → tuple[str, list[Any], list[str]] | None

Combine $expr SQL with other query fields.

Parameters:

• sql_expr – The $expr SQL expression

• params – SQL parameters

• query – Full query dictionary

• expr – The $expr expression

Returns:

Tuple of (WHERE clause, parameters, tables) or None for Python fallback