Module cache 

Query Caching Module

Provides multi-tier query caching for HeliosProxy:

• L1 Hot Cache: Per-connection, exact match, LRU eviction
• L2 Warm Cache: Shared, normalized queries, configurable storage
• L3 Semantic Cache: Vector similarity for AI workloads

Architecture

                    ┌─────────────────────────────────────────────────┐
                    │                QUERY CACHE LAYER                 │
                    │                                                  │
  Query ───────────►│ ┌──────────────────────────────────────────────┐│
                    ││ L1: Hot Cache (in-memory, <1ms)               ││
                    │└──────────────────────────────────────────────┘│
                    │         │ miss                                  │
                    │         ▼                                       │
                    │ ┌──────────────────────────────────────────────┐│
                    ││ L2: Warm Cache (shared memory, <5ms)          ││
                    │└──────────────────────────────────────────────┘│
                    │         │ miss                                  │
                    │         ▼                                       │
                    │ ┌──────────────────────────────────────────────┐│
                    ││ L3: Semantic Cache (vector similarity, <20ms) ││
                    │└──────────────────────────────────────────────┘│
                    │         │ miss                                  │
                    │         ▼                                       │
                    │       BACKEND                                   │
                    └─────────────────────────────────────────────────┘

Usage

use heliosdb_lite::proxy::cache::{QueryCache, CacheConfig};

let config = CacheConfig::default();
let cache = QueryCache::new(config);

// Check cache before executing query
if let Some(result) = cache.get(&query, &context).await {
    return result;
}

// Execute query and cache result
let result = execute_query(&query).await?;
cache.put(&query, &context, result.clone()).await;

Re-exports

pub use config::CacheConfig;

pub use config::L1Config;

pub use config::L2Config;

pub use config::L3Config;

pub use config::StorageBackend;

pub use l1_hot::L1HotCache;

pub use l2_warm::L2WarmCache;

pub use l3_semantic::L3SemanticCache;

pub use normalizer::QueryNormalizer;

pub use normalizer::NormalizedQuery;

pub use invalidation::InvalidationManager;

pub use invalidation::InvalidationMode;

pub use metrics::CacheMetrics;

pub use metrics::CacheStatsSnapshot;

pub use metrics::CacheStatsLevelSnapshot;

pub use hints::CacheHint;

pub use hints::parse_cache_hints;

pub use result::CachedResult;

pub use result::CacheKey;

Modules

config

Cache Configuration

hints

Cache Hints Parser

invalidation

Cache Invalidation

l1_hot

L1 Hot Cache

l2_warm

L2 Warm Cache

l3_semantic

L3 Semantic Cache

metrics

Cache Metrics

normalizer

Query Normalizer

result

Cached Result Types

Structs

CacheContext

Query cache context (for cache key generation)

QueryCache

Main query cache implementation

Enums

CacheLevel

Cache level indicator

CacheLookup

Cache lookup result