# SSCAN

> Iterate over the members of a set with a cursor.

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

```
SSCAN key cursor [MATCH pattern] [COUNT count]
```

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

`SSCAN` walks the set at `key` a few members at a time. 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 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.

## 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`. |

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 an array of members | 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 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`.
- `ERR NOSCORES option can only be used in ZSCAN` if you pass `NOSCORES`.

## Examples

```
127.0.0.1:6379> SADD tags "redis" "cache" "rust"
(integer) 3
127.0.0.1:6379> SSCAN tags 0 MATCH "r*"
1) "0"
2) 1) "redis"
   2) "rust"
```

## Compatibility

Same as Redis 7.4 and Valkey 8.

## See also

[SMEMBERS](https://docs.hotkv.com/commands/smembers/index.md), [SCAN](https://docs.hotkv.com/commands/scan/index.md), [HSCAN](https://docs.hotkv.com/commands/hscan/index.md),
[ZSCAN](https://docs.hotkv.com/commands/zscan/index.md)