Downsampling — a retention pyramid

Long-range queries stay tractable by pre-aggregating old chunks into coarser tiers (5 m, 1 h) and dropping the originals — but each tier is materialized as a real series with its own head chunk, postings, and disk chunks, not a query-time hint.

Previously

Cardinality bounds width. Retention bounds depth — and downsampling is how depth stays affordable.

Scene 10

Downsampling: a retention pyramid

Watch
Try it
Predict
Capture

What to watch for

Watch a query range slide across three tiers. A 1-day range is served by the raw tier; a 60-day range falls through to the 5 m rollup; a 1-year range drops to the 1 h rollup. The engine always picks the coarsest tier that fully covers the range.

Implementation

Highlighted lines are the ones running in the diagram right now.

RuleEngine.evaluateRecordingRule

every rule.interval, write the result back as a NEW series

1def evaluateRecordingRule(rule, window):
2    # rule.expr e.g. rate(http_requests_total[5m])
3    samples = promql.eval(rule.expr, window)
4    for labels, value in samples:
5        series = tsdb.getOrCreateSeries(
6            name = rule.name,  # job:http_requests:rate5m
7            labels = labels,
8        )
9        series.headChunk.append(now(), value)
10        postings.index(series.id, labels)
11    # real bytes, real cardinality, real cost

QueryEngine.pickTier

find the coarsest tier that fully covers query.range

1def pickTier(query):
2    # tiers ordered finest -> coarsest
3    tiers = [raw, rate5m, rate1h]
4    for tier in reversed(tiers):  # try coarsest first
5        if tier.retentionDays >= query.range.days:
6            covers = tier
7    # coarsest tier that still reaches back far enough
8    return covers.lookupSeries(query.matchers)

Retention.dropExpiredChunks

per-tier retention — old chunks get unlinked

1def dropExpiredChunks(tier):
2    cutoff = now() - tier.retentionDays * day
3    for series in tier.allSeries():
4        for chunk in series.chunks:
5            if chunk.maxTime < cutoff:
6                series.chunks.remove(chunk)
7                disk.unlink(chunk.file)
8                postings.maybeGC(series.id)
9    # raw: 7d  |  rate5m: 90d  |  rate1h: 730d

Where this sits in Build a Prometheus-style time-series database

Scene 10 of 12. Aggregate old chunks into 5-minute, then 1-hour buckets, dropping originals as you go. Recording rules materialize — they cost storage.

Up next. We have a complete single-node TSDB. But what about replication, HA, and 100-node clusters? That story is shorter than you'd think.

All 12 scenes in Build a Prometheus-style time-series database · Every curriculum

Built with Arqly

Every scene in Build a Prometheus-style time-series database builds on the one before it.All 12 Build a Prometheus-style time-series database scenes