# SCAN

> Iterate over the keys of the current database with a cursor.

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

```
SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]
```

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

`SCAN` walks the keyspace a little at a time. Start with cursor `0`, then pass
the cursor each reply returns into the next call, until a reply's cursor is
`0` again. Each call returns a page of key names. Unlike
[KEYS](https://docs.hotkv.com/commands/keys/index.md), no single call has to look at the whole database.

A full iteration returns every key that existed for the whole iteration
exactly once, however the keyspace changes in the meantime. Keys added or
removed during the iteration may or may not appear.

## Options

| Option | Effect |
| --- | --- |
| `MATCH pattern` | Return only keys matching this glob pattern (same syntax as [KEYS](https://docs.hotkv.com/commands/keys/index.md)). The filter is applied after the page is read, so a page can be empty while the cursor is not `0`. |
| `COUNT count` | A hint for how much work to do per call. Default `10`; must be at least `1`. |
| `TYPE type` | Return only keys of this type, using the names [TYPE](https://docs.hotkv.com/commands/type/index.md) replies (`string`, `list`, `set`, `zset`, `hash`, `stream`, ...), compared without case. A name that is no type returns an empty, finished scan. |

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Always | Array of two elements: the next cursor as a bulk string, then an array of key names | Same |

Errors:

- `ERR invalid cursor` when the cursor is not an unsigned integer.
- `ERR value is not an integer or out of range` when `COUNT` is not an integer.
- `ERR syntax error` for `COUNT` below 1, an option without its value, or an
  unknown option.
- `ERR NOSCORES option can only be used in ZSCAN` if you pass `NOSCORES`.

## Examples

```
127.0.0.1:6379> MSET user:1 "ada" user:2 "grace" order:1 "book"
OK
127.0.0.1:6379> SCAN 0 MATCH user:* COUNT 100
1) "0"
2) 1) "user:1"
   2) "user:2"
127.0.0.1:6379> SCAN 0 TYPE list
1) "0"
2) (empty array)
```

## Compatibility

Same options, reply shape and errors as Redis 7 and Valkey 8. Redis and
Valkey may return a key more than once during an iteration; HotKV does not,
but code that tolerates duplicates works unchanged.

## See also

[KEYS](https://docs.hotkv.com/commands/keys/index.md), [TYPE](https://docs.hotkv.com/commands/type/index.md),
[SSCAN](https://docs.hotkv.com/commands/sscan/index.md), [HSCAN](https://docs.hotkv.com/commands/hscan/index.md),
[ZSCAN](https://docs.hotkv.com/commands/zscan/index.md)