Redis Pattern Matching: How to Use KEYS and SCAN Effectively

#redis #beginners #learning

When working with Redis, you’ll often find yourself needing to retrieve keys that follow a certain pattern. Maybe you’ve stored user sessions with keys like session:user123, session:user456, and so on — and now you want to find all keys that start with session:.

Redis provides a couple of commands to help with this: KEYS and SCAN. They may seem similar at first glance, but they behave very differently, and it’s important to understand when and how to use each one.

1. Wildcard Pattern Matching in Redis

Both KEYS and SCAN support glob-style patterns, which use special wildcard characters to match multiple keys:

Pattern	Matches...
`*`	Any number of characters
`?`	Exactly one character
`[abc]`	One of the characters `a`, `b`, or `c`
`[a-z]`	Any character between `a` and `z`

For example:

KEYS user:* will match user:1, user:100, and user:abc.
KEYS session:? will match keys like session:a, session:1, but not session:ab.

2. The KEYS Command: Powerful, but Dangerous in Production

The KEYS command is simple and direct:

127.0.0.1:6379> KEYS user:*

It returns all keys matching the given pattern, and it does this in a single blocking operation. That’s the main problem — Redis will pause while collecting all the results, which can be risky in a production environment with a large number of keys.

When to Use `KEYS`

For debugging or development.
When the total number of keys is small.
When you’re sure performance won’t be affected.

3. The SCAN Command: Safe and Cursor-Based

To safely scan large keyspaces, Redis provides the SCAN command. It’s a cursor-based iterator, meaning it doesn’t return all matching keys in one go. Instead, it gives you a small subset of keys and a cursor to continue from.

127.0.0.1:6379> SCAN 0 MATCH user:* COUNT 10

0 is the initial cursor position.
MATCH is the pattern filter.
COUNT is a hint for how many keys to return (not guaranteed).

You repeat the command using the cursor returned in the previous response, until the cursor returns to 0, which indicates the end of the scan.

Example Output

1) "23"                       # next cursor
2) 1) "user:1"
   2) "user:2"

You then call SCAN 23 MATCH user:* COUNT 10 to continue.

When to Use `SCAN`

In production systems.
When working with a large number of keys.
When you need non-blocking access.

4. Best Practices

Avoid KEYS in production environments.
Always use SCAN for scalable, safe key iteration.
Consider namespacing your keys (e.g., user:, order:, etc.) to make pattern matching easier.
Don’t rely on COUNT returning exactly that number — it’s just a suggestion to Redis.

Wrapping Up

Pattern-based key retrieval is a powerful feature in Redis, but like all powerful tools, it should be used with care. For quick lookups in development, KEYS is handy. For scalable and production-safe iteration, SCAN is your best bet.

If you're a software developer who enjoys exploring different technologies and techniques like this one, check out LiveAPI. It’s a super-convenient tool that lets you generate interactive API docs instantly.

LiveAPI helps you discover, understand and use APIs in large tech infrastructures with ease!

So, if you’re working with a codebase that lacks documentation, just use LiveAPI to generate it and save time!

You can instantly try it out here! 🚀