redis.clients.jedis.commands

Interface ListCommands

All Known Subinterfaces:

JedisCommands

All Known Implementing Classes:

Jedis, JedisCluster, MultiDbClient, RedisClient, RedisClusterClient, RedisSentinelClient, UnifiedJedis

public interface ListCommands

Method Summary

Modifier and Type	Method and Description
java.lang.String	blmove(java.lang.String srcKey, java.lang.String dstKey, ListDirection from, ListDirection to, double timeout) Pop an element from a list, push it to another list and return it; or block until one is available
java.util.List<java.lang.String>	blmovem(java.lang.String srcKey, java.lang.String dstKey, ListDirection from, ListDirection to, double timeout) BLMOVEM Command The blocking variant of lmovem(String, String, ListDirection, ListDirection).
java.util.List<java.lang.String>	blmovem(java.lang.String srcKey, java.lang.String dstKey, ListDirection from, ListDirection to, double timeout, LMoveMParams params) BLMOVEM Command The blocking variant of lmovem(String, String, ListDirection, ListDirection, LMoveMParams).
KeyValue<java.lang.String,java.util.List<java.lang.String>>	blmpop(double timeout, ListDirection direction, int count, java.lang.String... keys)
KeyValue<java.lang.String,java.util.List<java.lang.String>>	blmpop(double timeout, ListDirection direction, java.lang.String... keys)
KeyValue<java.lang.String,java.lang.String>	blpop(double timeout, java.lang.String... keys) The blocking version of lpop(String) LPOP} because it blocks the connection when there are no elements to pop from any of the given lists.
KeyValue<java.lang.String,java.lang.String>	blpop(double timeout, java.lang.String key)
java.util.List<java.lang.String>	blpop(int timeout, java.lang.String... keys) The blocking version of lpop(String) LPOP} because it blocks the connection when there are no elements to pop from any of the given lists.
java.util.List<java.lang.String>	blpop(int timeout, java.lang.String key)
KeyValue<java.lang.String,java.lang.String>	brpop(double timeout, java.lang.String... keys) The blocking version of rpop(String) RPOP} because it blocks the connection when there are no elements to pop from any of the given lists.
KeyValue<java.lang.String,java.lang.String>	brpop(double timeout, java.lang.String key)
java.util.List<java.lang.String>	brpop(int timeout, java.lang.String... keys) The blocking version of rpop(String) RPOP} because it blocks the connection when there are no elements to pop from any of the given lists.
java.util.List<java.lang.String>	brpop(int timeout, java.lang.String key)
java.lang.String	brpoplpush(java.lang.String source, java.lang.String destination, int timeout) Deprecated. Use blmove(String, String, ListDirection, ListDirection, double) with ListDirection.RIGHT and ListDirection.LEFT. Deprecated in Jedis 7.3.0. Mirrors Redis deprecation since 6.2.0.
java.lang.String	lindex(java.lang.String key, long index) Returns the element at index in the list stored at key. 0 is the first element, 1 the second and so on.
long	linsert(java.lang.String key, ListPosition where, java.lang.String pivot, java.lang.String value) Inserts element in the list stored at key either before or after the reference value pivot.
long	llen(java.lang.String key) Return the length of the list stored at the specified key.
java.lang.String	lmove(java.lang.String srcKey, java.lang.String dstKey, ListDirection from, ListDirection to) Pop an element from a list, push it to another list and return it
java.util.List<java.lang.String>	lmovem(java.lang.String srcKey, java.lang.String dstKey, ListDirection from, ListDirection to) LMOVEM Command Atomically move one element from the head (LEFT) or tail (RIGHT) of the list at srcKey, push it onto the head (LEFT) or tail (RIGHT) of the list at dstKey, and return it wrapped in a list.
java.util.List<java.lang.String>	lmovem(java.lang.String srcKey, java.lang.String dstKey, ListDirection from, ListDirection to, LMoveMParams params) LMOVEM Command Atomically move multiple elements from the head (LEFT) or tail (RIGHT) of the list at srcKey onto the head (LEFT) or tail (RIGHT) of the list at dstKey, and return them in destination order.
KeyValue<java.lang.String,java.util.List<java.lang.String>>	lmpop(ListDirection direction, int count, java.lang.String... keys)
KeyValue<java.lang.String,java.util.List<java.lang.String>>	lmpop(ListDirection direction, java.lang.String... keys)
java.lang.String	lpop(java.lang.String key) Atomically return and remove the first (LPOP) or last (RPOP) element of the list.
java.util.List<java.lang.String>	lpop(java.lang.String key, int count) Atomically return and remove the first (LPOP) or last (RPOP) element of the list.
java.lang.Long	lpos(java.lang.String key, java.lang.String element) Returns the index of the first matching element inside a redis list.
java.lang.Long	lpos(java.lang.String key, java.lang.String element, LPosParams params) In case there are multiple matches Rank option specifies the "rank" of the element to return.
java.util.List<java.lang.Long>	lpos(java.lang.String key, java.lang.String element, LPosParams params, long count) Returns the index of matching elements inside a Redis list.
long	lpush(java.lang.String key, java.lang.String... strings) Add the string value to the head (LPUSH) or tail (RPUSH) of the list stored at key.
long	lpushx(java.lang.String key, java.lang.String... strings) Inserts specified values at the head of the list stored at key.
java.util.List<java.lang.String>	lrange(java.lang.String key, long start, long stop) Return the specified elements of the list stored at the specified key.
long	lrem(java.lang.String key, long count, java.lang.String value) Remove the first count occurrences of the value element from the list.
java.lang.String	lset(java.lang.String key, long index, java.lang.String value) Set a new value as the element at index position of the List at key.
java.lang.String	ltrim(java.lang.String key, long start, long stop) Trim an existing list so that it will contain only the specified range of elements specified.
java.lang.String	rpop(java.lang.String key) Atomically return and remove the first (LPOP) or last (RPOP) element of the list.
java.util.List<java.lang.String>	rpop(java.lang.String key, int count) Atomically return and remove the first (LPOP) or last (RPOP) element of the list.
java.lang.String	rpoplpush(java.lang.String srckey, java.lang.String dstkey) Deprecated. Use lmove(String, String, ListDirection, ListDirection) with ListDirection.RIGHT and ListDirection.LEFT. Deprecated in Jedis 7.3.0. Mirrors Redis deprecation since 6.2.0.
long	rpush(java.lang.String key, java.lang.String... strings) Add the string value to the head (LPUSH) or tail (RPUSH) of the list stored at key.
long	rpushx(java.lang.String key, java.lang.String... strings) Inserts specified values at the tail of the list stored at key.

