Using the Scan Commands in Redis
Traducciones al EspañolEstamos traduciendo nuestros guías y tutoriales al Español. Es posible que usted esté viendo una traducción generada automáticamente. Estamos trabajando con traductores profesionales para verificar las traducciones de nuestro sitio web. Este proyecto es un trabajo en curso.
Redis is a NoSQL database, exceptional for storing data structures in memory. Between that and its low-latency performance, Redis has become a go-to tool for web applications needing efficient caching and messaging storage.
This guide covers Redis’s SCAN commands, which provide a cursor-based method for incremental iterations through data collection. Here, get everything you need to start using these commands in your Redis instance — from an overview of the basics to advanced options.
Before You Begin
Familiarize yourself with our Getting Started with Linode guide and complete the steps for setting your Linode’s hostname and timezone.
This guide uses
sudowherever possible. Complete the sections of our How to Secure Your Server guide to create a standard user account, harden SSH access, and remove unnecessary network services.
Update your system.
On Debian and Ubuntu, use the following command:
sudo apt update && sudo apt upgrade
On AlmaLinux, CentOS (8 or later), or Fedora, use the following command:
sudo dnf upgrade
Follow the instructions in our How to Install a Redis Server guide to install a Redis server and command-line interface (CLI). Be sure to use the drop-down menu at the top of that page to select your Linux distribution and get the appropriate steps.
sudo. If you’re not familiar with the
sudocommand, see the Linux Users and Groups guide.
What Is the SCAN Command?
Redis’s SCAN commands each iterate incrementally over a given kind of collection, using a cursor-based approach.
When you call a SCAN command, you provide a cursor location, usually starting at the beginning of a collection. With each call, the command returns a limited set of data from the collection and a new cursor location, continuing further into the collection. Thus, each subsequent call can take the previously returned cursor location as input, advancing the cursor through the collection with each iteration.
The SCAN commands are especially useful when it comes to working with large and/or more complicated data sets. They only fetch the immediate entry or entries at the cursor, minimizing the time the server is tied up. Compare that to the effect of tying up the server when fetching the entirety of a large collection.
Types of SCAN Commands
Redis has four SCAN commands, each one dealing with a different type of collection.
Following are the four commands, each accompanied by a description of the kind of collection it covers:
SCANiterates over all the keys in the current database.
SSCANiterates over the elements in a given set.
ZSCANiterates over the elements and corresponding scores in a given sorted set.
HSCANiterates over the elements in a given hash.
Generally, these commands all operate similarly. The main difference is that all of these commands except for the
SCAN command itself take a key as an argument. This is required for
HSCAN to identify the objects they need to iterate over.
The instructions in this guide, while usually giving examples with the
SCAN command, are designed to work for all four commands. Where this is not possible or where there are differences, the guide clearly notes that.
How to Use the SCAN Commands
These next two sections walk you through how to use Redis’s SCAN commands, starting from the basics and progressing to more advanced options. Along the way, you can find examples of the commands’ usage to apply the concepts.
The examples all use data that you can load into your Redis instance using the following series of commands:
MSET key_1 "Value 1" key_2 "Value 2" key_3 "Value 3" key_4 "Value 4" key_5 "Value 5" key_6 "Value 6" key_7 "Value 7" key_8 "Value 8" key_9 "Value 9" key_10 "Value 10" key_11 "Value 11" key_12 "Value 12" key_13 "Value 13" key_14 "Value 14" key_15 "Value 15" key_16 "Value 16" SADD example_set 1 3 5 7 9 11 13 15 17 19 21 23 25 27 29 31 ZADD example_sorted_set 2 "Element 1" 4 "Element 2" 6 "Element 3" 8 "Element 4" 10 "Element 5" 12 "Element 6" 14 "Element 7" 16 "Element 8" 18 "Element 9" 20 "Element 10" 22 "Element 11" 24 "Element 12" 26 "Element 13" 28 "Element 14" 30 "Element 15" 32 "Element 16" HSET example_hash field_1 "Field 1" field_2 "Field 2" field_3 "Field 3" field_4 "Field 4" field_5 "Field 5" field_6 "Field 6" field_7 "Field 7" field_8 "Field 8" field_9 "Field 9" field_10 "Field 10" field_11 "Field 11" field_12 "Field 12" field_13 "Field 13" field_14 "Field 14" field_15 "Field 15" field_16 "Field 16"
Some of this data is not used directly in the examples that follow. However, the data set covers all of the types of collections the SCAN commands can be used on. So you can feel free, as the guide progresses, to substitute different variants of the SCAN command, and see the effects.
Basic Usage of the SCAN Commands
SCAN command takes one argument, the starting cursor position. Generally, you want to start with
0 as the cursor position, as it identifies the start of the collection.
The command then returns an array of two values:
First, the new cursor position to use in your next call of the command.
Second, an array of values retrieved from the collection.
Following is the demonstration of the
1) "14" 2) 1) "key_14" 2) "key_12" 3) "key_15" 4) "key_8" 5) "key_3" 6) "key_13" 7) "key_4" 8) "key_16" 9) "key_10" 10) "key_11"
When the returned cursor position is
0, Redis has iterated to the end of the collection.
The other SCAN commands add another required argument before the starting cursor position. This is the key for the collection to be iterated over:
HSCAN example_hash 0
In the above example,
example_hash should be the key for a value with a data type matching the SCAN command — in this case, a hash value.
The number of values returned by the SCAN commands varies. However, in the next section, you can see how to use the
COUNT option to generally dictate how many results you want from the commands.
Options for the SCAN Commands
The SCAN commands have three options that you can use to enhance or control the results. Each of these options is covered below, complete with examples showing how you can use them.
COUNToption can be added to a SCAN command to dictate how many results you would like from the SCAN command. Typically, a SCAN command comes back with about 10 entries per query. The
COUNToption tells Redis to, instead, attempt to fetch a specified number of entries per query:
SCAN 4 COUNT 2
1) "12" 2) 1) "key_8" 2) "key_3"
COUNToption is not a guarantee. There may be variances in the number of results, despite the use of this option. However, using the
COUNToption generally does control the number of results.
MATCHoption can be appended to a SCAN command to limit your query to only keys that match a given glob-style search pattern:
SCAN 0 MATCH *_1* COUNT 20
1) "0" 2) 1) "key_14" 2) "key_12" 3) "key_15" 4) "key_13" 5) "key_16" 6) "key_10" 7) "key_11" 8) "key_1"`
However, it is important to know that the
SCANcommand first fetches its results and then applies the
MATCHpattern filter. So, some iterations of the
SCANcommand may show no results, even if there are matching results within the collection. Those results show on the command iteration covering the matching keys.
TYPEoption can be used with the
SCANcommand to limit results to only keys matching a specified type.
SCAN 0 TYPE hash COUNT 20
SCANcommand here fetches results first and then applies the
TYPEfilter. So, a given
SCANcommand may return no results when a
TYPEfilter is used even if there are keys of the specified type in the collection. Those keys show up on the command iteration that covers their locations in the collection.
TYPEoption for the
SCANcommand is only supported in Redis 6 or later. Attempting to use this option in the earlier Redis version results in a syntax error.
With that, you are ready to start making use of SCAN commands on your Redis instance. These commands can provide effective methods for dealing with large and complex data sets. And the tools discussed in this guide help you to make the most of these commands to efficiently handle your data.
Want to continue learning about Redis, and get the most effective use out of your server? Thankfully, we have plenty of guides on using Redis that can help you navigate Redis data types, configurations, and more.
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
This page was originally published on