How to use Redis Scan

This guide will teach you how to work with the Redis SCAN command. The SCAN command is used to iterate through the keys within a specific Redis database.The SCAN command in Redis is a cursor-based iterator. Hence, the Redis server will return an updated cursor on every command call.

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:> MSET key1 value1 key2 value2 key3 value3 key4 value4 key5 value5 key6 value6


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:> SCAN 0

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:

MSET key7 value7 key8 value8 key9 value9 key10 value10 key11 value11 key12 value12

If we rerun the SCAN command, it will return the last position where the cursor stopped.> SCAN 0

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.> SCAN 13

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:

  1. COUNT
  2. MATCH


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.> SCAN 0 COUNT 15

Example output from the above command is as shown:

1) "0"

2) 1) "key4"

2) "key9"


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.


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.> SCAN 0 MATCH k*

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.> SCAN 0 MATCH k* COUNT 15

1) "0"

2) 1) "key4"

2) "key9"


11) "key1"

12) "key12"


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.

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list