# ZSCAN

> Iterate over the members and scores of a sorted set with a cursor.

URL: https://docs.hotkv.com/commands/zscan/

```
ZSCAN key cursor [MATCH pattern] [COUNT count] [NOSCORES]
```

- Group: Sorted set
- Complexity: O(1) for every call, O(N) for a full iteration
- HotKV Cloud: all plans
- On-Premise: no license needed

`ZSCAN` walks the sorted set at `key` a few members at a time, returning each
member with its score (or the members alone with `NOSCORES`). Start with cursor `0`; each reply gives you the next
cursor to pass in. The iteration is complete when the server returns cursor
`0` again.

Members that stay in the sorted set for the whole iteration are returned at
least once. A member can be returned more than once, and members added or
removed during the iteration may or may not be returned. The order of members
is not guaranteed; use [ZRANGE](https://docs.hotkv.com/commands/zrange/index.md) for ordered access.

## Options

| Option | Effect |
| --- | --- |
| `MATCH pattern` | Return only members that match the glob-style `pattern`. Filtering happens after members are fetched, so a call can return nothing and still have a non-zero cursor. |
| `COUNT count` | A hint for how much work to do per call. Default `10`. Must be at least `1`. |
| `NOSCORES` | Return only the members, without their scores. |

The cursor is checked first, then the key's type, then the options; when the
key does not exist, the options are not checked and the reply is an empty
page.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Success | Two-element array: the next cursor as a bulk string, then a flat array of member, score, member, score, ... (scores as bulk strings). With `NOSCORES`, the flat array holds the members only. | Same |
| Key does not exist | `["0", []]` | Same |

Errors:

- `ERR invalid cursor` if `cursor` is not an unsigned integer.
- `WRONGTYPE` if `key` holds a value that is not a sorted set.
- `ERR value is not an integer or out of range` if the `COUNT` value is not an
  integer, and `ERR syntax error` if it is below `1`, an option is unknown, or
  an option is missing its value.
- `ERR NOVALUES option can only be used in HSCAN` if you pass `NOVALUES`.

## Examples

```
127.0.0.1:6379> ZADD board 10 "alice" 20 "bob" 30 "anna"
(integer) 3
127.0.0.1:6379> ZSCAN board 0 MATCH "a*"
1) "0"
2) 1) "alice"
   2) "10"
   3) "anna"
   4) "30"
127.0.0.1:6379> ZSCAN board 0 NOSCORES
1) "0"
2) 1) "alice"
   2) "bob"
   3) "anna"
```

## Compatibility

Same as Redis 8.0 and Valkey 8. `NOSCORES` is accepted by `ZSCAN` only: `SCAN`, `SSCAN` and `HSCAN` answer `ERR NOSCORES option can only be used in ZSCAN`.

## See also

[ZRANGE](https://docs.hotkv.com/commands/zrange/index.md), [SCAN](https://docs.hotkv.com/commands/scan/index.md), [SSCAN](https://docs.hotkv.com/commands/sscan/index.md),
[HSCAN](https://docs.hotkv.com/commands/hscan/index.md)