Skip to content
DiceDB

PTTL

The PTTL command in DiceDB is used to retrieve the remaining time to live (TTL) of a key in milliseconds. This command is particularly useful for understanding how much longer a key will exist before it expires. If the key does not have an associated expiration, the command will return a specific value indicating this state.

Syntax

Terminal window
PTTL key

Parameters

ParameterDescriptionTypeRequired
keyThe key for which the remaining TTL is to be retrievedStringYes

Return values

ConditionReturn Value
Command is successfulPositive integer representing the remaining time to live of the key in milliseconds
Key exists but has no associated expiration-1
Key does not exist-2

Behaviour

  • The command is non-destructive and does not modify the key or its expiration in any way.
  • If a key’s TTL is modified (e.g., by EXPIRE or PEXPIRE commands), subsequent PTTL calls will reflect the updated remaining time.

Errors

  1. Wrong number of arguments:

    • Error Message: (error) ERR wrong number of arguments for 'pttl' command
    • Occurs when attempting to use this command without any arguments or with more than one argument.

Example Usage

Key with Expiration

Terminal window
127.0.0.1:7379> SET mykey "Hello"
127.0.0.1:7379> EXPIRE mykey 10
127.0.0.1:7379> PTTL mykey
(integer) 10000

In this example, the key mykey is set with a value of “Hello” and an expiration of 10 seconds. The PTTL command returns 10000, indicating that the key will expire in 10000 milliseconds.

Key without Expiration

Terminal window
127.0.0.1:7379> SET mykey "Hello"
127.0.0.1:7379> PTTL mykey
(integer) -1

In this example, the key mykey is set with a value of “Hello” but no expiration is set. The PTTL command returns -1, indicating that the key exists but has no associated expiration.

Non-existent Key

Terminal window
127.0.0.1:7379> PTTL nonExistentKey
(integer) -2

In this example, the key nonExistentKey does not exist in the DiceDB database. The PTTL command returns -2, indicating that the key does not exist.

Invalid usage

Terminal window
127.0.0.1:7379> SET newkey "value"
127.0.0.1:7379> PTTL newkey value
(error) ERR wrong number of arguments for 'pttl' command

In this example, the PTTL command is used with an extra argument. This results in an error, as the PTTL command accepts only one argument.

Best Practices

  • Use PTTL in conjunction with EXPIRE or PEXPIRE commands to manage key expiration effectively

Alternatives

  • TTL: Similar to PTTL but returns the time-to-live in seconds instead of milliseconds