neosqlite.collection.query_helper.translation_cache module

Translation Cache for SQL Tier Aggregation.

This module provides caching for translated pipeline-to-SQL queries, with O(1) LRU (Least Recently Used) eviction using OrderedDict.

The cache stores SQL templates (not results), allowing the same translated SQL to be reused across multiple query executions with different parameters.

class neosqlite.collection.query_helper.translation_cache.CacheEntry(sql_template: str, param_names: tuple[str, ...])

Bases: object

Single cache entry with hit statistics.

__init__(sql_template: str, param_names: tuple[str, ...])

sql_template

param_names

hit_count

class neosqlite.collection.query_helper.translation_cache.TranslationCache(max_size: int = 100)

Bases: object

LRU cache for SQL translation templates with O(1) get/put operations.

Uses OrderedDict for efficient LRU eviction: most recently used entries are moved to the end, least recently used are evicted from the front.

DEFAULT_MAX_SIZE = 100

__init__(max_size: int = 100)

get(key: str) → tuple[str, tuple[str, ...]] | None

Get cached SQL template by key. Returns (sql, param_names) or None.

put(key: str, sql_template: str, param_names: tuple[str, ...]) → None

Store SQL template in cache with extracted parameter names.

make_key(pipeline: list[dict[str, Any]]) → str

Create a cache key from pipeline structure.

Key includes: operator names + field names + nested operator names.

Values like $sample.size, $limit, $skip are NOT included in the key because we now parameterize them in SQL (using ?) - the same cached SQL template can be reused with different parameter values.

_extract_structure(obj: Any) → Any

Recursively convert pipeline dict into a hashable nested tuple.

Replaces literal values (numbers, strings, booleans) with ‘?’ placeholder, but PRESERVES field references (strings starting with $) to prevent cache collisions between queries grouping/filtering on different fields.

Examples: - {“$gt”: 25} -> (“$gt”, “?”) - {“_id”: “$dept”} -> (“_id”, “$dept”) # Preserved! - {“status”: “active”} -> (“status”, “?”)

get_stats() → dict[str, Any]

Get cache statistics.

clear() → None

Clear the cache and reset statistics.

resize(new_size: int) → None

Resize cache, evicting entries if needed.

evict(key: str) → bool

Evict a specific entry by key. Returns True if evicted.

contains(key: str) → bool

Check if a key is in the cache.

get_entry(key: str) → dict | None

Get detailed info about a specific cache entry.

_get_entry_hit_count(item: tuple[str, CacheEntry]) → int

Helper to extract hit_count from cache entry for sorting.

dump() → list[dict]

Dump all cache entries for debugging.

is_enabled() → bool

Check if cache is enabled.