Lists

There are several useful commands for working with lists. Let's work with a list of fruits represented visually here:

[ , , ]

RPUSH

RPUSH key value [value ...]

Insert all the specified values at the tail of the list stored at key. If key does not exist, it is created as an empty list before performing the push operation. When key holds a value that is not a list, an error is returned.

RPUSH Example

Add a value to the tail of the fruits list:

redis> rpush fruits apple
(integer) 0

Add multiple values to the tail of the list in one operation:

redis> rpush fruits banana orange
(integer) 0

LPUSH works similarly, but values are inserted at the head of the list.

Read more about the RPUSH command in the Redis documentation.

RPOP

RPOP key

Removes and returns the last element of the list stored at key.

RPOP Example

Remove the last value from our fruits list:

redis> rpop fruits
(integer) 0

If our list originally contained "apple", "banana", and "orange", it will now only contain "apple" and "banana".

LPOP works similarly, but removes the first element of the list.

Read more about the RPOP command in the Redis documentation.

LRANGE

LRANGE key start stop

Returns the specified elements of the list stored at key. The offsets start and stop are zero-based indexes, with 0 being the first element of the list (the head of the list), 1 being the next element and so on.

LRANGE Example

Get the first two elements of the fruits list (element 0 and element 1):

redis> lrange fruits 0 1
1) "apple"
2) "banana"

To see all the elements in a list, use a stop value of -1.

redis> lrange fruits 0 -1
1) "apple"
2) "banana"
3) "orange"

Read more about the LRANGE command in the Redis documentation.

LTRIM

LTRIM key start stop

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

LTRIM Example

Assuming our fruits list contains "apple", "banana", and "orange", the following command will trim the list to only include the first two elements and remove "orange":

redis> ltrim fruits 0 1
OK

See the remaining elements of the list:

redis> lrange fruits 0 -1
1) "apple"
2) "banana"

Trim "apple" from a list called fruits containing "apple", "banana", and "orange":

redis> ltrim fruits 1 2
OK
redis> lrange fruits 0 -1
1) "banana"
2) "orange"

Read more about the LTRIM command in the Redis documentation.

LREM

LREM key count value

Removes the first count occurrences of elements equal to value from the list stored at key. The count argument influences the operation in the following ways:

• count > 0: Remove elements equal to value moving from head to tail.
• count < 0: Remove elements equal to value moving from tail to head.
• count = 0: Remove all elements equal to value.

LREM Example

Assuming our fruits list contains "apple", "banana", and "orange", the following command will remove "banana":

redis> lrem fruits 1 banana
(integer) 1
redis> lrange fruits 0 -1
1) "apple"
2) "orange"

If the fruits list contains "apple", "banana", "orange", "apple", "apple", and "banana", we can remove the last two "apple" elements:

redis> lrem fruits -2 apple
(integer) 2
redis> lrange fruits 0 -1
1) "apple"
2) "banana"
3) "orange"
4) "banana"

Read more about the LREM command in the Redis documentation.

Deleting All Elements from a List

How do we delete all elements from a list? Let's start with the assumption that our fruits list contains "apple", "banana", and "orange". We have three options that I am summarizing here based on some great answers in this Stack Overflow question.

1. LTRIM key -1 0

   Warning:: This only works if the list contains more than one value.

   Given our list of three fruits, we issue the command and view the resulting list:

    redis> ltrim fruits -1 0
    OK
    redis> lrange fruits 0 -1
    (empty list or set)
   

   If our list contains one value, let's see what happens:

   ```bash redis> ltrim fruits -1 0 OK redis> lrange fruits 0 -1 1) "apple"

   The "apple" item remains in the list which is not what we hoped for.

2. ltrim key 0 -(N+1)

   If our fruits list contains three (N) items, issue the following command:

    redis> ltrim fruits 0 -4
    OK
    redis> lrange fruits 0 -1
    (empty list or set)
   

   If you don't know how many items are in the list, and you still want to delete all numbers, pick a sufficiently large number for N:

    redis> ltrim fruits 0 -9999
    OK
    redis> lrange fruits 0 -1
    (empty list or set)
   

3. Delete the key

   This will clear all of the items from the list, and Redis will not throw errors if the non-existent list is accessed. This is the quickest solution, but might incur a slight performance hit in high traffic scenarios. This is the approach we will use in some of the upcoming examples.

    redis> del fruits
    (integer) 0
    redis> lrange fruits 0 -1
    (empty list or set)