Read cache freshness
A cache client needs to expose or calculate how long a cached entry remains valid with millisecond precision.
Redis · Module
PTTL
Returns the remaining expiration time of a key in milliseconds. It distinguishes an existing key without expiration (-1) from a missing key (-2).
- Since
- Redis Open Source 2.6.0
How it works
PTTL takes one key and reports how long that key will remain before expiration, measured in milliseconds. A nonnegative result is the remaining lifetime; -1 distinguishes an existing key without expiration from -2, which means the key does not exist.
Syntax
PTTL keyParameters
| Name | Type | Description |
|---|---|---|
key | key | The name of the key whose remaining expiration should be returned. |
Returns
An integer: the remaining TTL in milliseconds; -1 if the key exists without an associated expiration; or -2 if the key does not exist.
Key points
- PTTL reports a key's remaining expiration interval using milliseconds.
- The required key argument identifies which Redis key to inspect.
- Use PTTL when millisecond units are needed; TTL provides the corresponding value in seconds.
- The command has been available since Redis Open Source 2.6.0.
- PTTL performs a constant-time expiration lookup.
Common mistakes
- Do not interpret every negative result as the same condition: -2 means the key is absent.
- An existing persistent key returns -1, so callers should handle it separately from a missing key.
Example: Inspect a millisecond expiration
SET session:42 "user-123" PX 30000
PTTL session:42Stores a session with a 30-second millisecond expiration, then reads its remaining lifetime.
When to use it
Calculate retry timing
A rate limiter needs the remaining lockout interval to tell a client when retrying may be reasonable.
Inspect key lifecycle
An operations check verifies whether a key has an expiration and observes its remaining duration.
Interview questions
QWhat does PTTL measure, and how does it differ from TTL?
PTTL returns the remaining time to live for a key in milliseconds. Unlike TTL, which reports seconds, PTTL uses millisecond units.
Follow-up: How would you distinguish a missing key from a persistent key? Check for -2 for a missing key and -1 for an existing key without an expiration.
QWhat are PTTL's argument and time complexity?
The command accepts one required argument: the key whose expiration is being inspected. Its time complexity is O(1), making the lookup constant time.
Follow-up: What should a caller do when the result is nonnegative? Treat it as the remaining lifetime in milliseconds, while remembering that it can decrease immediately after the read.
QWhat values can PTTL return?
PTTL returns an integer reply: a nonnegative TTL in milliseconds, -1 when the key exists without an expiration, or -2 when the key does not exist. These meanings apply to both RESP2 and RESP3.
Follow-up: Which command can establish a millisecond expiration before checking it? PEXPIRE sets a relative timeout with millisecond precision.
Related
TTLEXPIREPEXPIREPEXPIREATPERSIST