Valkey keys are binary safe; this means that you can use any binary sequence as a key, from a string like “foo” to the content of a JPEG file. The empty string is also a valid key.
A few other rules about keys:
There are commands that are not defined on particular types, but are useful in order to interact with the space of keys, and thus, can be used with keys of any type.
For example the EXISTS
command returns 1 or 0 to signal
if a given key exists or not in the database, while the DEL
command deletes a key and associated value, whatever the 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).
There are many key space 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
Before moving on, we should 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.
A few important notes about key expiration:
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. 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.
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.
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.
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.
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.