redis.clients.jedis.commands.KeyCommands Maven / Gradle / Ivy
Show all versions of jedis_preview Show documentation
package redis.clients.jedis.commands;
import java.util.List;
import java.util.Set;
import redis.clients.jedis.args.ExpiryOption;
import redis.clients.jedis.params.MigrateParams;
import redis.clients.jedis.params.RestoreParams;
import redis.clients.jedis.params.ScanParams;
import redis.clients.jedis.params.SortingParams;
import redis.clients.jedis.resps.ScanResult;
public interface KeyCommands {
/**
* Exists Command
* Test if the specified key exist.
*
* Time complexity: O(1)
* @param key
* @return {@code true} if the key exists, {@code false} otherwise
*/
boolean exists(String key);
/**
* Exists Command
* Test if the specified keys exist.
*
* Time complexity: O(N)
* @param keys
* @return The number of keys that exist from those specified as {@code keys}.
*/
long exists(String... keys);
/**
* Persist Command
* Undo a {@link KeyCommands#expire(String, long) expire} at turning the expire key into a normal key.
*
* Time complexity: O(1)
* @param key
* @return 1 if the key is now persist. 0 otherwise (only happens when key not set)
*/
long persist(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)
* @param key
* @return "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
*/
String type(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.
* @param key
* @return The serialized value
*/
byte[] dump(String key);
/**
* Restore Command
* Create a key associated with a value that is obtained by deserializing the provided serialized
* value (obtained via {@link KeyCommands#dump(String) 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.
* @param key
* @param ttl If ttl is 0 the key is created without any expire, otherwise the specified expire
* time (in milliseconds) is set.
* @param serializedValue
* @return OK
*/
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 {@link KeyCommands#dump(String) 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.
* @param key
* @param ttl If ttl is 0 the key is created without any expire, otherwise the specified expire
* time (in milliseconds) is set.
* @param serializedValue
* @param params {@link RestoreParams}
* @return OK
*/
String restore(String key, long ttl, byte[] serializedValue, RestoreParams params);
/**
* 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
* {@link KeyCommands#persist(String) PERSIST} command.
*
* Time complexity: O(1)
* @param key
* @param seconds time to expire
* @return 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.
*/
long expire(String key, long seconds);
/**
* Similar to {@link KeyCommands#expire(String, long) EXPIRE} but with optional expiry setting.
* @see KeyCommands#expire(String, long)
* @param key
* @param seconds time to expire
* @param expiryOption can be NX, XX, GT or LT
* @return 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.
*/
long expire(String key, long seconds, ExpiryOption expiryOption);
/**
* PExpire Command
* This command works exactly like {@link KeyCommands#expire(String, long) EXPIRE} but the time
* to live of the key is specified in milliseconds instead of seconds.
*
* Time complexity: O(1)
* @param key
* @param milliseconds time to expire
* @return 1 if the timeout was set, 0 otherwise.
* e.g. key doesn't exist, or operation skipped due to the provided arguments.
*/
long pexpire(String key, long milliseconds);
/**
* Similar to {@link KeyCommands#pexpire(String, long) EXPIRE} but with optional expiry setting.
* @see KeyCommands#pexpire(String, long)
* @param key
* @param milliseconds time to expire
* @param expiryOption can be NX, XX, GT or LT
* @return 1 if the timeout was set, 0 otherwise.
* e.g. key doesn't exist, or operation skipped due to the provided arguments.
*/
long pexpire(String key, long milliseconds, ExpiryOption expiryOption);
/**
* 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)
* @param key
* @return 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.
*/
long expireTime(String key);
/**
* PExpireTime Command
* Similar to {@link KeyCommands#expireTime(String) EXPIRETIME} but returns the absolute Unix expiration
* timestamp in milliseconds instead of seconds.
*
* Time complexity: O(1)
* @see KeyCommands#expireTime(String)
* @param key
* @return 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.
*/
long pexpireTime(String key);
/**
* ExpireAt Command
* EXPIREAT works exactly like {@link KeyCommands#expire(String, long) 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)
* @param key
* @param unixTime time to expire
* @return 1 if the timeout was set, 0 otherwise.
* e.g. key doesn't exist, or operation skipped due to the provided arguments.
*/
long expireAt(String key, long unixTime);
/**
* ExpireAt Command
* Similar to {@link KeyCommands#expireAt(String, long) EXPIREAT} but with {@code ExpiryOption}.
* @see KeyCommands#expireAt(String, long)
* @param key
* @param unixTime time to expire
* @param expiryOption can be NX, XX, GT or LT
* @return 1 if the timeout was set, 0 otherwise.
* e.g. key doesn't exist, or operation skipped due to the provided arguments.
*/
long expireAt(String key, long unixTime, ExpiryOption expiryOption);
/**
* PExpireAt Command
* This command works exactly like {@link KeyCommands#expireAt(String, long) EXPIREAT} but
* Unix time at which the key will expire is specified in milliseconds instead of seconds.
*
* Time complexity: O(1)
* @param key
* @param millisecondsTimestamp time to expire
* @return 1 if the timeout was set, 0 otherwise.
* e.g. key doesn't exist, or operation skipped due to the provided arguments.
*/
long pexpireAt(String key, long millisecondsTimestamp);
/**
* ExpireAt Command
* Similar to {@link KeyCommands#pexpireAt(String, long) PEXPIREAT} but with {@code ExpiryOption}.
* @see KeyCommands#pexpireAt(String, long)
* @param key
* @param millisecondsTimestamp time to expire
* @param expiryOption can be NX, XX, GT or LT
* @return 1 if the timeout was set, 0 otherwise.
* e.g. key doesn't exist, or operation skipped due to the provided arguments.
*/
long pexpireAt(String key, long millisecondsTimestamp, ExpiryOption expiryOption);
/**
* TTL Command
* The TTL command returns the remaining time to live in seconds of a key that has an
* {@link KeyCommands#expire(String, long) 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)
* @param key
* @return TTL in seconds, or a negative value in order to signal an error
*/
long ttl(String key);
/**
* PTTL Command
* The PTTL command returns the remaining time to live in milliseconds of a key that has an
* {@link KeyCommands#expire(String, long) EXPIRE} set.
*
* Time complexity: O(1)
* @param key
* @return TTL in milliseconds, or a negative value in order to signal an error
*/
long pttl(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.
* @param key
* @return The number of keys that were touched
*/
long touch(String key);
/**
* 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.
* @param keys
* @return The number of keys that were touched
*/
long touch(String... keys);
/**
* 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.
* @see KeyCommands#sort(String, SortingParams)
* @param key
* @return 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.
*/
List sort(String key);
/**
* Similar to {@link KeyCommands#sort(String) SORT} but store the result in {@code dstkey}.
* @see KeyCommands#sort(String)
* @param key
* @param dstkey
* @return The number of elements stored at dstkey.
*/
long sort(String key, String dstkey);
/**
* 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]
*
* @param key
* @param sortingParameters {@link SortingParams}
* @return A list of sorted elements
*/
List sort(String key, SortingParams sortingParameters);
/**
* Similar to {@link KeyCommands#sort(String, SortingParams) SORT} but store the result in {@code dstkey}.
* @see KeyCommands#sort(String, SortingParams)
* @param key
* @param sortingParameters {@link SortingParams}
* @param dstkey
* @return The number of elements stored at dstkey
*/
long sort(String key, SortingParams sortingParameters, String dstkey);
/**
* Read-only variant of the {@link KeyCommands#sort(String, SortingParams) SORT} command.
* It is exactly like the original SORT but refuses the STORE option and can safely be used in read-only replicas.
* @param key the key to sort
* @param sortingParams {@link SortingParams}
* @return list of sorted elements.
*/
List sortReadonly(String key, SortingParams sortingParams);
/**
* Del Command
* Remove the specified key. If a given key does not exist, no operation is performed.
*
* Time complexity: O(1)
* @param key
* @return 1 if the key was removed, 0 if the key does not exist
*/
long del(String key);
/**
* Remove the specified keys. If a given key does not exist, no operation is performed.
*
* Time complexity: O(N)
* @param keys
* @return An integer greater than 0 if one or more keys were removed, 0 if none of the specified keys existed
*/
long del(String... keys);
/**
* Unlink Command
* This command is very similar to {@link KeyCommands#del(String) 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.
* @param key
* @return The number of keys that were unlinked
*/
long unlink(String key);
/**
* Similar to {@link KeyCommands#unlink(String) SORT} but can be used with multiple keys.
* @see KeyCommands#unlink(String)
* @param keys
* @return The number of keys that were unlinked
*/
long unlink(String... keys);
/**
* Copy Command
* Copy the value stored at the source key to the destination key.
* @param srcKey the source key.
* @param dstKey the destination key.
* @param replace removes the destination key before copying the value to it, in order to avoid error.
* @return {@code true} if source was copied, {@code false} otherwise
*/
boolean copy(String srcKey, String dstKey, boolean replace);
/**
* Rename Command
* Atomically renames the key {@code oldkey} to {@code newkey}. If the source and destination name are the same an
* error is returned. If {@code newkey} already exists it is overwritten.
*
* Time complexity: O(1)
* @param oldkey
* @param newkey
* @return OK
*/
String rename(String oldkey, String newkey);
/**
* RenameNX Command
* Rename oldkey into newkey but fails if the destination key newkey already exists.
*
* Time complexity: O(1)
* @param oldkey
* @param newkey
* @return 1 if the key was renamed, 0 if the target key already exist
*/
long renamenx(String oldkey, String newkey);
/**
* Memory Usage Command
* Report the number of bytes that a key and its value require to be stored in RAM.
*
* Time complexity: O(1)
* @param key
* @return The memory usage in bytes
*/
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)
* @param key
* @param samples the number of sampled nested values. By default, this option is set to 5.
* To sample the all the nested values, use 0.
* @return The memory usage in bytes
*/
Long memoryUsage(String key, int samples);
/**
* Object Refcount Command
* Return the reference count of the stored at key.
*
* Time complexity: O(1)
* @param key
* @return The number of references
*/
Long objectRefcount(String key);
/**
* Object Encoding Command
* Return the internal encoding for the Redis object stored at key.
*
* Time complexity: O(1)
* @param key
* @return The encoding of the object
*/
String objectEncoding(String key);
/**
* Object IdleTime Command
* Return the time in seconds since the last access to the value stored at key.
*
* Time complexity: O(1)
* @param key
* @return The idle time in seconds
*/
Long objectIdletime(String key);
/**
* Object Freq Command
* Return the logarithmic access frequency counter of a Redis object stored at key.
*
* Time complexity: O(1)
* @param key
* @return The counter's value
*/
Long objectFreq(String key);
/**
* 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.
* @param host
* @param port
* @param key
* @param timeout the maximum idle time in any moment of the communication with the
* destination instance in milliseconds.
* @return OK on success, or NOKEY if no keys were found in the source instance.
*/
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.
* @param host
* @param port
* @param timeout the maximum idle time in any moment of the communication with the
* destination instance in milliseconds.
* @param params {@link MigrateParams}
* @param keys
* @return OK on success, or NOKEY if no keys were found in the source instance.
*/
String migrate(String host, int port, int timeout, MigrateParams params, String... keys);
/**
* 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)
* @param pattern
* @return List of keys matching the pattern.
*/
Set keys(String pattern);
ScanResult scan(String cursor);
ScanResult scan(String cursor, ScanParams params);
ScanResult scan(String cursor, ScanParams params, String type);
/**
* RandomKey Command
* Return a randomly selected key from the currently selected DB.
*
* Time complexity: O(1)
* @return The random key, or {@code nil} when the database is empty
*/
String randomKey();
}