Method Detail

rpush

long rpush(java.lang.String key,
           java.lang.String... strings)

Add the string value to the head (LPUSH) or tail (RPUSH) of the list stored at key. If the key does not exist an empty list is created just before the append operation. If the key exists but is not a List an error is returned.

Time complexity: O(1)

Parameters:

key -

strings - data to push

Returns:

The number of elements inside the list after the push operation

lpush

long lpush(java.lang.String key,
           java.lang.String... strings)

Add the string value to the head (LPUSH) or tail (RPUSH) of the list stored at key. If the key does not exist an empty list is created just before the append operation. If the key exists but is not a List an error is returned.

Time complexity: O(1)

Parameters:

key -

strings - data to push

Returns:

The number of elements inside the list after the push operation

llen

long llen(java.lang.String key)

Return the length of the list stored at the specified key. If the key does not exist zero is returned (the same behaviour as for empty lists). If the value stored at key is not a list an error is returned.

Time complexity: O(1)

Parameters:

key -

Returns:

The length of the list

lrange

java.util.List<java.lang.String> lrange(java.lang.String key,
                                        long start,
                                        long stop)

Return the specified elements of the list stored at the specified key. Start and end are zero-based indexes. 0 is the first element of the list (the list head), 1 the next element and so on.

For example LRANGE foobar 0 2 will return the first three elements of the list.

start and end can also be negative numbers indicating offsets from the end of the list. For example -1 is the last element of the list, -2 the penultimate element and so on.

Consistency with range functions in various programming languages

Note that if you have a list of numbers from 0 to 100, LRANGE 0 10 will return 11 elements, that is, rightmost item is included. This may or may not be consistent with behavior of range-related functions in your programming language of choice (think Ruby's Range.new, Array#slice or Python's range() function).

