Cache Endpoints
The cache management endpoints control the multi-level query cache, including statistics, invalidation, warming, semantic cache, adaptive policies, and analytics. Served by CacheController at /v1/cache.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/cache/stats | Get cache statistics |
| GET | /v1/cache/config | Get cache configuration (Admin) |
| POST | /v1/cache/invalidate/query/:queryHash | Invalidate specific query |
| POST | /v1/cache/invalidate/dependency/:dep | Invalidate by dependency |
| POST | /v1/cache/invalidate/tenant | Invalidate entire tenant cache (Admin) |
| POST | /v1/cache/invalidate/schema-change | Handle schema change |
| POST | /v1/cache/warm | Trigger cache warming (Admin) |
| POST | /v1/cache/warm/query | Warm specific query |
| GET | /v1/cache/warming/status | Get warming status |
| GET | /v1/cache/analytics/dashboard | Cache analytics dashboard |
| GET | /v1/cache/analytics/efficiency-report | Efficiency report |
| GET | /v1/cache/analytics/query/:queryHash | Analyze query performance |
| GET | /v1/cache/analytics/timeseries/:metric | Time-series metrics |
| GET | /v1/cache/analytics/heatmap | Access heatmap |
| GET | /v1/cache/semantic/stats | Semantic cache statistics |
| GET | /v1/cache/semantic/templates | Popular query templates |
| POST | /v1/cache/semantic/normalize | Normalize SQL query |
| GET | /v1/cache/policy/stats | Adaptive policy statistics |
| GET | /v1/cache/policy/recommendations | Optimization recommendations |
| POST | /v1/cache/policy/freshness | Configure table freshness (Admin) |
Cache Architecture
The cache uses a two-level architecture:
| Level | Backend | TTL | Purpose |
|---|---|---|---|
| L1 | In-memory (Caffeine) | Short | Hot query results, near-zero latency |
| L2 | Redis | Long | Shared cache across query engine replicas |
Invalidation
By query hash: Invalidates a specific cached query result.
By dependency: Invalidates all cached results that depend on a specific table or data source. Used when underlying data changes.
By schema change: Accepts a set of affected tables and invalidates all dependent cache entries.
{
"affectedTables": ["orders", "customers"]
}Cache Warming
Proactively populates the cache with results for frequently executed queries.
POST /v1/cache/warmReturns 202 Accepted if warming starts, or 200 with "in_progress" if warming is already running.
Semantic Cache
The semantic cache normalizes SQL queries to identify structurally identical queries with different literal values. This increases cache hit rates for parameterized queries.
POST /v1/cache/semantic/normalize{
"query": "SELECT * FROM orders WHERE customer_id = 'C-001' AND date > '2026-01-01'"
}Returns the normalized query and template hash.