Time buckets and windowing

Time series analytics almost always relies on windows: “per minute”, “last 24 hours”, “calendar month”. In SurrealDB you express these ideas with ordinary SurrealQL—filtering on timestamps or on components of complex record IDs, and grouping with functions such as time::day() where appropriate.

Time buckets

A bucket is a fixed or sliding interval that groups raw events into summaries: counts, sums, averages, or percentiles. Buckets are how dashboards show smooth lines instead of millions of raw points.

When you design buckets, choose the grain that matches how people consume the data (operations often want 1-minute or 5-minute data; executives may only need daily rollups).

Example — hourly energy readings: time::floor() snaps each ts down to the start of a duration (here 1h), and GROUP BY collapses every row in that window into one aggregate.

CREATE measurement SET ts = d"2025-04-10T09:15:00Z", kwh = 1.2;
CREATE measurement SET ts = d"2025-04-10T09:42:00Z", kwh = 0.8;
CREATE measurement SET ts = d"2025-04-10T10:05:00Z", kwh = 2.0;

SELECT
	count(), time::floor(ts, 1h) AS hour_bucket
FROM measurement
GROUP BY hour_bucket;

[
	{
		count: 2,
		hour_bucket: d'2025-04-10T09:00:00Z'
	},
	{
		count: 1,
		hour_bucket: d'2025-04-10T10:00:00Z'
	}
]

For calendar-aligned buckets (whole days or months), time::group() is often simpler than picking a duration.

Aligning windows to business time

Decide whether windows are wall-clock (calendar buckets) or relative (“last 15 minutes” rolling). Range queries on record IDs or timestamp fields should use the same convention across writers and readers so aggregates line up.

For concrete sensor and metrics examples, continue with IoT and telemetry patterns and Aggregation queries.