LRANGE behavior is consistent with one of Tcl.

Out-of-range indexes

Indexes out of range will not produce an error: if start is over the end of the list, or start > end, an empty list is returned. If end is over the end of the list Redis will threat it just like the last element of the list.

Time complexity: O(start+n) (with n being the length of the range and start being the start offset)

Parameters:

key -

start -

stop -

Returns:

A list of elements in the specified range

ltrim

java.lang.String ltrim(java.lang.String key,
                       long start,
                       long stop)

Trim an existing list so that it will contain only the specified range of elements specified. Start and end are zero-based indexes. 0 is the first element of the list (the list head), 1 the next element and so on.

For example LTRIM foobar 0 2 will modify the list stored at foobar key so that only the first three elements of the list will remain.

start and end can also be negative numbers indicating offsets from the end of the list. For example -1 is the last element of the list, -2 the penultimate element and so on.

Indexes out of range will not produce an error: if start is over the end of the list, or start > end, an empty list is left as value. If end over the end of the list Redis will threat it just like the last element of the list.

Hint: the obvious use of LTRIM is together with LPUSH/RPUSH. For example:

lpush("mylist", "someelement"); ltrim("mylist", 0, 99); *

The above two commands will push elements in the list taking care that the list will not grow without limits. This is very useful when using Redis to store logs for example. It is important to note that when used in this way LTRIM is an O(1) operation because in the average case just one element is removed from the tail of the list.

Time complexity: O(n) (with n being len of list - len of range)

Parameters:

key -

start -

stop -

Returns:

OK

lindex

java.lang.String lindex(java.lang.String key,
                        long index)

Returns the element at index in the list stored at key. 0 is the first element, 1 the second and so on. Negative indexes are supported, for example -1 is the last element, -2 the penultimate and so on.

If the value stored at key is not of list type an error is returned. If the index is out of range a 'nil' reply is returned.

Note that even if the average time complexity is O(n) asking for the first or the last element of the list is O(1).

Time complexity: O(n) (with n being the length of the list)

Parameters:

key -

index -

Returns:

The requested element

lset

java.lang.String lset(java.lang.String key,
                      long index,
                      java.lang.String value)

Set a new value as the element at index position of the List at key.

Out of range indexes will generate an error.

Similarly to other list commands accepting indexes, the index can be negative to access elements starting from the end of the list. So -1 is the last element, -2 is the penultimate, and so forth.

Time Complexity O(N) when N being the length of the list. For the first or last elements of the list is O(1)

Parameters:

key -

index -

value -

Returns:

OK

lrem

long lrem(java.lang.String key,
          long count,
          java.lang.String value)

Remove the first count occurrences of the value element from the list. If count is zero all the elements are removed. If count is negative elements are removed from tail to head, instead to go from head to tail that is the normal behaviour. So for example LREM with count -2 and hello as value to remove against the list (a,b,c,hello,x,hello,hello) will leave the list (a,b,c,hello,x). The number of removed elements is returned as an integer, see below for more information about the returned value. Note that non existing keys are considered like empty lists by LREM, so LREM against non existing keys will always return 0.

Time complexity: O(N) (with N being the length of the list)

Parameters:

key -

count -

value -

Returns:

The number of removed elements if the operation succeeded

lpop

java.lang.String lpop(java.lang.String key)

Atomically return and remove the first (LPOP) or last (RPOP) element of the list. For example if the list contains the elements "a","b","c" LPOP will return "a" and the list will become "b","c".

If the key does not exist or the list is already empty the special value 'nil' is returned.

Parameters:

key -

Returns:

The popped element

lpop

java.util.List<java.lang.String> lpop(java.lang.String key,
                                      int count)

Atomically return and remove the first (LPOP) or last (RPOP) element of the list. For example if the list contains the elements "a","b","c" LPOP will return "a" and the list will become "b","c".

Parameters:

key -

count -

Returns:

A list of popped elements, or 'nil' when key does not exist

lpos

java.lang.Long lpos(java.lang.String key,
                    java.lang.String element)

