Package redis.clients.jedis.commands

Interface KeyCommands

All Known Subinterfaces:
JedisCommands
All Known Implementing Classes:
Jedis, JedisCluster, JedisPooled, JedisSentineled, JedisSharding, UnifiedJedis
public interface KeyCommands

  • Method Details

    • exists

      boolean exists(String key)
      Exists Command Test if the specified key exist.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      true if the key exists, false otherwise

    • exists

      long exists(String... keys)
      Exists Command Test if the specified keys exist.

      Time complexity: O(N)

      Parameters:
      keys -
      Returns:
      The number of keys that exist from those specified as keys.

    • persist

      long persist(String key)
      Persist Command Undo a expire at turning the expire key into a normal key.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      1 if the key is now persist. 0 otherwise (only happens when key not set)

    • type

      String type(String key)
      Type Command Return the type of the value stored at key in form of a string. The type can be one of "none", "string", "list", "set". "none" is returned if the key does not exist.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      "none" if the key does not exist, "string" if the key contains a String value, "list" if the key contains a List value, "set" if the key contains a Set value, "zset" if the key contains a Sorted Set value, "hash" if the key contains a Hash value

    • dump

      byte[] dump(String key)
      Dump Command Serialize the value stored at key in a Redis-specific format and return it to the user.

      Time complexity: O(1) to access the key and additional O(N*M) to serialize it where N is the number of Redis objects composing the value and M their average size.

      Parameters:
      key -
      Returns:
      The serialized value

    • restore

      String restore(String key, long ttl, byte[] serializedValue)
      Restore Command Create a key associated with a value that is obtained by deserializing the provided serialized value (obtained via DUMP).

      Time complexity: O(1) to access the key and additional O(N*M) to serialize it where N is the number of Redis objects composing the value and M their average size.

      Parameters:
      key -
      ttl - If ttl is 0 the key is created without any expire, otherwise the specified expire time (in milliseconds) is set.
      serializedValue -
      Returns:
      OK

    • restore

      String restore(String key, long ttl, byte[] serializedValue, RestoreParams params)
      Restore Command Create a key associated with a value that is obtained by deserializing the provided serialized value (obtained via DUMP).

      Time complexity: O(1) to access the key and additional O(N*M) to serialize it where N is the number of Redis objects composing the value and M their average size.

      Parameters:
      key -
      ttl - If ttl is 0 the key is created without any expire, otherwise the specified expire time (in milliseconds) is set.
      serializedValue -
      params - RestoreParams
      Returns:
      OK

    • expire

      long expire(String key, long seconds)
      Expire Command Set a timeout on the specified key. After the timeout the key will be automatically deleted by the server. A key with an associated timeout is said to be volatile in Redis terminology.

      Volatile keys are stored on disk like the other keys, the timeout is persistent too like all the other aspects of the dataset. Saving a dataset containing expires and stopping the server does not stop the flow of time as Redis stores on disk the time when the key will no longer be available as Unix time, and not the remaining seconds.

      Since Redis 2.1.3 you can update the value of the timeout of a key already having an expire set. It is also possible to undo the expire at all turning the key into a normal key using the PERSIST command.

      Time complexity: O(1)

      Parameters:
      key -
      seconds - time to expire
      Returns:
      1 if the timeout was set, 0 otherwise. Since the key already has an associated timeout (this may happen only in Redis versions < 2.1.3, Redis >= 2.1.3 will happily update the timeout), or the key does not exist.

    • expire

      long expire(String key, long seconds, ExpiryOption expiryOption)
      Similar to EXPIRE but with optional expiry setting.
      Parameters:
      key -
      seconds - time to expire
      expiryOption - can be NX, XX, GT or LT
      Returns:
      1 if the timeout was set, 0 otherwise. Since the key already has an associated timeout (this may happen only in Redis versions < 2.1.3, Redis >= 2.1.3 will happily update the timeout), or the key does not exist.
      See Also:

    • pexpire

      long pexpire(String key, long milliseconds)
      PExpire Command This command works exactly like EXPIRE but the time to live of the key is specified in milliseconds instead of seconds.

      Time complexity: O(1)

      Parameters:
      key -
      milliseconds - time to expire
      Returns:
      1 if the timeout was set, 0 otherwise. e.g. key doesn't exist, or operation skipped due to the provided arguments.

    • pexpire

      long pexpire(String key, long milliseconds, ExpiryOption expiryOption)
      Similar to EXPIRE but with optional expiry setting.
      Parameters:
      key -
      milliseconds - time to expire
      expiryOption - can be NX, XX, GT or LT
      Returns:
      1 if the timeout was set, 0 otherwise. e.g. key doesn't exist, or operation skipped due to the provided arguments.
      See Also:

    • expireTime

      long expireTime(String key)
      ExpireTime Command Returns the absolute Unix timestamp (since January 1, 1970) in seconds at which the given key will expire.

      The command returns -1 if the key exists but has no associated expiration time, and -2 if the key does not exist.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      Expiration Unix timestamp in seconds, or a negative value in order to signal an error: -1 if the key exists but has no associated expiration time, and -2 if the key does not exist.

    • pexpireTime

      long pexpireTime(String key)
      PExpireTime Command Similar to EXPIRETIME but returns the absolute Unix expiration timestamp in milliseconds instead of seconds.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      Expiration Unix timestamp in milliseconds, or a negative value in order to signal an error: -1 if the key exists but has no associated expiration time, and -2 if the key does not exist.
      See Also:

    • expireAt

      long expireAt(String key, long unixTime)
      ExpireAt Command EXPIREAT works exactly like EXPIRE but instead to get the number of seconds representing the Time To Live of the key as a second argument (that is a relative way of specifying the TTL), it takes an absolute one in the form of a UNIX timestamp (Number of seconds elapsed since 1 Gen 1970).

      EXPIREAT was introduced in order to implement the Append Only File persistence mode so that EXPIRE commands are automatically translated into EXPIREAT commands for the append only file. Of course EXPIREAT can also used by programmers that need a way to simply specify that a given key should expire at a given time in the future.

      Time complexity: O(1)

      Parameters:
      key -
      unixTime - time to expire
      Returns:
      1 if the timeout was set, 0 otherwise. e.g. key doesn't exist, or operation skipped due to the provided arguments.

    • expireAt

      long expireAt(String key, long unixTime, ExpiryOption expiryOption)
      ExpireAt Command Similar to EXPIREAT but with ExpiryOption.
      Parameters:
      key -
      unixTime - time to expire
      expiryOption - can be NX, XX, GT or LT
      Returns:
      1 if the timeout was set, 0 otherwise. e.g. key doesn't exist, or operation skipped due to the provided arguments.
      See Also:

    • pexpireAt

      long pexpireAt(String key, long millisecondsTimestamp)
      PExpireAt Command This command works exactly like EXPIREAT but Unix time at which the key will expire is specified in milliseconds instead of seconds.

      Time complexity: O(1)

      Parameters:
      key -
      millisecondsTimestamp - time to expire
      Returns:
      1 if the timeout was set, 0 otherwise. e.g. key doesn't exist, or operation skipped due to the provided arguments.

    • pexpireAt

      long pexpireAt(String key, long millisecondsTimestamp, ExpiryOption expiryOption)
      ExpireAt Command Similar to PEXPIREAT but with ExpiryOption.
      Parameters:
      key -
      millisecondsTimestamp - time to expire
      expiryOption - can be NX, XX, GT or LT
      Returns:
      1 if the timeout was set, 0 otherwise. e.g. key doesn't exist, or operation skipped due to the provided arguments.
      See Also:

    • ttl

      long ttl(String key)
      TTL Command The TTL command returns the remaining time to live in seconds of a key that has an EXPIRE set. This introspection capability allows a Redis connection to check how many seconds a given key will continue to be part of the dataset.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      TTL in seconds, or a negative value in order to signal an error

    • pttl

      long pttl(String key)
      PTTL Command The PTTL command returns the remaining time to live in milliseconds of a key that has an EXPIRE set.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      TTL in milliseconds, or a negative value in order to signal an error

    • touch

      long touch(String key)
      Touch Command Alters the last access time of a key. A key is ignored if it does not exist.

      Time complexity: O(N) where N is the number of keys that will be touched.

      Parameters:
      key -
      Returns:
      The number of keys that were touched

    • touch

      long touch(String... keys)
      Touch Command Alters the last access time of a key(s). A key is ignored if it does not exist.

      Time complexity: O(N) where N is the number of keys that will be touched.

      Parameters:
      keys -
      Returns:
      The number of keys that were touched

    • sort

      List<String> sort(String key)
      Sort Command Sort a Set or a List.

      Sort the elements contained in the List, Set, or Sorted Set values at key. By default, sorting is numeric with elements being compared as double precision floating point numbers. This is the simplest form of SORT.

      Parameters:
      key -
      Returns:
      Assuming the Set/List at key contains a list of numbers, the return value will be the list of numbers ordered from the smallest to the biggest number.
      See Also:

    • sort

      long sort(String key, String dstkey)
      Similar to SORT but store the result in dstkey.
      Parameters:
      key -
      dstkey -
      Returns:
      The number of elements stored at dstkey.
      See Also:

    • sort

      List<String> sort(String key, SortingParams sortingParameters)
      Sort a Set or a List accordingly to the specified parameters.

      examples:

      Given are the following sets and key/values: 

       x = [1, 2, 3]
 y = [a, b, c]

 k1 = z
 k2 = y
 k3 = x

 w1 = 9
 w2 = 8
 w3 = 7
      Sort Order: 
       sort(x) or sort(x, sp.asc())
 -> [1, 2, 3]

 sort(x, sp.desc())
 -> [3, 2, 1]

 sort(y)
 -> [c, a, b]

 sort(y, sp.alpha())
 -> [a, b, c]

 sort(y, sp.alpha().desc())
 -> [c, a, b]
      Limit (e.g. for Pagination): 
       sort(x, sp.limit(0, 2))
 -> [1, 2]

 sort(y, sp.alpha().desc().limit(1, 2))
 -> [b, a]
      Sorting by external keys: 
       sort(x, sb.by(w*))
 -> [3, 2, 1]

 sort(x, sb.by(w*).desc())
 -> [1, 2, 3]
      Getting external keys: 
       sort(x, sp.by(w*).get(k*))
 -> [x, y, z]

 sort(x, sp.by(w*).get(#).get(k*))
 -> [3, x, 2, y, 1, z]
      Parameters:
      key -
      sortingParameters - SortingParams
      Returns:
      A list of sorted elements

    • sort

      long sort(String key, SortingParams sortingParameters, String dstkey)
      Similar to SORT but store the result in dstkey.
      Parameters:
      key -
      sortingParameters - SortingParams
      dstkey -
      Returns:
      The number of elements stored at dstkey
      See Also:

    • sortReadonly

      List<String> sortReadonly(String key, SortingParams sortingParams)
      Read-only variant of the SORT command. It is exactly like the original SORT but refuses the STORE option and can safely be used in read-only replicas.
      Parameters:
      key - the key to sort
      sortingParams - SortingParams
      Returns:
      list of sorted elements.

    • del

      long del(String key)
      Del Command Remove the specified key. If a given key does not exist, no operation is performed.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      1 if the key was removed, 0 if the key does not exist

    • del

      long del(String... keys)
      Remove the specified keys. If a given key does not exist, no operation is performed.

      Time complexity: O(N)

      Parameters:
      keys -
      Returns:
      An integer greater than 0 if one or more keys were removed, 0 if none of the specified keys existed

    • unlink

      long unlink(String key)
      Unlink Command This command is very similar to DEL: it removes the specified key. Just like DEL a key is ignored if it does not exist. However, the command performs the actual memory reclaiming in a different thread, so it is not blocking, while DEL is. This is where the command name comes from: the command just unlinks the keys from the keyspace. The actual removal will happen later asynchronously.

      Time complexity: O(1) for each key removed regardless of its size. Then the command does O(N) work in a different thread in order to reclaim memory, where N is the number of allocations the deleted objects where composed of.

      Parameters:
      key -
      Returns:
      The number of keys that were unlinked

    • unlink

      long unlink(String... keys)
      Similar to SORT but can be used with multiple keys.
      Parameters:
      keys -
      Returns:
      The number of keys that were unlinked
      See Also:

    • copy

      boolean copy(String srcKey, String dstKey, boolean replace)
      Copy Command Copy the value stored at the source key to the destination key.
      Parameters:
      srcKey - the source key.
      dstKey - the destination key.
      replace - removes the destination key before copying the value to it, in order to avoid error.
      Returns:
      true if source was copied, false otherwise

    • rename

      String rename(String oldkey, String newkey)
      Rename Command Atomically renames the key oldkey to newkey. If the source and destination name are the same an error is returned. If newkey already exists it is overwritten.

      Time complexity: O(1)

      Parameters:
      oldkey -
      newkey -
      Returns:
      OK

    • renamenx

      long renamenx(String oldkey, String newkey)
      RenameNX Command Rename oldkey into newkey but fails if the destination key newkey already exists.

      Time complexity: O(1)

      Parameters:
      oldkey -
      newkey -
      Returns:
      1 if the key was renamed, 0 if the target key already exist

    • memoryUsage

      Long memoryUsage(String key)
      Memory Usage Command Report the number of bytes that a key and its value require to be stored in RAM.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      The memory usage in bytes

    • memoryUsage

      Long memoryUsage(String key, int samples)
      Memory Usage Command Report the number of bytes that a key and its value require to be stored in RAM.

      Time complexity: O(1)

      Parameters:
      key -
      samples - the number of sampled nested values. By default, this option is set to 5. To sample the all the nested values, use 0.
      Returns:
      The memory usage in bytes

    • objectRefcount

      Long objectRefcount(String key)
      Object Refcount Command Return the reference count of the stored at key.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      The number of references

    • objectEncoding

      String objectEncoding(String key)
      Object Encoding Command Return the internal encoding for the Redis object stored at key.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      The encoding of the object

    • objectIdletime

      Long objectIdletime(String key)
      Object IdleTime Command Return the time in seconds since the last access to the value stored at key.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      The idle time in seconds

    • objectFreq

      Long objectFreq(String key)
      Object Freq Command Return the logarithmic access frequency counter of a Redis object stored at key.

      Time complexity: O(1)

      Parameters:
      key -
      Returns:
      The counter's value

    • migrate

      String migrate(String host, int port, String key, int timeout)
      Migrate Command Atomically transfer a key from a source Redis instance to a destination Redis instance. On success the key is deleted from the original instance and is guaranteed to exist in the target instance.
      Parameters:
      host -
      port -
      key -
      timeout - the maximum idle time in any moment of the communication with the destination instance in milliseconds.
      Returns:
      OK on success, or NOKEY if no keys were found in the source instance.

    • migrate

      String migrate(String host, int port, int timeout, MigrateParams params, String... keys)
      Migrate Command Atomically transfer a key from a source Redis instance to a destination Redis instance. On success the key is deleted from the original instance and is guaranteed to exist in the target instance.
      Parameters:
      host -
      port -
      timeout - the maximum idle time in any moment of the communication with the destination instance in milliseconds.
      params - MigrateParams
      keys -
      Returns:
      OK on success, or NOKEY if no keys were found in the source instance.

    • keys

      Set<String> keys(String pattern)
      Keys Command Returns all the keys matching the glob-style pattern as space separated strings. For example if you have in the database the keys "foo" and "foobar" the command "KEYS foo*" will return "foo foobar".

      Note that while the time complexity for this operation is O(n) the constant times are pretty low. For example Redis running on an entry level laptop can scan a 1 million keys database in 40 milliseconds. Still it's better to consider this one of the slow commands that may ruin the DB performance if not used with care.

      In other words this command is intended only for debugging and special operations like creating a script to change the DB schema. Don't use it in your normal code. Use Redis Sets in order to group together a subset of objects.

      Glob style patterns examples:

      • h?llo will match hello hallo hhllo
      • h*llo will match hllo heeeello
      • h[ae]llo will match hello and hallo, but not hillo

      Use \ to escape special chars if you want to match them verbatim.

      Time complexity: O(n) (with n being the number of keys in the DB, and assuming keys and pattern of limited length)

      Parameters:
      pattern -
      Returns:
      List of keys matching the pattern.

    • scan

      ScanResult<String> scan(String cursor)

    • scan

      ScanResult<String> scan(String cursor, ScanParams params)

    • scan

      ScanResult<String> scan(String cursor, ScanParams params, String type)

    • randomKey

      String randomKey()
      RandomKey Command Return a randomly selected key from the currently selected DB.

      Time complexity: O(1)

      Returns:
      The random key, or nil when the database is empty