Cache lifetime monitoring
Inspect how long a cached value can remain before Redis removes it.
Redis · Command
TTL
Returns a key's remaining expiration time in seconds. It distinguishes missing keys from existing keys that have no expiration.
- Since
- 2.8
How it works
TTL inspects a key's expiration and returns the number of seconds until Redis removes it. It returns special negative values when the key is missing or exists without an expiration, allowing clients to distinguish those states.
Syntax
TTL keyParameters
| Name | Type | Description |
|---|---|---|
key | key | The key whose remaining expiration time should be inspected. |
Returns
An integer number of seconds remaining; -1 if the key exists without an expiration; -2 if the key does not exist.
Key points
- TTL reports the remaining lifetime only for a key with a configured timeout.
- The command lets clients inspect the lifetime in seconds without retrieving the stored value.
- The result estimates how long the key remains part of Redis's dataset.
- Use PTTL when the application needs the same check at millisecond resolution.
Common mistakes
- A missing key produces -2, not a normal zero-second lifetime.
- A persistent key produces -1, so do not interpret it as imminent expiration.
Example: Check a key's remaining lifetime
SET session:123 active EX 60
TTL session:123
Stores a key with a 60-second expiration, then reports its remaining lifetime in seconds.
When to use it
Session and token expiry checks
Check whether a session or token key is nearing expiration.
Key-state diagnostics
Identify whether a key is absent, persistent, or configured to expire.
Interview questions
QWhat does TTL do?
TTL returns the remaining time to live for a key in seconds. It is an introspection command, so it checks expiration without changing the key.
Follow-up: How would you obtain finer resolution? Use PTTL, which reports the corresponding expiration information in milliseconds.
QWhat do TTL's negative return values mean?
TTL returns -2 when the key does not exist and -1 when the key exists but has no expiration. A nonnegative result is the remaining lifetime in seconds.
Follow-up: How can a key acquire an expiration? Set one with EXPIRE, or write it using an expiration option such as SET with EX.
QWhen should TTL be preferred over PTTL?
Use TTL when second-level precision is sufficient for checking cache or session lifetime. For millisecond resolution, use PTTL instead.
Follow-up: What should a client do when TTL returns -2? Treat the value as absent and avoid assuming that an expiration is merely near.
Related
EXPIREPTTLSET