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:
key | The key to create and store the deserialised data. |
ttl | The time to live. If ttl is 0 the key is created without any expire, otherwise the specified expire time (in milliseconds) is set. |
serialized-value | The 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.