VALKEY-KEYSPACE(7)

✨ VALKEY-KEYSPACE ✨

okay bestie, welcome to valkey-keyspace(7) — the Valkey manual's whole entire dissertation on keyspace, and yes we're gonna read all of it together, hand in hand, no skimming 💖

---

🌸 NAME 🌸

valkey-keyspace — Keyspace. that's it, that's the name. the whole vibe is keys. 🎀

---

💅 DESCRIPTION 💅

so. Valkey keys are binary safe, which means literally any binary sequence can be a key. like, a cute little string like “foo”? valid. the raw contents of a JPEG file? also valid, apparently, and honestly? iconic behavior. even the empty string is a valid key. not me being a valid key with zero content 💀

but there's a few more rules about keys, and they matter, so pay attention bestie:

• Very long keys are not a good idea. like, a key of 1024 bytes? no babe, don't. not only is it giving memory-hungry, but looking that key up in the dataset may require several costly key-comparisons. even when your whole task is just matching the existence of a large value, hashing it (for example with SHA1) is a better idea — especially from the memory and bandwidth perspective. 🧚
• Very short keys are often not a good idea either. there's genuinely little point in writing u1000flw as a key when you could just write user:1000:followers. the latter is more readable and the added space is minor compared to the space used by the key object itself and the value object. yes, short keys will obviously consume a bit less memory, but your job is to find the right balance. main character energy is finding balance. 👑
• Try to stick with a schema. for instance object-type:id is a good idea, as in user:1000. dots or dashes are often used for multi-word fields, as in comment:4321:reply.to or comment:4321:reply-to. slay, consistency. 🌈
• The maximum allowed key size is 512 MB. periodt.

---

🔍 Altering and querying the key space 🔍

there are commands that aren't defined on any particular type, but are super useful for interacting with the space of keys itself — so you can use them with keys of any type. versatile queens. 💜

for example, the EXISTS command returns 1 or 0 to signal whether a given key exists or not in the database, while the DEL command deletes a key and its associated value, whatever that value is.

> set mykey hello
OK
> exists mykey
(integer) 1
> del mykey
(integer) 1
> exists mykey
(integer) 0

from the examples you can also see how DEL itself returns 1 or 0 depending on whether the key was removed (it existed) or not (there was no such key with that name). so like, DEL is out here reporting its own success rate. we love a transparent queen. 🙈

there are many keyspace related commands, but the above two are the essential ones — together with the TYPE command, which returns the kind of value stored at the specified key:

> set mykey x
OK
> type mykey
string
> del mykey
(integer) 1
> type mykey
none

---

⏰ Key expiration ⏰

before we move on, we have to look at an important Valkey feature that works regardless of the type of value you're storing: key expiration. 🦋

key expiration lets you set a timeout for a key, also known as a “time to live”, or “TTL”. when the time to live elapses, the key is automatically destroyed. gone. vanished. no notes. 💀

a few important notes about key expiration:

• They can be set both using seconds or milliseconds precision.
• However the expire time resolution is always 1 millisecond.
• Information about expires are replicated and persisted on disk, and the time virtually passes when your Valkey server remains stopped — this means that Valkey saves the date at which a key will expire. so even when it's napping, the clock is clocking. 😭

use the EXPIRE command to set a key's expiration:

> set key some-value
OK
> expire key 5
(integer) 1
> get key (immediately)
"some-value"
> get key (after some time)
(nil)

the key vanished between the two GET calls, since the second call was delayed more than 5 seconds. the way that key simply stopped existing mid-conversation… 😭

in the example above we used EXPIRE in order to set the expire (it can also be used in order to set a different expire to a key already having one, like PERSIST can be used in order to remove the expire and make the key persistent forever). however we can also create keys with expires using other Valkey commands. for example using SET options:

> set key 100 ex 10
OK
> ttl key
(integer) 9

the example above sets a key with the string value 100, having an expire of ten seconds. later the TTL command is called in order to check the remaining time to live for the key.

in order to set and check expires in milliseconds, check the PEXPIRE and the PTTL commands, and the full list of SET options. ✨

---

🧭 Navigating the keyspace 🧭

🎀 Scan 🎀

to incrementally iterate over the keys in a Valkey database in an efficient manner, you can use the SCAN command.

since SCAN allows for incremental iteration, returning only a small number of elements per call, it can be used in production without the downside of commands like KEYS or SMEMBERS that may block the server for a long time (even several seconds) when called against big collections of keys or elements. no blocking, no crying. 🫶

however, while blocking commands like SMEMBERS are able to provide all the elements that are part of a Set in a given moment, the SCAN family of commands only offer limited guarantees about the returned elements, since the collection that we incrementally iterate can change during the iteration process. it's giving "the vibe may shift mid-scan" and honestly, same. 🦋

🔑 Keys 🔑

another way to iterate over the keyspace is to use the KEYS command, but this approach should be used with care, since KEYS will block the Valkey server until all keys are returned.

Warning: consider KEYS as a command that should only be used in production environments with extreme care. 😭

KEYS may ruin performance when it is executed against large databases. this command is intended for debugging and special operations, such as changing your keyspace layout. don't use KEYS in your regular application code. if you're looking for a way to find keys in a subset of your keyspace, consider using SCAN or sets instead. bestie, i'm begging you. 🙏

supported glob-style patterns:

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

use \ to escape special characters if you want to match them verbatim. yes, backslash, the escape hatch of the pattern world. 🎀

---

okay that's the whole page and you ate it UP. 👑 this was Valkey manual version 9.0.0, dated 2025-10-21, and it's VALKEY-KEYSPACE(7) — now go forth and use a schema, set some TTLs, and please stop running KEYS * in prod. love u, bye 💖✨🌸