# TS.ADD

> Append a sample to a time series.

URL: https://docs.hotkv.com/commands/ts-add/

```
TS.ADD key <timestamp | *> value
```

- Group: Time series
- Complexity: O(1), plus the samples retention removes
- HotKV Cloud: Performance and Scale plans
- On-Premise: requires the time-series license feature

`TS.ADD` appends a sample to the time series `key` and returns the timestamp
it was stored with. The series must already exist (see
[TS.CREATE](https://docs.hotkv.com/commands/ts-create/index.md)).

## Arguments

| Argument | Meaning |
| --- | --- |
| `timestamp` | Unix time in milliseconds. `*`, or any value of 0 or less, uses the server's current time. |
| `value` | The sample value, a floating-point number. |

Samples are kept in time order. A timestamp older than the series' last
sample is not rejected: the sample is stored with the last sample's
timestamp instead. Several samples can share a timestamp. Check the returned
timestamp if this matters to you.

After adding, samples older than the series' retention are dropped, and the
sample is copied to the destination of any [TS.DOWNSAMPLE](https://docs.hotkv.com/commands/ts-downsample/index.md)
rule.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Added | Integer: the timestamp used | Integer |

Error replies:

- `ERR series not found`
- `ERR invalid timestamp` and `ERR invalid value`
- `NOLICENSE ...` without the `time-series` license feature.

## Examples

```
127.0.0.1:6379> TS.CREATE temp:kitchen LABELS room kitchen
OK
127.0.0.1:6379> TS.ADD temp:kitchen 1700000000000 21.5
(integer) 1700000000000
127.0.0.1:6379> TS.ADD temp:kitchen 1699999990000 21.4
(integer) 1700000000000
127.0.0.1:6379> TS.ADD temp:garage 1700000000000 9
(error) ERR series not found
```

## Compatibility

HotKV's own time series API. Unlike RedisTimeSeries `TS.ADD`, it does not
create the series and has no duplicate or out-of-order policy options: an
older timestamp is stored as the last one.

## See also

[TS.CREATE](https://docs.hotkv.com/commands/ts-create/index.md), [TS.RANGE](https://docs.hotkv.com/commands/ts-range/index.md), [TS.AGG](https://docs.hotkv.com/commands/ts-agg/index.md)