Adaptive Cache Policies

The AdaptiveCachePolicy service manages per-table and per-data-source freshness requirements. Different tables have different update frequencies -- a real-time events table needs much shorter cache TTLs than a slowly-changing dimension table.

Freshness Levels

The adaptive policy supports configurable freshness levels:

Level	Description	Typical Max Staleness
`REALTIME`	Data must be current (bypass cache)	0 seconds
`NEAR_REALTIME`	Tolerate slight staleness	30 seconds
`FRESH`	Standard freshness	5 minutes
`RELAXED`	Acceptable for historical data	1 hour
`STALE_OK`	Long-lived reference data	24 hours

Configuring Table Freshness

Administrators can configure freshness requirements per table:

# Set freshness policy for a real-time events table
curl -X POST http://query-engine:8080/v1/cache/policy/freshness \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "tableName": "analytics.events",
    "maxStalenessSeconds": 30,
    "level": "NEAR_REALTIME"
  }'

{
  "status": "configured",
  "table": "analytics.events"
}

Data Source Update Tracking

When a data source is updated (ETL completion, streaming ingestion), the policy service records the update timestamp:

# Record a data source update
curl -X POST http://query-engine:8080/v1/cache/policy/data-source-update \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{"dataSource": "analytics.orders"}'

This timestamp is compared against the freshness policy to determine if cached results are still valid. When the cached result's creation time plus the max staleness is older than the last data source update, the cache entry is considered stale and bypassed.

Policy Statistics

curl http://query-engine:8080/v1/cache/policy/stats \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "totalPolicies": 12,
  "tablesTracked": 45,
  "averageStalenessSeconds": 180,
  "staleEntriesEvicted": 342,
  "freshHits": 8920,
  "staleBypass": 156
}

Optimization Recommendations

The adaptive policy generates recommendations based on observed access patterns:

curl http://query-engine:8080/v1/cache/policy/recommendations \
  -H "Authorization: Bearer $JWT_TOKEN"

[
  {
    "type": "INCREASE_TTL",
    "table": "dim_products",
    "currentTtlSeconds": 300,
    "recommendedTtlSeconds": 3600,
    "reason": "Table has not been updated in 72 hours, current TTL is unnecessarily short",
    "estimatedHitRateIncrease": 0.12
  },
  {
    "type": "DECREASE_TTL",
    "table": "fact_orders",
    "currentTtlSeconds": 3600,
    "recommendedTtlSeconds": 300,
    "reason": "Table is updated every 5 minutes, cached results are frequently stale",
    "estimatedFreshnessImprovement": 0.85
  }
]

Semantic Cache Cache Warming