SPILL.RESTORE - DiceDB Commands

Syntax

SPILL.RESTORE key

Parameters

Parameter	Description	Type	Required
`key`	The key to restore from disk storage	String	Yes

Return Value

Condition	Return Value
Key restored successfully	`OK`
Key not found in RocksDB	`(nil)`
Key has expired	`ERR Key has expired`
Data corruption detected	`ERR Corrupted data in RocksDB`
Module not initialized	`ERR RocksDB not initialized`

Behaviour

When SPILL.RESTORE is called, DiceDB attempts to restore the specified key from RocksDB storage back to memory. This command allows explicit restoration without triggering an access command.

After eviction, keys are automatically restored when accessed through commands like GET, EXISTS, TYPE, LRANGE, SMEMBERS, HGETALL, etc. However, this command allows manual restoration of keys without accessing their values.

Key behaviors:

Restored keys are removed from RocksDB after successful restoration
TTL is fully preserved during restoration
If a key with the same name already exists in memory, restoration is skipped and returns (nil)
Works with all Redis data types: strings, lists, sets, hashes, sorted sets, etc.
After eviction, keys logically still exist and accessing them automatically triggers restoration

Examples

Restore a previously evicted key:

127.0.0.1:7379> SET k1 v1
OK
127.0.0.1:7379> EVICT k1
OK
127.0.0.1:7379> KEYS *
(empty array)
127.0.0.1:7379> SPILL.RESTORE k1
OK
127.0.0.1:7379> GET k1
"v1"

Attempting to restore a non-existent key:

127.0.0.1:7379> SPILL.RESTORE nonexistent
(nil)

Restoring an expired key:

127.0.0.1:7379> SET temp "value" EX 1
OK
127.0.0.1:7379> EVICT temp
OK
(wait for key to expire...)
127.0.0.1:7379> SPILL.RESTORE temp
(error) ERR Key has expired

Notes

This command is specific to DiceDB and is not available in Valkey or Redis.
The SPILL.RESTORE command works in conjunction with the Spill module (dicedb-spill) for tiered storage support.
Automatic restoration happens transparently when you access evicted keys, so manual restoration is typically only needed for specific use cases.
See the Multi Tiering documentation for more details on the Spill module and tiered storage architecture.