Delete large cache entries
Removing large cached values without synchronously blocking Redis's main thread.
Redis · Module
UNLINK
UNLINK asynchronously deletes one or more Redis keys. It removes keys from the keyspace promptly while reclaiming their memory in a background thread.
- Since
- 4.0.0
How it works
UNLINK removes the specified keys from Redis's keyspace immediately, while memory reclamation runs asynchronously in another thread. It accepts one or more keys, ignores keys that do not exist, and returns how many keys were unlinked.
Syntax
UNLINK key [key ...]Parameters
| Name | Type | Description |
|---|---|---|
key [key ...] | key | One or more keys to delete asynchronously. |
Returns
Integer reply: the number of keys that were unlinked.
Key points
- The unlinking operation is O(1) per key, independent of the size of the value stored there.
- Memory reclamation is proportional to the deleted object's allocations and is handled by another thread.
- Supplying a nonexistent key does not produce an error or increase the returned count.
- The keyspace no longer exposes the unlinked keys after the command processes them.
- The required argument is a variadic list containing at least one key.
Common mistakes
- In clustered Redis, multi-key behavior has cluster-specific constraints; consult the multi-key operations rules when the keys may be distributed across shards.
- A successful reply means the keys were unlinked from the keyspace, not that all associated memory has already been reclaimed.
Example: Asynchronously remove keys
SET key1 "Hello"
SET key2 "World"
UNLINK key1 key2 key3Creates two keys, then asynchronously unlinks them; the missing third key is ignored.
When to use it
Best-effort multi-key cleanup
Deleting several known keys while tolerating keys that may already be absent.
Cluster-aware cleanup
Performing non-blocking key removal in a clustered deployment after checking multi-key constraints.
Interview questions
QWhy use UNLINK instead of DEL for large values?
UNLINK removes one or more keys without making memory reclamation block the main Redis thread. It unlinks each key from the keyspace and performs the heavier reclamation work asynchronously.
Follow-up: How does its complexity compare with DEL? UNLINK is O(1) per removed key regardless of value size in the command path, followed by O(N) reclamation work in another thread.
QWhat does UNLINK return?
The command accepts one or more keys using the form UNLINK key [key ...]. Missing keys are ignored, and the integer reply reports how many keys were actually unlinked.
Follow-up: What does a reply of 2 mean for three supplied keys? Exactly two supplied keys existed and were unlinked; the third was absent or otherwise not counted.
QWhat cluster consideration applies to multi-key UNLINK?
UNLINK can remove multiple keys in one command, but clustered Redis environments impose multi-key behavior constraints. Keys may need to satisfy the cluster's requirements for multi-key operations.
Follow-up: What should be checked before issuing a multi-key UNLINK in a cluster? Review Redis's multi-key operation rules and ensure the selected keys are valid for the target cluster topology.
Related
DELmulti-key operations