skip to content

Time Series Samples

TS.ADD appends timestamped samples with retention, labels and compaction rules, and TS.RANGE aggregates them. Interviewers ask when this type is enough and when a dedicated time-series store wins.

part ofRedisread it →
on this pageshow

explore

questions

6

In Redis's time series type, what does a series hold, and how do TS.CREATE and TS.ADD build one with retention and labels?

level: juniorimportance: must knowfreq 29%

answer

  1. one key, many timestamped doubles
  2. milliseconds, not seconds
  3. age against the highest timestamp
  4. metadata on the series, not the reading
  5. auto-create, then options ignored

basics

~20 s

A Redis time series is one key of millisecond timestamps paired with double values. TS.CREATE makes it empty with RETENTION and LABELS; TS.ADD appends a sample, creates a missing key, and replies with the timestamp.

solid answer

~50 s

A time series is a Redis key of type `TSDB-TYPE` holding samples, each a 64-bit millisecond timestamp plus a double, in time order inside memory chunks. `TS.CREATE sensor:7:temp RETENTION 86400000 LABELS device 7 site berlin` makes an empty series; on an existing key it fails with `TSDB: key already exists`. `RETENTION` is a maximum sample age in milliseconds, measured against the series' highest timestamp rather than the wall clock, and 0 keeps everything. `LABELS` are name-value strings on the series, not on each sample, and they are the secondary index `TS.MRANGE` filters on. `TS.ADD key timestamp value` takes a millisecond timestamp or `*` for the server's clock, creates the key if it is missing, and replies with the sample's timestamp. Its creation options are ignored on an existing series, so `TS.ALTER` is how you change retention or labels later.

code

plaintext · 15 lines
plaintext
TS.ADD sensor:9:temp 1760000000000 19.8 RETENTION 86400000 LABELS device 9 site berlin
(integer) 1760000000000
TS.ADD sensor:9:temp 1760000001000 19.9 RETENTION 3600000 LABELS device 9 site paris
(integer) 1760000001000
TS.INFO sensor:9:temp
...
retentionTime
(integer) 86400000
...
labels
1) 1) "device"
   2) "9"
2) 1) "site"
   2) "berlin"
...

go deeper

for a junior

Recall the shape: one key, millisecond timestamps, double values. Know that TS.CREATE makes the series and TS.ADD appends to it, creating the key if needed.

for a middle

Explain that retention is measured against the series' highest timestamp, and that TS.ADD's creation options are silently ignored once the key exists, which is why TS.ALTER exists.

for a senior

Show you have run this: choose device timestamps over the server clock on purpose, and treat a label change as a TS.ALTER that replaces the whole list across the fleet.

for a principal

Connect the per-key shape to cost: one double per timestamp means a key for each metric on each device, and that count drives memory and how labels should be designed.

