# TS.CREATE

> Create a time series with an optional retention period and labels.

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

```
TS.CREATE key [RETENTION milliseconds] [LABELS label value [label value ...]]
```

- Group: Time series
- Complexity: O(L), L being the labels
- HotKV Cloud: Performance and Scale plans
- On-Premise: requires the time-series license feature

`TS.CREATE` creates an empty time series named `key`. A time series holds
samples (a millisecond timestamp and a floating-point value) in time order.
Add samples with [TS.ADD](https://docs.hotkv.com/commands/ts-add/index.md), read them with
[TS.RANGE](https://docs.hotkv.com/commands/ts-range/index.md) and summarize them with
[TS.AGG](https://docs.hotkv.com/commands/ts-agg/index.md).

Time series live beside the keyspace: [KEYS](https://docs.hotkv.com/commands/keys/index.md),
[EXISTS](https://docs.hotkv.com/commands/exists/index.md) and [DEL](https://docs.hotkv.com/commands/del/index.md) do not see them, and a
series name does not clash with a key of the same name. They are kept in
snapshots. In cluster mode, a series lives on the node that owns the hash
slot of its name.

Time series need the `time-series` license feature on HotKV On-Premise, and
are included in the Performance and Scale plans on HotKV Cloud. Without it,
every `TS.*` command replies
`NOLICENSE time-series requires a HotKV license. Contact sales@hotkv.com`.

## Options

| Option | Effect |
| --- | --- |
| `RETENTION milliseconds` | Drop samples older than this, measured back from the server's current time. `0` (the default) keeps samples forever. |
| `LABELS label value ...` | Attach label pairs, used to find series with [TS.LIST](https://docs.hotkv.com/commands/ts-list/index.md). |

Put `RETENTION` before `LABELS` when you use both.

The number of series a server holds is capped by the `timeseries.max-series`
setting.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Created | Simple string `OK` | Simple string `OK` |

Error replies:

- `ERR series already exists or limit reached`
- `ERR invalid RETENTION value`
- `ERR unknown option: name` for an unknown option, or a label without a value.
- `NOLICENSE ...` without the license feature.

## Examples

```
127.0.0.1:6379> TS.CREATE temp:kitchen RETENTION 604800000 LABELS room kitchen
OK
127.0.0.1:6379> TS.CREATE temp:kitchen
(error) ERR series already exists or limit reached
127.0.0.1:6379> TS.CREATE temp:hall LABELS room
(error) ERR unknown option: room
```

## Compatibility

HotKV's own time series API. `TS.CREATE` shares its name with the
RedisTimeSeries command, but takes only `RETENTION` and `LABELS`, and its
error replies differ.

## See also

[TS.ADD](https://docs.hotkv.com/commands/ts-add/index.md), [TS.RANGE](https://docs.hotkv.com/commands/ts-range/index.md), [TS.INFO](https://docs.hotkv.com/commands/ts-info/index.md),
[TS.RETENTION](https://docs.hotkv.com/commands/ts-retention/index.md), [TS.LIST](https://docs.hotkv.com/commands/ts-list/index.md), [TS.DELETE](https://docs.hotkv.com/commands/ts-delete/index.md)