Returns the index of the first matching element inside a redis list. If the element is found, its index (the zero-based position in the list) is returned. Otherwise, if no match is found, 'nil' is returned.

Time complexity: O(N) where N is the number of elements in the list

Parameters:

key -

element -

Returns:

The index of first matching element in the list. Value will be 'nil' when the element is not present in the list

lpos

java.lang.Long lpos(java.lang.String key,
                    java.lang.String element,
                    LPosParams params)

In case there are multiple matches Rank option specifies the "rank" of the element to return. A rank of 1 returns the first match, 2 to return the second match, and so forth. If list `foo` has elements ("a","b","c","1","2","3","c","c"), The function call to get the index of second occurrence of "c" will be as follows lpos("foo","c", LPosParams.lPosParams().rank(2)).

Maxlen option compares the element provided only with a given maximum number of list items. A value of 1000 will make sure that the command performs only 1000 comparisons. The comparison is made for the first part or the last part depending on the fact we use a positive or negative rank. Following is how we could use the Maxlen option lpos("foo", "b", LPosParams.lPosParams().rank(1).maxlen(2)).

Parameters:

key -

element -

params - LPosParams

Returns:

The integer representing the matching element, or 'nil' if there is no match

lpos

java.util.List<java.lang.Long> lpos(java.lang.String key,
                                    java.lang.String element,
                                    LPosParams params,
                                    long count)

Returns the index of matching elements inside a Redis list. If the element is found, its index (the zero-based position in the list) is returned. Otherwise, if no match is found, nil is returned.

Time complexity: O(N) where N is the number of elements in the list

Parameters:

key -

element -

params - LPosParams

count -

Returns:

A list containing position of the matching elements inside the list

rpop

java.lang.String rpop(java.lang.String key)

Atomically return and remove the first (LPOP) or last (RPOP) element of the list. For example if the list contains the elements "a","b","c" LPOP will return "a" and the list will become "b","c".

Parameters:

key -

Returns:

The popped element

rpop

java.util.List<java.lang.String> rpop(java.lang.String key,
                                      int count)

Atomically return and remove the first (LPOP) or last (RPOP) element of the list. For example if the list contains the elements "a","b","c" LPOP will return "a" and the list will become "b","c".

Parameters:

key -

count - return up to count elements

Returns:

A list of count popped elements, or 'nil' when key does not exist.

linsert

long linsert(java.lang.String key,
             ListPosition where,
             java.lang.String pivot,
             java.lang.String value)

Inserts element in the list stored at key either before or after the reference value pivot.

When key does not exist, it is considered an empty list and no operation is performed.

Parameters:

key -

where - can be BEFORE or AFTER

pivot - reference value

value - the value

Returns:

The length of the list after the insert operation, or -1 when the value pivot was not found

lpushx

long lpushx(java.lang.String key,
            java.lang.String... strings)

Inserts specified values at the head of the list stored at key. In contrary to LPUSH, no operation will be performed when key does not yet exist.

Parameters:

key -

strings - the strings to push

Returns:

The length of the list after the push operation

rpushx

long rpushx(java.lang.String key,
            java.lang.String... strings)

Inserts specified values at the tail of the list stored at key. In contrary to RPUSH, no operation will be performed when key does not yet exist.

Parameters:

key -

strings - the strings to push

Returns:

The length of the list after the push operation

blpop

java.util.List<java.lang.String> blpop(int timeout,
                                       java.lang.String... keys)

The blocking version of lpop(String) LPOP} because it blocks the connection when there are no elements to pop from any of the given lists. An element is popped from the head of the first list that is non-empty, with the given keys being checked in the order that they are given.

Parameters:

timeout - the timeout argument is interpreted as a double value specifying the maximum number of seconds to block. A timeout of zero can be used to block indefinitely.

keys -

blpop

java.util.List<java.lang.String> blpop(int timeout,
                                       java.lang.String key)

See Also:

blpop(int, String...)

blpop

KeyValue<java.lang.String,java.lang.String> blpop(double timeout,
                                                  java.lang.String... keys)

The blocking version of lpop(String) LPOP} because it blocks the connection when there are no elements to pop from any of the given lists. An element is popped from the head of the first list that is non-empty, with the given keys being checked in the order that they are given.