## What a Redis time series is The **time series type** stores real-valued measurements against the moment they were taken, such as one temperature reading a second from each device in a fleet. One series is one Redis key, and `TYPE` reports it as `TSDB-TYPE`. Each **sample** in it is a pair: - a **timestamp**, a 64-bit integer counting milliseconds since the Unix epoch - a **value**, a double Samples sit in memory **chunks** ordered by time. A key holds one value per timestamp, so a device reporting temperature and humidity needs two series, not one series with two columns. Since Redis 8.0 the type is part of Redis Open Source, and Redis Stack is superseded for 8.0 onward. A plain source build with no module configuration does not have the `TS.*` commands; a release tarball's `redis.conf`, or `redis-full.conf` from a git checkout, loads them. ## Creating a series with TS.CREATE `TS.CREATE` makes an empty series and replies `OK`. If the key already exists it fails with `TSDB: key already exists`, so it is not an idempotent setup step. Its options: | Option | What it sets | When you leave it out | |---|---|---| | `RETENTION` | Maximum sample age, in milliseconds | `ts-retention-policy`, which defaults to 0, no expiry | | `ENCODING` | `COMPRESSED` or `UNCOMPRESSED` | `COMPRESSED` | | `CHUNK_SIZE` | Initial bytes per chunk, a multiple of 8 from 48 to 1048576 | `ts-chunk-size-bytes`, default 4096 | | `DUPLICATE_POLICY` | What a repeated timestamp does | `ts-duplicate-policy`, default `BLOCK` | | `LABELS` | Name-value string pairs on the series | No labels | Two of these are worth understanding on day one. **`RETENTION` is relative to the data, not to the clock.** A sample is too old when it is further behind the series' highest reported timestamp than the retention period. A series that stops receiving writes therefore stops ageing, and its last window stays readable however much real time passes. A day is `86400000` and a year is `31536000000`, because every duration here is in milliseconds. **`LABELS` describe the series as a whole.** They cannot vary from one reading to the next. They act as a secondary index: `TS.MGET`, `TS.MRANGE`, `TS.MREVRANGE` and `TS.QUERYINDEX` find series by their labels instead of by key name. ## Adding samples with TS.ADD `TS.ADD key timestamp value` writes one sample and replies with its timestamp as an integer. - The **timestamp** is milliseconds, or `*` to take the server's clock at that moment. - The **value** is a double. Infinite values are rejected. - If the **key is missing**, `TS.ADD` creates the series and applies any `RETENTION`, `ENCODING`, `CHUNK_SIZE`, `DUPLICATE_POLICY` and `LABELS` you passed. - If the **key exists**, those same options are ignored without an error. That last point is the classic surprise. Sending `LABELS` on every write looks like it keeps metadata current, and it does nothing after the first write. `TS.ALTER` changes retention, chunk size, duplicate policy and labels on an existing series, and passing `LABELS` to it replaces the whole label list. `TS.MADD` writes many samples in one command, across one or more keys, but it does not create series. Each sample gets its own entry in the array reply, so a missing key produces an error for that sample while the others still land. ## Putting it together A typical setup for one device, in order: 1. Run `TS.CREATE` once with retention and labels, or let the first `TS.ADD` do it with the same options. 2. Send readings with `TS.ADD` or batches with `TS.MADD`, using the device's own timestamp when you trust its clock. 3. Read the newest value with `TS.GET`, and a window with `TS.RANGE`. 4. Check the configuration with `TS.INFO`, which reports `retentionTime`, `chunkSize`, `duplicatePolicy`, `labels`, `rules` and `memoryUsage`. ```text TS.CREATE sensor:7:temp RETENTION 86400000 LABELS device 7 site berlin OK TS.ADD sensor:7:temp 1760000000000 21.4 (integer) 1760000000000 TS.GET sensor:7:temp 1) (integer) 1760000000000 2) 21.4 ``` ## Mistakes to avoid - Writing timestamps in seconds. The series reads them as milliseconds near 1970, so a one-day `RETENTION` ends up keeping about 2.7 years of once-a-second readings. - Using `*` for bursts. Two writes in one millisecond get the same timestamp, and the default `BLOCK` policy turns the second into an error. - Assuming retention frees memory instantly. Reads stop at the retention window at once, while whole chunks are released only when a later append opens a new chunk.

  • Why does RETENTION not remove samples from a series that has stopped receiving data?
    Expiry compares each sample's timestamp with the series' highest timestamp, and only a newer write moves that value. With no writes the window stays where it was, so the last stretch of readings stays readable indefinitely. `RETENTION` is not a TTL. To drop an abandoned series you delete the key.
  • What does using `*` as the TS.ADD timestamp cost you?
    You record arrival time on the server instead of measurement time, so network delay and client batching end up in your data. Two writes landing in one millisecond also share a timestamp, and under the default `BLOCK` duplicate policy the second one returns an error. It suits one-off events more than high-rate ingestion.

  • RETENTION expires samples by wall-clock time, the way a TTL does.
  • TS.ADD with LABELS updates the labels of a series that already exists.
  • Labels belong to each sample, so they can change from one reading to the next.
  • TS.ADD fails unless the key was first created with TS.CREATE.
  • Time series on Redis 8 still requires installing Redis Stack.

Assumes Redis 8.10; the time series type has been part of Redis Open Source since 8.0, and before that it was the separate RedisTimeSeries module.

open as a page

In Redis, how do you use TS.CREATERULE to keep raw time series samples for a day and a downsampled series for a year?

level: middleimportance: should knowfreq 27%

basics

~20 s

Create a destination series first, with its own RETENTION, then run TS.CREATERULE source dest AGGREGATION avg 60000. Give raw a day's retention and the destination a year's. Only samples added after the rule are aggregated.

open as a page

In a Redis time series, what happens when TS.ADD repeats an existing timestamp, and how do DUPLICATE_POLICY and ON_DUPLICATE control the outcome?

level: middleimportance: should knowfreq 21%

basics

~10 s

By default the second sample fails: DUPLICATE_POLICY is BLOCK and TS.ADD replies with an error. A series can instead keep FIRST, LAST, MIN, MAX or SUM, and ON_DUPLICATE overrides that policy for one command.

open as a page

For a fleet dashboard on Redis time series, how do TS.RANGE with AGGREGATION and TS.MRANGE with FILTER and GROUPBY differ, and what do they reply?

level: middleimportance: should knowfreq 24%

basics

~20 s

TS.RANGE reads one key and can bucket it with AGGREGATION, replying with timestamp and value pairs. TS.MRANGE finds series by a label FILTER, replies per series, and GROUPBY with REDUCE combines same-timestamp values across each group.

open as a page

Devices in a Redis time series fleet upload buffered readings after hours offline; ingest slows, some writes fail and hourly rollups look wrong. How do you diagnose and fix it?

level: seniorimportance: should knowfreq 17%

basics

~20 s

Late samples take the upsert path: each rewrites a compressed chunk and each rule recomputes its bucket. Samples beyond retention are rejected, and partly trimmed buckets get overwritten. Replay oldest first and keep raw retention above lateness plus bucket.

open as a page

Your team already runs Redis and must keep fleet temperature readings: when is Redis's time series type enough, and when is a dedicated time-series database worth running?

level: principalimportance: should knowfreq 23%

basics

~20 s

The type is enough when the raw window fits in RAM, rollups are known up front, and queries are ranges and bucket aggregates. A dedicated database earns its cost when history, query variety or series count outgrow that.

open as a page