Redis KEYS Command Explained

In Redis, the KEYS command returns all keys in the database matching a given pattern.

The KEYS command is intended for debugging and special operations, such as changing your keyspace layout. It should be used cautiously in production environments. The Redis documentation recommends against using KEYS in your regular application code. Instead, consider the SCAN command, which incrementally iterates the set of keys in the currently selected Redis database.

Syntax

The syntax goes like this:

KEYS pattern

Where pattern is a glob-style pattern.

The following glob-style patterns are supported:

  • h?llo matches hellohallo and hxllo
  • h*llo matches hllo and heeeello
  • h[ae]llo matches hello and hallo, but not hillo
  • h[^e]llo matches hallohbllo, … but not hello
  • h[a-b]llo matches hallo and hbllo

Use \ to escape special characters if you want to match them verbatim.

Source: Redis documentation

The * Wildcard

Here’s an example of using the * wildcard character to match all characters:

KEYS *

Sample result:

1) "listname"
2) "named_color"
3) "color"
4) "name"
5) "lastname"
6) "colour"
7) "firstname"

This returned 7 keys in my database.

We can narrow the results down by combining the * wildcard with other characters:

KEYS *name

Result:

1) "listname"
2) "name"
3) "lastname"
4) "firstname"

If we want to include keys that have characters after the name part, we can do this:

KEYS *name*

Result:

1) "listname"
2) "named_color"
3) "name"
4) "lastname"
5) "firstname"

We can also use the * wildcard to match different spellings of a word:

KEYS colo*r

Result:

1) "color"
2) "colour"

We can also include the * wildcard at the start and/or end of the string in order to expand the criteria:

KEYS *colo*r*

Result:

1) "named_color"
2) "color"
3) "colour"

The ? Wildcard

Here’s an example of using the ? wildcard character:

KEYS colo?r

Result:

1) "colour"

Notice that this example requires a single character to be at the specified position. If there’s not, then there’s not match. Therefore, we only get one result instead of the two that we got when using the * wildcard.

We can use multiple ? wildcards in a row if we want to match two, three, four, or even more characters:

KEYS ??stname

Result:

1) "listname"
2) "lastname"

And here’s what happens when we add another ? character:

KEYS ???stname

Result:

1) "firstname"

Square Brackets []

We can use square brackets to specify character classes and ranges.

Example:

KEYS l[aio]stname

Result:

1) "listname"
2) "lastname"

In this case, I was looking for either an a, an i, or an o character. The a and i characters matched, and the result was returned.

Here’s an example of specifying a range:

KEYS [f-l]*stname

Result:

1) "listname"
2) "lastname"
3) "firstname"

In this case, I used a range of f-l, which matched three keys.

Let’s change the range:

KEYS [l-z]*stname

Result:

1) "listname"
2) "lastname"

This time only two keys matched.

Here’s another one with a wider range:

KEYS [a-z]*stname

Result:

1) "listname"
2) "lastname"
3) "firstname"

Again, all three keys match.

We can use the ^ character to negate the match. In other words, we can use ^ to specify the pattern that we don’t want to match.

Example:

KEYS l[^a]stname

Result:

1) "listname"

When there are No Matches

An empty array is returned if there are no matches.

Exxample:

KEYS *age

Result:

(empty array)

We get an empty array, because there are no matches.