Redis List Data Structure Tutorial

Redis List Data Structure

A list is similar to an Array in most programming languages. Each value we add to a list is automatically assigned an index number starting at 0.

For example, if we added the individual letters of the word ‘Hello’, it would look like the following.

A list is an ordered collection, which means the values are added one after another in sequence from either the left or the right.

How to insert (push) values into a List

To insert values into a list we use the RPUSH command. The first argument is the key name, followed by the values we want to add to our list.

RPUSH key_name value-1 value-2 value-3

RPUSH greeting H e l l o

If the list was created successfully, the number of elements in the list will be returned.

(integer) 5

The RPUSH command pushes the values to the right of the list, which means that the values we enter will be pushed in the same sequence to the list.

How to return values from a List

To see the values in a list we use the LRANGE command. The first argument is the key name, followed by the index number where we want to start returning and then the index number where we want to stop returning.

LRANGE key_name start_index stop_index

Remember that lists are zero-indexed. To access a value in the first position, we would refer to index 0.

LRANGE greeting 0 4

In the example above, we access all 5 of the values in the ‘greeting’ list, starting at 0.

1) "H"
2) "e"
3) "l"
4) "l"
5) "o"

We can start and stop anywhere we want to.

LRANGE greeting 1 3

This time we start at index 1 (the second value) and end at index 3.

1) "e"
2) "l"
3) "l"

How to push values to the left of a List

If we want to push values to the left of the list, we can use the LPUSH command.

FLUSHALL

LPUSH greeting H e l l o

With the LPUSH command the last value that was entered will be at the 0 index.

LRANGE greeting 0 4

Instead of showing ‘Hello’, it will show ‘olleH’.

1) "o"
2) "l"
3) "l"
4) "e"
5) "H"

How to return values from a List with negative indexing

We can return the elements in a list with negative indexing, which means that we start at end of the list and move to the start of the list.

LRANGE greeting 0 -1

The example above will return all the values present in the list.

1) "o"
2) "l"
3) "l"
4) "e"
5) "H"

If we use 0 to -2, it will return all the values except the last element in the list, and so on.

LRANGE greeting 0 -2

1) "o"
2) "l"
3) "l"
4) "e"

This is usefull when you want to return either the whole list or certain parts of it, but don’t want it to be a two step process where you first need to get the length of the list, and then get the elements.

How to return the amount of elements in (length of) a List

To get the amount of elements in a list, we use the LLEN command with the key as the only argument.

LLEN key_name

LLEN greeting

(integer) 4

As mentioned previously, we can use this in a two step process to first get the amount of elements in a list, then access them with the LRANGE command.

How to return a List element at a specific index

To get the item at a specific index, we use the LINDEX command. The first argument is the key, and the second argument is the index number.

Remember that lists are zero-indexed, which means the index starts at 0.

LINDEX key_name index

LINDEX greeting 2

In the example above we return the value in the third element at index 2.

"l"

If we pass in an index that doesn’t exist, Redis will return nil.

LINDEX greeting 99

(nil)

How to remove an element from a List

To remove an item from a list, we can use the LPOP or RPOP commands.

The LPOP command will remove an item from the left of the list, in other words the start. The only argument is the key name.

LPOP key_name

LPOP greeting

If the pop was successfull, Redis will return the value that was removed from the list.

"e"

The RPOP command will remove an item from the right of the list, in other words the end.

RPOP key_name

RPOP greeting

If the pop was successfull, Redis will return the value that was removed from the list.

"o"

How to update a value in a List

If we want to update a value in the list, we use the LSET command. The first argument is the key name, followed by the index number and then the new value.

LSET key_name index new_value

LSET greeting 0 Hello

If we run the LRANGE command now, we’ll see that the value at index 0 has been updated.

LRANGE greeting 0 -1

1) "Hello"
2) "l"

If we try to update an element that doesn’t exist, Redis will throw an “index out of range” error.

LSET greeting 99 Hello

(error) ERR index out of range

How to delete a whole List

To delete a list, we use the DEL command with the key name as the only argument.

DEL key_name

DEL greeting

If the list was successfully deleted, Redis will return true.

(integer) 1

How to insert a value only if the List exists

It may happen that we accidentally misspell the key name when pushing a new value to list. In that case Redis will create a new list with that value instead of adding it to the list we want.

To get around these types of accidents, we can use the LPUSHX and RPUSHX commands. These commands will only add the value to the list if the key name exists.

RPUSH greeting H e l l o

The key name in the example above is ‘greeting’. Now let’s try to push some values to a key that doesn’t exist with the RPUSHX command.

RPUSHX greetings T h e r e

In the example above we misspelled the key name as ‘greetings’ so the values aren’t added.

(integer) 0

Because we used the RPUSHX command however, Redis won’t create a new separate list with the name ‘greetings’.

If we add the values with the correct spelling for the key, Redis will add them to the list.

RPUSHX greeting T h e r e

If the values were added successfully, it will return the total amount of values in the list.

(integer) 10

How to insert a value at a specific place in a List

If we want to add a value at a specific location in the list we use the LINSERT command.

With the LINSERT command, we choose a pivot value and then specify if we want to insert the new value before or after it.

LINSERT key_name BEFORE|AFTER pivot_value new_value

LINSERT greeting BEFORE H Well

In the example above, we use the ‘H’ as our pivot value and then specify we want to add the value before it. Then we add the string ‘Well’.

If we use the LRANGE command with 0 and -1 to return the full list, we can see that the new value was added before the H.

1) "Well"
2) "H"
3) "e"
4) "l"
5) "l"
6) "o"
7) "T"
8) "h"
9) "e"
10) "r"
11) "e"