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 together with their exact bound parameters. Cache keys canonicalize the full pipeline content (including literal values), so a cache hit always corresponds to an identical pipeline and the stored parameters are guaranteed to match the template’s placeholders.

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

Bases: object

Single cache entry with hit statistics.

__init__(sql_template: str, payload: tuple[Any, ...])

sql_template

payload

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[Any, ...]] | None

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

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

Store SQL template in cache with its associated payload.

The payload is consumer-defined (e.g. the exact bound parameters for the template). It must correspond 1:1 with this exact key, which is guaranteed because make_key canonicalizes literal values into the key — a cache hit therefore implies an identical pipeline.

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

Create a cache key from the full pipeline content.

Literal values are canonicalized (type-tagged) into the key so that a cache hit implies an identical pipeline. This is required for correctness: sort directions, limits and other literals may be baked into the cached SQL template rather than bound as parameters.

Field references ($field) are preserved verbatim; dicts are sorted for order-insensitivity where ordering is not semantic.

_canonicalize(value: Any) → tuple

Recursively convert a value into a hashable, type-tagged structure.

Type tags distinguish values that Python would otherwise equate (e.g. True vs 1, 1 vs 1.0) so that semantically different pipelines never share a cache entry. Unhashable/exotic objects (ObjectId, datetime, bytes, …) are represented via their type name and repr, which is stable for equal instances.

_extract_structure(obj: Any) → tuple

Recursively convert a pipeline fragment into a hashable nested tuple.

Preserves both field references ($field) and literal values so that structurally identical but semantically different fragments (e.g. differing sort directions or comparison bounds) map to distinct keys.

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.