skip to content

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.