Skip to main content
0 reactions

Valkey KEYS vs SCAN: Which Should You Use?

valkey-cli session showing KEYS book:* and SCAN 0 MATCH book:* COUNT 100 returning the same four book keys, with SCAN returning cursor 0.
KEYS and SCAN return the same four keys here.

Valkey® has two commands for listing keys: KEYS and SCAN. On a small test database they give the same answer. On a busy server, only one of them is safe.

The Short Answer

Use SCAN in your apps and on any server that matters. KEYS is fine on a small test database like the one in this guide, and for one-off debugging.

Syntax

Plain text
KEYS <pattern>
SCAN <cursor> [MATCH <pattern>] [COUNT <count>] [TYPE <type>]
  • <pattern>: the key names to match, such as book:*. The * stands for any characters.
  • <cursor>: where SCAN carries on from. Start with 0, then pass the cursor each reply gives you.
  • COUNT <count>: about how many keys SCAN looks at in one call. The default is 10.
  • TYPE <type>: only keys of one data type, such as string.

From the KEYS (opens in a new tab) and SCAN (opens in a new tab) documentation.

Prerequisites

  • Valkey installed and running, for example with How to Install Valkey on macOS.
  • A terminal. The valkey-cli commands are the same on macOS, Ubuntu and Windows (inside WSL).

Step 1: Add a Few Keys

Bash
valkey-cli MSET book:1:title "The Paper Lantern Café" book:2:title "A Map of Quiet Places" book:3:title "The Clockmaker's Garden" book:4:title "Salt and Starlight" cart:42 "book:4"
Plain text
OK

Step 2: List Keys with KEYS

Bash
valkey-cli
Plain text
KEYS book:*
Plain text
1) "book:1:title"
2) "book:2:title"
3) "book:3:title"
4) "book:4:title"

KEYS returned every key that matches, in one reply.

Step 3: List the Same Keys with SCAN

Plain text
SCAN 0 MATCH book:* COUNT 100
Plain text
1) "0"
2) 1) "book:1:title"
   2) "book:2:title"
   3) "book:3:title"
   4) "book:4:title"

The first line, "0", is the cursor for the next call; 0 means SCAN has finished. The second part is the keys it found. With only a few keys, one call covered them all. In a big database the cursor comes back as another number, and you call SCAN again with it until it returns 0.

valkey-cli session showing KEYS book:* and SCAN 0 MATCH book:* COUNT 100 returning the same four book keys, with SCAN returning cursor 0.
KEYS and SCAN return the same four keys here.

KEYS vs SCAN at a Glance

KEYSSCAN
How it worksGoes through every key in one callGoes through a few keys per call and returns a cursor
Cost of one callGrows with the number of keysSmall, whatever the size of the database
While it runsValkey answers no one elseOther clients get answers between calls
ResultAll matching keys at onceMatching keys over several calls; a key can come back more than once
Use it forSmall test databases and debuggingApps and real servers

Clean Up

Plain text
exit
Bash
valkey-cli DEL book:1:title book:2:title book:3:title book:4:title cart:42
Plain text
(integer) 5

Common Mistakes

MistakeWhat happensDo this instead
Running KEYS * on a large production databaseEvery other client waits until it finishesUse SCAN, or valkey-cli --scan from the terminal
Stopping after the first SCAN callYou miss keys when the cursor isn’t 0 yetCall SCAN again with the returned cursor until it’s 0

FAQ

Is KEYS ever OK to use?

Yes, on a small database where a pause doesn’t matter, such as your own test server. Valkey’s documentation describes it as a command for debugging and special operations.

Why did SCAN return cursor 0 straight away?

The database was small, so one call covered all of it. With many keys, SCAN returns another number, and you keep calling it.

Does COUNT limit how many keys come back?

Not exactly. COUNT is a hint for how much work one call does, so a reply can hold more or fewer keys than the number you give.

Conclusion

KEYS is simple but makes Valkey wait until it’s done. SCAN takes a few calls, and it keeps the server answering. Make SCAN your habit.

Additional Resources

Valkey® is a registered trademark of LF Projects, LLC. Redis® is a registered trademark of Redis Ltd. Any rights therein are reserved to Redis Ltd. Other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with the Valkey project, LF Projects or Redis Ltd., and isn’t endorsed, supported or certified by them.

0 comments