Caching Architecture

The Query Engine implements a sophisticated multi-level caching system designed to minimize redundant computation while maintaining data freshness. The cache architecture combines in-memory speed with distributed durability and semantic intelligence to maximize cache hit rates.

Cache Layers

  Query Request
       |
       v
  +----+----+
  | Semantic |--- Template match ---> Return cached result
  | Cache    |
  +----+----+
       |
       v
  +----+----+
  |  L1     |--- In-memory hit ---> Return (sub-millisecond)
  | Caffeine|
  +----+----+
       |
       v
  +----+----+
  |  L2     |--- Redis hit -------> Promote to L1 + Return
  |  Redis  |
  +----+----+
       |
       v
  Execute Query ---> Cache result in L1 + L2

Layer	Technology	Capacity	TTL	Latency	Purpose
Semantic	In-memory index	Unlimited templates	Same as L2	sub-ms	Match structurally similar queries
L1	Caffeine	256 MB / 1000 entries	10 minutes	sub-ms	Hot query results for the local JVM
L2	Redis	Configurable	1 hour	1-5ms	Shared cache across Query Engine replicas

Key Components

Component	Source File	Role
`MultiLevelCacheService`	`cache/MultiLevelCacheService.java`	L1 + L2 cache operations
`SemanticCacheService`	`cache/SemanticCacheService.java`	Template normalization and matching
`AdaptiveCachePolicy`	`cache/AdaptiveCachePolicy.java`	Per-table freshness policies
`CacheWarmingService`	`cache/CacheWarmingService.java`	Proactive cache population
`CacheAnalyticsService`	`cache/CacheAnalyticsService.java`	Hit rate analytics and dashboards
`CacheInvalidationService`	`cache/CacheInvalidationService.java`	Programmatic invalidation
`CacheInvalidationListener`	`cache/CacheInvalidationListener.java`	Event-driven invalidation
`CacheConfig`	`cache/CacheConfig.java`	Configuration properties

Subsections

Page	Description
Multi-Level Cache	L1 in-memory (Caffeine) + L2 distributed (Redis) with GZIP compression
Semantic Cache	Template normalization, parameter extraction, fuzzy matching
Adaptive Policies	Per-table freshness requirements, staleness tracking
Cache Warming	Proactive population of popular queries
Cache Analytics	Hit rates, efficiency reports, heatmaps, time-series
Invalidation	Query, dependency, tenant, and schema-based invalidation
Configuration	Complete cache configuration reference

Query Statistics Multi-Level Cache