Period Comparison

The comparison endpoint enables comparing query performance between two arbitrary time periods, useful for evaluating the impact of configuration changes, deployments, or data growth.

Endpoint

GET /v1/analytics/compare

Query Parameters

Parameter	Type	Required	Description
`period1Start`	ISO DateTime	Yes	Start of first period
`period1End`	ISO DateTime	Yes	End of first period
`period2Start`	ISO DateTime	Yes	Start of second period
`period2End`	ISO DateTime	Yes	End of second period

curl Example

# Compare this week vs last week
curl "http://query-engine:8080/v1/analytics/compare?\
period1Start=2026-02-03T00:00:00Z&period1End=2026-02-09T23:59:59Z&\
period2Start=2026-01-27T00:00:00Z&period2End=2026-02-02T23:59:59Z" \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "period1": {
    "start": "2026-02-03T00:00:00Z",
    "end": "2026-02-09T23:59:59Z",
    "queryCount": 12450,
    "avgLatencyMs": 2340,
    "successRate": 0.962,
    "cacheHitRate": 0.34,
    "totalBytesScanned": 10995116277760
  },
  "period2": {
    "start": "2026-01-27T00:00:00Z",
    "end": "2026-02-02T23:59:59Z",
    "queryCount": 11200,
    "avgLatencyMs": 2680,
    "successRate": 0.955,
    "cacheHitRate": 0.28,
    "totalBytesScanned": 9895604649984
  },
  "comparison": {
    "queryCountChange": 0.112,
    "avgLatencyChange": -0.127,
    "successRateChange": 0.007,
    "cacheHitRateChange": 0.214,
    "bytesScannedChange": 0.111
  },
  "insights": [
    "Query volume increased 11.2% week-over-week",
    "Average latency improved by 12.7%, likely due to cache hit rate improvement",
    "Cache hit rate improved by 21.4% after cache warming was enabled"
  ]
}

Implementation

@GetMapping("/compare")
public ResponseEntity<Map<String, Object>> comparePerformance(
        @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) Instant period1Start,
        @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) Instant period1End,
        @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) Instant period2Start,
        @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) Instant period2End) {
 
    UUID tenantId = SecurityUtils.getCurrentTenantId();
    Map<String, Object> comparison = analyticsService.comparePerformance(
            tenantId, period1Start, period1End, period2Start, period2End);
    return ResponseEntity.ok(comparison);
}

Comparison Use Cases

Scenario	Period 1	Period 2
Week-over-week	This week	Last week
Pre/post deployment	After deploy	Before deploy
Seasonal comparison	This month	Same month last year
A/B cache config	After config change	Before config change

Time Series Overview