Redis SCAN and MATCH Command Tutorial


This tutorial will provide explanations and examples on how to use the basic Redis Scan and Match command and how the commands will iterate through the available keys within a database. SCAN is a commonly used command and is a cursor-based approach for iterating over data structures set in the database. The MATCH command is used to iterate elements that only match a specified pattern.


  • Redis must be properly installed and configured. Redis can be downloaded from their website:
  • The Redis server must be running in the background.

What is a Redis SCAN?

  • The Redis SCAN command permits iterations to the set of keys within the database while returning a small amount per call. This is helpful in production applications and accepts a cursor or position as a parameter.

  • Using the parameters will result in the server returning an update cursor together with every command that is called.

  • The updated cursor can then be used as an argument for the next call.

  • When the cursor is set to “0,” the iteration will start and will only terminate when zero is returned by the cursor coming from the server.

SCAN Guarantees

  • The Redis SCAN function guarantees obtaining a full iteration all of the elements that exists within the collection, from beginning to end.

  • The Redis SCAN function will never return elements that do not exist, from beginning to end, in a collection.

The SCAN COUNT option

  • The COUNT can be defined within a scan that allows for overwriting the default returned for every iteration.
  • This allows for specifying the number(s) of work done per call.
  • Can change the COUNT from every iteration.

The MATCH Option

  • As the name implies, the MATCH option iterates elements that will only match a specified pattern. For example:
  1. SCAN 0 MATCH some_string: This SCAN and MATCH will only match elements with the phrase “some_string.”
  2. SCAN 0 MATCH a: A wild card, such as “a“, can be used if part of specific expression is unknown.

SCAN used with other data types

This section will explain what other data types are associated with SCAN.

  • ZSCAN: Used with sorted sets. It will return an array of elements with a corresponding score.
  • SSCAN: This is used with sets and will return the lists of its members.
  • HSCAN: Used with hashes and will return an array of elements with the corresponding field and value.

Redis SCAN and MATCH Examples

This section will provide examples that will further explains the details previously discussed.

First, create a sample dataset by executing the following steps, in sequence:

    1. Ensure the Redis server is running.
    1. Connect to the Redis server using the redis-cli via command line.
    1. Execute the following command to create a basic database:> MSET mkey1 "1" mkey2 "2" mkey3 "3" mkey4 "4" mkey5 "5" mkey6 "6" mkey7 "7" mkey8 "8" mkey9 "9" mkey10 "10"

The above code employs the Redis command MSET with a value of keys from mkey1 to mkey10.

With the database now created, use the following command to scan the database:> SCAN 0
1) "0"
2) 1) "mkey9"
2) "mkey6"
3) "mkey4"
4) "mkey5"
5) "mkey8"
6) "mkey7"
7) "mkey2"
8) "mkey1"
9) "mkey10"
10) "mkey3"

It is important to remember that the default count of the SCAN command is “10”. Since there are only 10 keys to iterate through, the cursor returns “0” that indicates that the SCAN has managed to get all the keys contained in the database.

The COUNT option can also be performed using the following command:> SCAN 0 COUNT 5
1) "14"
2) 1) "mkey9"
2) "mkey6"
3) "mkey4"
4) "mkey5"
5) "mkey8"> SCAN 14
1) "0"
2) 1) "mkey7"
2) "mkey2"
3) "mkey1"
4) "mkey10"
5) "mkey3"

As shown in the above code, because of the option COUNT having a value “5,” the server returns five random keys with a cursor of 14. The scan can then be continued using that value.

  • We can also perform the MATCH option using the following command. SCAN 0 MATCH mkey1*.> SCAN 0 MATCH mkey1*
1) "0"
2) 1) "mkey1"
2) "mkey10"

Since there are 10 keys, the server returns mkey1 and mkey10.


This tutorial provided explanations and examples on how to use the basic Redis SCAN and MATCH command. The article specifically covered what the Redis SCAN and MATCH command are used for and the options for when to use each. The tutorial also provided Redis SCAN and MATCH examples, specifically the COUNT option. When using the SCAN command, it is important to remember that the system default count 10.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.