Skip to main content

​
Description

Returns all keys matching a glob-style pattern. This command should be used with caution in production environments as it can impact performance on large databases.
Consider using SCAN instead of KEYS for production use cases. KEYS blocks the server until it completes, while SCAN provides an incremental iteration approach.

​
Method Signature

keys(pattern: string): Promise<string[]>

​
Parameters

​
pattern
string
required
The glob-style pattern to match keys against. Supported glob patterns:
  • * matches any number of characters (including zero)
  • ? matches exactly one character
  • [abc] matches one character from the set
  • [^abc] matches one character not in the set
  • [a-z] matches one character from the range
  • \ escapes special characters

​
Return Value

​
result
string[]
Array of keys matching the pattern. Returns an empty array if no keys match.

​
Examples

​
Match all keys

await redis.set("user:1", "Alice");
await redis.set("user:2", "Bob");
await redis.set("post:1", "Hello");

const allKeys = await redis.keys("*");
console.log(allKeys); // ["user:1", "user:2", "post:1"]

​
Match with prefix

const userKeys = await redis.keys("user:*");
console.log(userKeys); // ["user:1", "user:2"]

​
Match with wildcard in middle

await redis.set("user:1:name", "Alice");
await redis.set("user:1:email", "[email protected]");
await redis.set("user:2:name", "Bob");

const user1Keys = await redis.keys("user:1:*");
console.log(user1Keys); // ["user:1:name", "user:1:email"]

​
Match single character

await redis.set("key1", "a");
await redis.set("key2", "b");
await redis.set("key10", "c");

const keys = await redis.keys("key?");
console.log(keys); // ["key1", "key2"] (not key10)

​
Match character range

await redis.set("user:a", "Alice");
await redis.set("user:b", "Bob");
await redis.set("user:z", "Zoe");

const keys = await redis.keys("user:[a-c]");
console.log(keys); // ["user:a", "user:b"] (not user:z)

​
No matches

const keys = await redis.keys("nonexistent:*");
console.log(keys); // []

​
Performance Considerations

KEYS is a blocking operation that scans the entire keyspace. For production use:
  • Use SCAN for incremental iteration
  • Avoid using KEYS on large databases
  • Consider using key naming schemes that allow targeted queries

​
See Also

  • scan - Incrementally iterate over keys
  • exists - Check if specific keys exist

Build docs developers (and LLMs) love

Get started for freeTalk to us