YouTipKeys Scan
## Redis SCAN Command
The Redis **SCAN** command is used to incrementally iterate over the keys in the current Redis database.
Unlike the `KEYS` command, which can block the Redis server when running against large databases, `SCAN` is a cursor-based iterator. This means it retrieves keys in a non-blocking, page-by-page manner, making it safe for production environments.
---
## How SCAN Works
The `SCAN` command is cursor-based. Every time you call it, the server returns a two-element multi-bulk reply:
1. **The next cursor**: A new cursor value to be used in the next `SCAN` call.
2. **The list of elements**: An array of keys retrieved in the current iteration.
To start a new iteration, pass `0` as the cursor. To continue iterating, pass the cursor returned by the previous call. The iteration is complete when the returned cursor is `0`.
### Related Commands
Redis provides specialized scan commands for different data structures:
* (https://redis.io/commands/sscan/) – Iterates over elements in a Set.
* (https://redis.io/commands/hscan/) – Iterates over fields and values in a Hash.
* (https://redis.io/commands/zscan/) – Iterates over elements and scores in a Sorted Set.
---
## Syntax
The basic syntax for the Redis `SCAN` command is as follows:
```redis
SCAN cursor
```
### Parameter Descriptions
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `cursor` | Integer | The cursor value. Use `0` to start a new iteration, and use the returned cursor value for subsequent calls. |
| `MATCH pattern` | String | *Optional.* Filters keys matching a glob-style pattern (e.g., `user:*`). |
| `COUNT count` | Integer | *Optional.* Provides a hint to Redis about the number of keys to return per call. The default is `10`. |
| `TYPE type` | String | *Optional (Redis 6.0+).* Filters keys matching a specific data type (e.g., `string`, `list`, `set`). |
### Available Version
* Available since Redis version **2.8.0**.
### Return Value
An array containing two elements:
* The first element is the next cursor (represented as a string).
* The second element is an array of keys found during the current scan.
---
## Examples
### Basic Iteration
The following example demonstrates how to iterate through keys using the `SCAN` command.
**Step 1: Start the iteration with cursor `0`**
```redis
redis 127.0.0.1:6379> SCAN 0
1) "17" # The cursor to use in the next call
2) 1) "key:12"
2) "key:8"
3) "key:4"
4) "key:14"
5) "key:16"
6) "key:17"
7) "key:15"
8) "key:10"
9) "key:3"
10) "key:7"
11) "key:1"
```
**Step 2: Continue the iteration using the returned cursor `17`**
```redis
redis 127.0.0.1:6379> SCAN 17
1) "0" # Cursor is 0, indicating the iteration is complete
2) 1) "key:5"
2) "key:18"
3) "key:0"
4) "key:2"
5) "key:19"
6) "key:13"
7) "key:6"
8) "key:9"
9) "key:11"
```
---
## Key Considerations & Best Practices
When using the `SCAN` command in production, keep the following behaviors in mind:
1. **No Blocking**: Unlike `KEYS`, `SCAN` does not block the Redis server. It can be safely used in production environments with millions of keys.
2. **Duplicate Keys**: A full iteration may occasionally return duplicate keys. Your application logic should handle duplicates (e.g., by using a Set to store results).
3. **Key Changes During Scan**: If a key is added or removed during an active iteration, `SCAN` does not guarantee whether the change will be reflected in the output.
4. **The COUNT Parameter**: The `COUNT` parameter is only a **hint** for the amount of work to do per iteration. Redis may return more or fewer elements than requested, and it can even return an empty list of elements with a non-zero cursor.
5. **Termination**: The iteration is only complete when the returned cursor is exactly `"0"`. Do not assume the iteration is complete just because the returned list of keys is empty.