Parameters:

timeout - the timeout argument is interpreted as a double value specifying the maximum number of seconds to block. A timeout of zero can be used to block indefinitely.

keys -

blpop

KeyValue<java.lang.String,java.lang.String> blpop(double timeout,
                                                  java.lang.String key)

See Also:

blpop(double, String...)

brpop

java.util.List<java.lang.String> brpop(int timeout,
                                       java.lang.String... keys)

The blocking version of rpop(String) RPOP} because it blocks the connection when there are no elements to pop from any of the given lists. An element is popped from the tail of the first list that is non-empty, with the given keys being checked in the order that they are given.

Parameters:

timeout - the timeout argument is interpreted as a double value specifying the maximum number of seconds to block. A timeout of zero can be used to block indefinitely.

keys -

brpop

java.util.List<java.lang.String> brpop(int timeout,
                                       java.lang.String key)

See Also:

brpop(int, String...)

brpop

KeyValue<java.lang.String,java.lang.String> brpop(double timeout,
                                                  java.lang.String... keys)

The blocking version of rpop(String) RPOP} because it blocks the connection when there are no elements to pop from any of the given lists. An element is popped from the tail of the first list that is non-empty, with the given keys being checked in the order that they are given.

Parameters:

timeout - the timeout argument is interpreted as a double value specifying the maximum number of seconds to block. A timeout of zero can be used to block indefinitely.

keys -

brpop

KeyValue<java.lang.String,java.lang.String> brpop(double timeout,
                                                  java.lang.String key)

See Also:

brpop(double, String...)

rpoplpush

@Deprecated
java.lang.String rpoplpush(java.lang.String srckey,
                                       java.lang.String dstkey)

Deprecated. Use lmove(String, String, ListDirection, ListDirection) with ListDirection.RIGHT and ListDirection.LEFT. Deprecated in Jedis 7.3.0. Mirrors Redis deprecation since 6.2.0.

Atomically return and remove the last (tail) element of the srckey list, and push the element as the first (head) element of the dstkey list. For example if the source list contains the elements "a","b","c" and the destination list contains the elements "foo","bar" after an RPOPLPUSH command the content of the two lists will be "a","b" and "c","foo","bar".

If the key does not exist or the list is already empty the special value 'nil' is returned. If the srckey and dstkey are the same the operation is equivalent to removing the last element from the list and pushing it as first element of the list, so it's a "list rotation" command.

Time complexity: O(1)

Parameters:

srckey -

dstkey -

Returns:

Bulk reply

brpoplpush

@Deprecated
java.lang.String brpoplpush(java.lang.String source,
                                        java.lang.String destination,
                                        int timeout)

Deprecated. Use blmove(String, String, ListDirection, ListDirection, double) with ListDirection.RIGHT and ListDirection.LEFT. Deprecated in Jedis 7.3.0. Mirrors Redis deprecation since 6.2.0.

The blocking variant of rpoplpush(String, String). When source is empty, Redis will block the connection until another client pushes to it or until timeout is reached. A timeout of zero can be used to block indefinitely.

Time complexity: O(1)

Parameters:

source -

destination -

timeout - the timeout argument is interpreted as a double value specifying the maximum number of seconds to block. A timeout of zero can be used to block indefinitely.

Returns:

The element being popped from source and pushed to destination

lmove

java.lang.String lmove(java.lang.String srcKey,
                       java.lang.String dstKey,
                       ListDirection from,
                       ListDirection to)

Pop an element from a list, push it to another list and return it

Parameters:

srcKey -

dstKey -

from - can be LEFT or RIGHT

to - can be LEFT or RIGHT

Returns:

The element being popped and pushed

blmove

java.lang.String blmove(java.lang.String srcKey,
                        java.lang.String dstKey,
                        ListDirection from,
                        ListDirection to,
                        double timeout)

Pop an element from a list, push it to another list and return it; or block until one is available

Parameters:

srcKey -

dstKey -

from - can be LEFT or RIGHT

to - can be LEFT or RIGHT

timeout - the timeout argument is interpreted as a double value specifying the maximum number of seconds to block. A timeout of zero can be used to block indefinitely.

