Redis RESTORE Command Explained

In Redis, the RESTORE command creates a key associated with a value that is obtained by deserialising the provided serialised value (obtained via the DUMP command).

The serialisation format contains a 64-bit checksum, as well as the RDB version. The RESTORE command checks the RDB version and data checksum. If they don’t match an error is returned.

Syntax

RESTORE key ttl serialized-value [REPLACE] [ABSTTL] [IDLETIME seconds] [FREQ frequency]

Explanation of the arguments:

keyThe key to create and store the deserialised data.
ttlThe time to live. If ttl is 0 the key is created without any expire, otherwise the specified expire time (in milliseconds) is set.
serialized-valueThe serialised value to restore.
[REPLACE]Replaces the key if it already exists. Without this, an error will occur if the key already exists.
[ABSTTL]When this modifier is used, ttl represents an absolute Unix timestamp (in milliseconds) in which the key will expire.
[IDLETIME seconds]This is the idle time of the key, that is the approximated number of seconds elapsed since the last access to the key.
[FREQ freqency]The access frequency index of the key. The returned integer is proportional to the logarithm of the recent access frequency of the key. Can be used for eviction purposes.

Example

Here’s an example to demonstrate:

RESTORE type 0 "\x00\x03Dog\n\x00\x14\x069\xb24\x14\xe4\xd6"

Result:

OK

In this case, I created a key called type and restored the serialised value to it. I also set a ttl of 0, which means that it has no expiry.

Let’s check the value of our new type key:

GET type

Result:

"Dog"

When the Key Already Exists

By default, if the key already exists, an error is returned.

To demonstrate this let’s run the previous code again (but with a slightly different serialised value):

RESTORE type 0 "\x00\x03Cat\n\x00\x10\x1e\xeaH\xafMl\x17"

Result:

(error) BUSYKEY Target key name already exists.

As expected, we got an error.

The REPLACE Argument

We can use the REPLACE argument to replace the key if it already exists.

Let’s try running the previous code again, but this time we’ll add the REPLACE argument:

RESTORE type 0 "\x00\x03Cat\n\x00\x10\x1e\xeaH\xafMl\x17" REPLACE

Result:

OK

This time the operation succeeded without error.

Let’s check the key’s value:

GET type

Result:

"Cat"

So we can see that the new deserialised value has been assigned to the key.

Set an Expiry Time

The previous examples set a ttl of 0, which means that the key has no expiry. We can use a value other than 0 to set an expire time, in milliseconds, for the key:

RESTORE type 60000 "\x00\x03Cat\n\x00\x10\x1e\xeaH\xafMl\x17" REPLACE

Result:

OK

Now let’s check the time to live of the key before it expires:

PTTL type

Result:

(integer) 55940

Running PTTL returns the current time to live, in milliseconds. We can alternatively use the TTL command to return the time to live in seconds. Anyway, if we run PTTL again, we can see that it has decremented:

PTTL type

Result:

(integer) 15263

We can alternatively specify the time to live as an absolute Unix timestamp (in milliseconds). When doing this, we need to add the ABSTTL argument.

The DUMP Command

We can get serialised data by using the DUMP command. The DUMP command serialises the value stored at a specified key in a Redis-specific format and returns it to the user.

Example:

DUMP type

That returns the value of the key as a serialised value.