Getting Started

Tutorial: Building with CleaveDB

Linear regression

When historical observations follow a steady upward or downward trajectory, METHOD LINEAR fits an Ordinary Least Squares (OLS) regression line directly over your time-series data. It evaluates historical slope and intercept, measures the goodness-of-fit via the R² metric, and projects future milestones.

Setting up sample time-series data

Consider a bucket containing sequential daily revenue records:

CleaveQLExample · Insert historical sales records

POUR INTO sales "s1" {"created_at": "2026-10-01", "total": 100.0}
POUR INTO sales "s2" {"created_at": "2026-10-02", "total": 115.0}
POUR INTO sales "s3" {"created_at": "2026-10-03", "total": 130.0}
POUR INTO sales "s4" {"created_at": "2026-10-04", "total": 145.0}

Each document stores an ISO date string in created_at and a numeric revenue figure in total.

Executing a linear forecast

Predict the next 7 days of sales by specifying the target bucket, prediction field, timestamp field, horizon, and method:

CleaveQLExample · Forecast query

FORECAST sales PREDICT total OVER created_at NEXT 7 DAYS METHOD LINEAR

CleaveDB scans the bucket, parses timestamps into Unix epochs, computes the regression coefficients via numpy.linalg.lstsq, and generates the projection.

Structured forecast response

The engine returns the model details, goodness-of-fit score, and an array of predicted future dates:

CleaveQLExample · Linear regression output

{
  "status": "ok",
  "method": "LINEAR",
  "r_squared": 1.0,
  "predictions": [
    { "date": "2026-10-05", "predicted_total": 160.0 },
    { "date": "2026-10-06", "predicted_total": 175.0 },
    { "date": "2026-10-07", "predicted_total": 190.0 },
    { "date": "2026-10-08", "predicted_total": 205.0 },
    { "date": "2026-10-09", "predicted_total": 220.0 },
    { "date": "2026-10-10", "predicted_total": 235.0 },
    { "date": "2026-10-11", "predicted_total": 250.0 }
  ]
}

Future dates are incremented automatically according to the specified DAYS delta (86,400 seconds).

Understanding the R² coefficient

The r_squared field represents the coefficient of determination (ranging from 0.0 to 1.0):

R² Range	Interpretation	Recommended Action
0.85 – 1.00	Strong linear correlation; high confidence in projected trend	Use `METHOD LINEAR` for production planning
0.50 – 0.84	Moderate variance or seasonal noise present in data	Compare against `METHOD MOVING_AVERAGE`
< 0.50	Weak linear fit; historical trend is non-linear or erratic	Switch to rolling smoothing or moving window models

Sub-daily forecasting

For infrastructure monitoring, sensor feeds, or IoT time series, you can extrapolate across smaller intervals:

CleaveQLExample · Hourly CPU utilization projection

FORECAST telemetry PREDICT cpu_pct OVER recorded_at NEXT 12 HOURS METHOD LINEAR

CleaveDB sets a delta of 3,600 seconds per step and generates hourly forecast points formatted with ISO UTC timestamps.