Returns:

The element being popped and pushed

lmovem

java.util.List<java.lang.String> lmovem(java.lang.String srcKey,
                                        java.lang.String dstKey,
                                        ListDirection from,
                                        ListDirection to)

LMOVEM Command Atomically move one element from the head (LEFT) or tail (RIGHT) of the list at srcKey, push it onto the head (LEFT) or tail (RIGHT) of the list at dstKey, and return it wrapped in a list. Without a count block this is equivalent to lmove(String, String, ListDirection, ListDirection).

Time complexity: O(1)

Parameters:

srcKey - the source list

dstKey - the destination list

from - where to pop from the source, LEFT or RIGHT

to - where to push to the destination, LEFT or RIGHT

Returns:

The moved element in a list, or null if the source list does not exist

Since:

8.0

lmovem

java.util.List<java.lang.String> lmovem(java.lang.String srcKey,
                                        java.lang.String dstKey,
                                        ListDirection from,
                                        ListDirection to,
                                        LMoveMParams params)

LMOVEM Command Atomically move multiple elements from the head (LEFT) or tail (RIGHT) of the list at srcKey onto the head (LEFT) or tail (RIGHT) of the list at dstKey, and return them in destination order. The params select how many elements to move (COUNT: up to; EXACTLY: exactly or nothing) and their ordering (OBO: one by one; BULK: in bulk).

Time complexity: O(N) where N is the number of elements moved.

Parameters:

srcKey - the source list

dstKey - the destination list

from - where to pop from the source, LEFT or RIGHT

to - where to push to the destination, LEFT or RIGHT

params - the count and ordering of the move

Returns:

The moved elements in destination order, or null if the source list does not exist or, with EXACTLY, holds fewer than the requested number of elements

Since:

8.0

blmovem

java.util.List<java.lang.String> blmovem(java.lang.String srcKey,
                                         java.lang.String dstKey,
                                         ListDirection from,
                                         ListDirection to,
                                         double timeout)

BLMOVEM Command The blocking variant of lmovem(String, String, ListDirection, ListDirection). When the source list is empty, Redis blocks the connection until another client pushes to it or until timeout is reached.

Time complexity: O(1)

Parameters:

srcKey - the source list

dstKey - the destination list

from - where to pop from the source, LEFT or RIGHT

to - where to push to the destination, LEFT or RIGHT

timeout - the maximum number of seconds to block, interpreted as a double. A timeout of zero blocks indefinitely.

Returns:

The moved element in a list, or null on timeout

Since:

8.0

blmovem

java.util.List<java.lang.String> blmovem(java.lang.String srcKey,
                                         java.lang.String dstKey,
                                         ListDirection from,
                                         ListDirection to,
                                         double timeout,
                                         LMoveMParams params)

BLMOVEM Command The blocking variant of lmovem(String, String, ListDirection, ListDirection, LMoveMParams). With a COUNT selector it blocks only while the source list is empty; with an EXACTLY selector it blocks until the source list holds enough elements, or until timeout is reached.

Time complexity: O(N) where N is the number of elements moved.

Parameters:

srcKey - the source list

dstKey - the destination list

from - where to pop from the source, LEFT or RIGHT

to - where to push to the destination, LEFT or RIGHT

timeout - the maximum number of seconds to block, interpreted as a double. A timeout of zero blocks indefinitely.

params - the count and ordering of the move

Returns:

The moved elements in destination order, or null on timeout

Since:

8.0

lmpop

KeyValue<java.lang.String,java.util.List<java.lang.String>> lmpop(ListDirection direction,
                                                                  java.lang.String... keys)

lmpop

KeyValue<java.lang.String,java.util.List<java.lang.String>> lmpop(ListDirection direction,
                                                                  int count,
                                                                  java.lang.String... keys)

blmpop

KeyValue<java.lang.String,java.util.List<java.lang.String>> blmpop(double timeout,
                                                                   ListDirection direction,
                                                                   java.lang.String... keys)

blmpop

KeyValue<java.lang.String,java.util.List<java.lang.String>> blmpop(double timeout,
                                                                   ListDirection direction,
                                                                   int count,
                                                                   java.lang.String... keys)