Tutorial: Building with CleaveDB

Moving averages

In real-world telemetry, server loads, and retail traffic, metrics frequently exhibit noise, spikes, and non-linear patterns where standard linear regression can over-extrapolate. CleaveDB provides METHOD MOVING_AVERAGE and METHOD EXPONENTIAL to smooth out short-term fluctuations and project stable baseline estimates.

Rolling window moving average

The moving average method calculates predictions by averaging the most recent W observations in the time series:

POUR INTO server_metrics "m1" {"timestamp": "2026-10-05T08:00:00Z", "cpu_pct": 32.5}
POUR INTO server_metrics "m2" {"timestamp": "2026-10-05T09:00:00Z", "cpu_pct": 45.0}
POUR INTO server_metrics "m3" {"timestamp": "2026-10-05T10:00:00Z", "cpu_pct": 41.5}
POUR INTO server_metrics "m4" {"timestamp": "2026-10-05T11:00:00Z", "cpu_pct": 52.0}

Execute a 3-hour forecast using a sliding window of 3 periods:

FORECAST server_metrics PREDICT cpu_pct OVER timestamp NEXT 3 HOURS METHOD MOVING_AVERAGE WINDOW 3

If the WINDOW clause is omitted or set to 0, CleaveDB defaults to a 3-period rolling window.

Autoregressive projection output

CleaveDB evaluates the sliding window autoregressively: step 1 averages the last W points, and step 2 rolls forward incorporating the newly predicted value:

{
  "status": "ok",
  "method": "MOVING_AVERAGE",
  "window": 3,
  "predictions": [
    {
      "date": "2026-10-05T12:00:00+00:00",
      "predicted_cpu_pct": 46.1667
    },
    {
      "date": "2026-10-05T13:00:00+00:00",
      "predicted_cpu_pct": 46.5556
    },
    {
      "date": "2026-10-05T14:00:00+00:00",
      "predicted_cpu_pct": 48.2407
    }
  ]
}

This prevents momentary anomalies from skewing future projections.

Exponential smoothing (METHOD EXPONENTIAL)

When recent points carry more predictive weight than older historical records, use METHOD EXPONENTIAL:

FORECAST orders PREDICT volume OVER created_at NEXT 5 DAYS METHOD EXPONENTIAL

CleaveDB applies single exponential smoothing with a decay parameter (α = 0.5):

{
  "status": "ok",
  "method": "EXPONENTIAL",
  "alpha": 0.5,
  "predictions": [
    { "date": "2026-10-06", "predicted_volume": 128.5 },
    { "date": "2026-10-07", "predicted_volume": 128.5 },
    { "date": "2026-10-08", "predicted_volume": 128.5 },
    { "date": "2026-10-09", "predicted_volume": 128.5 },
    { "date": "2026-10-10", "predicted_volume": 128.5 }
  ]
}

Exponential smoothing quickly adapts to recent regime changes without being overwhelmed by distant historical outliers.

Choosing the right forecasting method