# TOPK.ADD

> Count one occurrence of each item in a Top-K list, returning any items pushed out.

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

```
TOPK.ADD key item [item ...]
```

- Group: Top-K
- Complexity: O(n * depth), n being the items
- HotKV Cloud: all plans
- On-Premise: no license needed

`TOPK.ADD` counts one sighting of each `item` in the Top-K at `key`, in
order. When the list is full and an item outside it reaches the count of the
least frequent listed item, it takes that item's place, and the reply tells
you which item left.

The Top-K must exist (see [TOPK.RESERVE](https://docs.hotkv.com/commands/topk-reserve/index.md)). To count
several sightings at once, use [TOPK.INCRBY](https://docs.hotkv.com/commands/topk-incrby/index.md).

## Return value

An array with one element per item, the same shape in RESP2 and RESP3:

| Element | Value |
| --- | --- |
| An item left the list | Bulk string: the item that left |
| Nothing left the list | Nil (RESP3: null) |

Error replies: `TopK: key does not exist`, and `WRONGTYPE` if the key holds
another type.

## Examples

```
127.0.0.1:6379> TOPK.RESERVE trending 2 50 4 0.9
OK
127.0.0.1:6379> TOPK.ADD trending redis hotkv hotkv
1) (nil)
2) (nil)
3) (nil)
127.0.0.1:6379> TOPK.ADD trending valkey valkey
1) "redis"
2) (nil)
127.0.0.1:6379> TOPK.LIST trending
1) "hotkv"
2) "valkey"
```

## Compatibility

Same as `TOPK.ADD` in RedisBloom.

## See also

[TOPK.INCRBY](https://docs.hotkv.com/commands/topk-incrby/index.md), [TOPK.LIST](https://docs.hotkv.com/commands/topk-list/index.md), [TOPK.QUERY](https://docs.hotkv.com/commands/topk-query/index.md)