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
KEYS <pattern>
SCAN <cursor> [MATCH <pattern>] [COUNT <count>] [TYPE <type>]
<pattern>: the key names to match, such asbook:*. The*stands for any characters.<cursor>: where SCAN carries on from. Start with0, then pass the cursor each reply gives you.COUNT <count>: about how many keys SCAN looks at in one call. The default is10.TYPE <type>: only keys of one data type, such asstring.
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
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"
OK
Step 2: List Keys with KEYS
valkey-cli
KEYS book:*
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
SCAN 0 MATCH book:* COUNT 100
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.

KEYS vs SCAN at a Glance
| KEYS | SCAN | |
|---|---|---|
| How it works | Goes through every key in one call | Goes through a few keys per call and returns a cursor |
| Cost of one call | Grows with the number of keys | Small, whatever the size of the database |
| While it runs | Valkey answers no one else | Other clients get answers between calls |
| Result | All matching keys at once | Matching keys over several calls; a key can come back more than once |
| Use it for | Small test databases and debugging | Apps and real servers |
Clean Up
exit
valkey-cli DEL book:1:title book:2:title book:3:title book:4:title cart:42
(integer) 5
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Running KEYS * on a large production database | Every other client waits until it finishes | Use SCAN, or valkey-cli --scan from the terminal |
Stopping after the first SCAN call | You miss keys when the cursor isn’t 0 yet | Call 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.
Related
- Valkey Tutorial — Part 2: Your First Valkey Commands with valkey-cli
- How to List All Keys in Valkey with valkey-cli --scan
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