What is Redis SCAN?
As mentioned, the SCAN in Redis is a cursor-based iterator that allows you to iterate over the set of keys in a specific Redis database. The command accepts the cursor position as the argument.
The server returns an update cursor every time the command is called. Using the updated cursor as an argument in the following command call can be used.
The iteration starts when the cursor is at position 0 and stops when the cursor coming from the server is at 0.
Using SCAN – Examples
Let us take a few examples to illustrate how the SCAN command works. Start by creating a collection of keys and values as shown in the command below:
OK
The example above insert a set of dummy key and value pairs for illustration purposes.
Now that we have a database with keys and values, we can use the SCAN command to iterate over the keys.
The command can be executed as:
1) "0"
2) 1) "key4"
2) "rq:finished:default"
3) "key5"
4) "key6"
5) "key2"
6) "key3"
7) "rq:queues"
8) "key1"
9) "captains"
Once we run the command, it will iterate over the keys in the database and return all the available keys.
NOTE: The SCAN command will only return the first ten keys in the database. Since the SCAN command can fetch the first ten elements in our example, it returns an integer value of 0, as shown above.
Let’s take an example where the cursor returned from the server is not 0. If we add the keys as shown in the command below:
If we rerun the SCAN command, it will return the last position where the cursor stopped.
1) "13"
2) 1) "key4"
2) "key9"
3) "rq:finished:default"
4) "key5"
5) "key6"
6) "key8"
7) "key2"
8) "key3"
9) "key10"
10) "key7"
11) "rq:queues"
In this example, the cursor position is at 13. We can use this position to scan the remaining keys.
1) "0"
2) 1) "key11"
2) "key1"
3) "key12"
4) "captains"
Since the command fetches all the keys, in this case, it returns the cursor at position 0.
SCAN Options
The SCAN command accepts two main options:
- COUNT
- MATCH
SCAN COUNT
The count command allows you to modify how many keys the SCAN command will fetch per call. By default, the SCAN command fetches ten keys.
However, we can modify this by setting the count command.
Example output from the above command is as shown:
2) 1) "key4"
2) "key9"
…TRUNCATED…
14) "key12"
15) "captains"
In this example, we set the cursor to return 15 elements instead of the default 10. Since there are no more than 15 keys in the database, the server returns the key position at 0.
SCAN MATCH
The MATCH option allows you to SCAN for keys that match a specific pattern. For example, to return all the keys matching K*, we can do.
1) "13"
2) 1) "key4"
2) "key9"
3) "key5"
4) "key6"
5) "key8"
6) "key2"
7) "key3"
8) "key10"
9) "key7"
The above command only returns the keys matching the specified pattern.
You can use the MATCH and COUNT options in the same command.
1) "0"
2) 1) "key4"
2) "key9"
---TRUNCATED---
11) "key1"
12) "key12"
Conclusion
This guide gives you the basics usage and examples of using the Redis SCAN command. The SCAN allows you to iterate through the keys of the database using a cursor position. You can check the documentation for more SCAN variations.