neosqlite.collection.jsonb_support module¶

JSONB support detection utilities for NeoSQLite.

Provides efficient detection of JSONB capabilities with automatic caching to avoid redundant database queries.

neosqlite.collection.jsonb_support.clear_jsonb_cache(db_connection=None) → None[source]¶

Clear the JSONB support cache.

Parameters:: db_connection – Optional specific connection to clear from cache. If None, clears the entire cache.

neosqlite.collection.jsonb_support.supports_jsonb(db_connection) → bool[source]¶

Check if the SQLite connection supports JSONB functions.

This function tests whether the SQLite installation has JSONB support by attempting to call the jsonb() function. Results are cached to avoid redundant queries.

Parameters:: db_connection – SQLite database connection to test
Returns:: True if JSONB is supported, False otherwise
Return type:: bool

neosqlite.collection.jsonb_support.supports_jsonb_each(db_connection) → bool[source]¶

Check if the SQLite connection supports jsonb_each() table-valued function.

The jsonb_each() and jsonb_tree() functions were added in SQLite 3.51.0. This function tests whether they’re available by attempting to use them. Results are cached to avoid redundant queries.

Parameters:: db_connection – SQLite database connection to test
Returns:: True if jsonb_each is supported, False otherwise
Return type:: bool

neosqlite.collection.jsonb_support._get_json_function_prefix(jsonb_supported: bool) → str[source]¶

Get the appropriate JSON function prefix based on JSONB support.

Parameters:: jsonb_supported – Whether JSONB functions are supported
Returns:: “jsonb” if JSONB is supported, “json” otherwise
Return type:: str

neosqlite.collection.jsonb_support._get_json_each_function(jsonb_supported: bool, jsonb_each_supported: bool) → str[source]¶

Get the appropriate json_each function name based on support.

Parameters:

jsonb_supported – Whether JSONB functions are supported
jsonb_each_supported – Whether jsonb_each is supported (SQLite 3.51.0+)

Returns:

“jsonb_each” if supported, “json_each” otherwise

Return type:

str

neosqlite.collection.jsonb_support._get_json_tree_function(jsonb_supported: bool, jsonb_each_supported: bool) → str[source]¶

Get the appropriate json_tree function name based on support.

Parameters:

jsonb_supported – Whether JSONB functions are supported
jsonb_each_supported – Whether jsonb_each/jsonb_tree is supported (SQLite 3.51.0+)

Returns:

“jsonb_tree” if supported, “json_tree” otherwise

Return type:

str

neosqlite.collection.jsonb_support._get_json_group_array_function(jsonb_supported: bool) → str[source]¶

Get the appropriate json_group_array function name based on support.

Parameters:: jsonb_supported – Whether JSONB functions are supported
Returns:: “jsonb_group_array” if supported, “json_group_array” otherwise
Return type:: str

neosqlite.collection.jsonb_support.should_use_json_functions(query: dict | None = None, jsonb_supported: bool = False) → bool[source]¶

Determine if we should use json_* functions instead of jsonb_* functions.

This function determines whether to use json_* or jsonb_* functions based on: 1. JSONB support availability 2. Query content (specifically text search queries which require FTS compatibility)

Parameters:

query – MongoDB query dictionary to check for text search operations
jsonb_supported – Whether JSONB functions are supported by the database

Returns:

True if json_* functions should be used, False if jsonb_* functions should be used

Return type:

bool

neosqlite.collection.jsonb_support._contains_text_operator(query: dict) → bool[source]¶

Check if a query contains any $text operators, including nested in logical operators.

This method recursively traverses a MongoDB query specification to detect the presence of $text operators, which require special handling and fallback to Python implementation. It checks both top-level $text operators and those nested within logical operators ($and, $or, $nor, $not).

Parameters:: query – The query to check
Returns:: True if the query contains $text operators, False otherwise

neosqlite.collection.jsonb_support.json_data_column(jsonb_supported: bool, source: str = 'data') → str[source]¶

Return the data column expression for SELECT queries.

When JSONB is supported, wraps the source with json() to convert JSONB to text. Otherwise returns the source unchanged.

When JSONB is supported, also handles malformed JSON gracefully by checking json_valid() first for text values. This prevents the entire query from failing when a single row has corrupted data. JSONB blobs are always passed through json() since they’re stored in SQLite’s binary JSON format.