# TOPK.RESERVE

> Create a Top-K list that tracks the most frequent items in a stream of events.

URL: https://docs.hotkv.com/commands/topk-reserve/

```
TOPK.RESERVE key topk [width depth decay]
```

- Group: Top-K
- Complexity: O(1)
- HotKV Cloud: all plans
- On-Premise: no license needed

`TOPK.RESERVE` creates an empty Top-K structure at `key`. It keeps the `topk`
items seen most often, with estimated counts, in a fixed amount of memory, so
you can find heavy hitters (popular products, noisy clients, trending terms)
without storing a counter per item.

The Top-K must exist before you add to it.

## Arguments

| Argument | Effect |
| --- | --- |
| `topk` | How many items to keep, 1 to 4294967295. |
| `width` | Counters per row used to estimate counts (default 8). More counters give more accurate counts and take more memory. |
| `depth` | Number of counter rows (default 7). More rows make large errors less likely and take more memory. |
| `decay` | A value above 0 and at most 1 (default 0.9) that sets how readily rare items give way to frequent ones. |

`width`, `depth` and `decay` are given together or not at all.

## Return value

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

Error replies:

- `TopK: key already exists` if the key exists (with any type).
- `TopK: invalid k`, `TopK: invalid width`, `TopK: invalid depth`
- `TopK: invalid decay value. must be '<= 1' & '> 0'`
- `TopK: Insufficient memory to create the key`
- `ERR wrong number of arguments for 'topk.reserve' command` when only some of `width`, `depth`, `decay` are given.

## Examples

```
127.0.0.1:6379> TOPK.RESERVE trending 3
OK
127.0.0.1:6379> TOPK.INFO trending
1) k
2) (integer) 3
3) width
4) (integer) 8
5) depth
6) (integer) 7
7) decay
8) "0.9"
127.0.0.1:6379> TOPK.RESERVE trending 5
(error) TopK: key already exists
127.0.0.1:6379> TOPK.RESERVE wide 10 100 5 0.9
OK
```

## Compatibility

Same arguments and defaults as `TOPK.RESERVE` in RedisBloom.

## See also

[TOPK.ADD](https://docs.hotkv.com/commands/topk-add/index.md), [TOPK.INCRBY](https://docs.hotkv.com/commands/topk-incrby/index.md), [TOPK.LIST](https://docs.hotkv.com/commands/topk-list/index.md),
[TOPK.INFO](https://docs.hotkv.com/commands/topk-info/index.md)