neosqlite.collection.query_helper.query_builder module

Query Builder Mixin for NeoSQLite.

This module contains the QueryBuilderMixin class, which provides methods for building SQL queries from MongoDB-like query specifications.

class neosqlite.collection.query_helper.query_builder.QueryBuilderMixin[source]

Bases: object

A mixin class that provides query building capabilities.

This mixin assumes it will be used with a class that has: - self.collection (with db and name attributes) - self._jsonb_supported - self._json_function_prefix - self._build_expr_where_clause method (for handling $expr queries)

collection: Collection
_jsonb_supported: bool
_json_function_prefix: str
_build_expr_where_clause: Any
_is_text_search_query(query: dict[str, Any]) → bool[source]

Check if the query is a text search query (contains $text operator).

Parameters:

query – The query to check.

Returns:

True if the query is a text search query, False otherwise.

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

Builds a SQL query for text search using FTS5.

Parameters:

query – A dictionary representing the text search query with $text operator.

Returns:

A tuple containing the SQL WHERE clause,

a list of parameters, and an empty list of tables to clean up, or None.

Return type:

tuple[str, list[Any], list[str]] | None

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

Build WHERE clause for non-$expr fields.

Parameters:

  • query – Full query dictionary

  • expr – The $expr expression

Returns:

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

_categorize_ids(ids: list[Any]) → tuple[list[int], list[str]] | None[source]

Categorize a list of ID values into integer IDs and string IDs.

Parameters:

ids – List of ID values (ints, ObjectIds, or strings)

Returns:

Tuple of (int_ids, string_ids) or None if unsupported types found

_build_id_operator_clause(value: dict) → tuple[str, list[Any]] | None[source]

Build a WHERE clause for _id field with operators like $in, $nin, $ne, etc.

Parameters:

value – Dictionary containing operators like $in, $nin, $ne, etc.

Returns:

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

_categorize_id_value(value: Any) → tuple[int | None, str | None][source]

Categorize a single ID value into either an int ID or a string ID.

Returns:

Tuple of (int_value, string_value) where only one is non-None.

_build_field_clause(field: str, value: Any) → tuple[str, list[Any]] | None[source]

Build a WHERE clause for a single field.

Parameters:

  • field – Field name

  • value – Field value or operator dict

Returns:

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

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

Builds a SQL WHERE clause for simple queries that can be handled with json_extract.

This method constructs a SQL WHERE clause based on the query provided. It handles simple equality checks and query operators like $eq, $gt, $lt, etc. for fields stored in JSON data. For more complex queries, it returns None, indicating that a Python-based method should be used instead.

When the force fallback flag is set, this method returns None to force Python-based processing for benchmarking and debugging purposes.

Parameters:

query (dict[str, Any]) – A dictionary representing the query criteria.

Returns:

A tuple containing the SQL WHERE clause,

a list of parameters, and a list of temporary tables to clean up, or None.

Return type:

tuple[str, list[Any], list[str]] | None

_build_sort_clause(sort: dict[str, int] | None, collation: dict[str, Any] | None = None) → str[source]

Builds a SQL ORDER BY clause from a sort dictionary.

Parameters:

  • sort – A dictionary mapping fields to sort directions (1 for ASC, -1 for DESC).

  • collation – Optional collation settings for case-insensitive sorting.

Returns:

A SQL ORDER BY clause string (including ‘ORDER BY’ prefix), or empty string.

_build_pagination_clause(limit: int | None, skip: int = 0) → str[source]

Builds a SQL LIMIT and OFFSET clause.

Parameters:

  • limit – The maximum number of documents to return.

  • skip – The number of documents to skip.

Returns:

A SQL LIMIT/OFFSET clause string, or empty string.

_build_operator_clause(json_path: str, operators: dict[str, Any], is_datetime_indexed: bool = False, regex_options: str = '') → tuple[str | None, list[Any]][source]

Builds a SQL clause for query operators.

This method constructs a SQL clause based on the provided operators for a specific JSON path. It handles various operators like $eq, $gt, $lt, etc., and returns a tuple containing the SQL clause and a list of parameters. If an unsupported operator is encountered, it returns None, indicating that a fallback to Python processing is needed.

Parameters:

  • json_path (str) – The JSON path to extract the value from.

  • operators (dict[str, Any]) – A dictionary of operators and their values.

  • is_datetime_indexed (bool) – Whether the field has a datetime index that requires timezone normalization.

Returns:

A tuple containing the SQL clause and

parameters. If the operator is unsupported, returns (None, []).

Return type:

tuple[str | None, list[Any]]

_search_in_value(value: Any, search_term: str) → bool[source]

Recursively search for a term in a value (string, dict, or list).

Parameters:

  • value – The value to search in

  • search_term – The term to search for

Returns:

True if the search term is found, False otherwise

Return type:

bool

_apply_query(query: dict[str, Any], document: dict[str, Any]) → bool[source]

Applies a query to a document to determine if it matches the query criteria.

Handles logical operators ($and, $or, $nor, $not) and nested field paths. Processes both simple equality checks and complex query operators.

Parameters:

  • query (dict[str, Any]) – A dictionary representing the query criteria.

  • document (dict[str, Any]) – The document to apply the query to.

Returns:

True if the document matches the query, False otherwise.

Return type:

bool

_get_operator_fn(op: str) → Any[source]

Retrieve the function associated with the given operator from the query_operators module.

Parameters:

op (str) – The operator string, which should start with a ‘$’ prefix.

Returns:

The function corresponding to the operator.

Return type:

Any

Raises: