Redis LPOS

“Redis lists are linked lists of strings ordered in sequence. Redis list operations are extremely effective since they run at constant time complexity at the head or tail. Redis is unique among key-value stores in that it allows linked lists, which makes it a linked-list structure. The maximum length of a Redis list is 2^32 – 1 (4,294,967,295) elements, which holds more than 4 billion elements per list.”

The above diagram depicts the arrangement of a Redis list elements-wise and in the index format, which plays a vital role when using the LPOS Command.

Brief Overview of the LPOS Command

The LPOS command in Redis returns the matching index of the elements on a list. Furthermore, the LPOS command scans a list from the first index to the last index until a matching element is found for the specified element. When the specified list element is found, the element index is returned. The special NIL value will return when no match is found.

A Quick Review of the Syntax of the LPOS  Command

LPOS list_key list_element [RANK rank] [COUNT num-matches] [MAXLEN length]

The arguments within the square brackets are optional. The normal behavior of the LPOS command is to return the index of the first occurrence of the specified element when optional arguments are not given.

The RANK option is used to specify which instance of the value to return and can be handy when the list consists of numerous occurrences of the same value.

The COUNT option returns the position of multiple instances of the specified list element.

The MAXLEN option is used to limit the comparisons to a specified amount. Furthermore, it helps to limit the amount of time a command takes to execute, especially when it’s a large list and when expecting a match to be found early on.

The LPOS Command in Action

Creating a Redis list called “Names” with the aid of the RPUSH to demonstrate the LPOS command as follows:

RPUSH Names "Jenny" "Leon" "Nick" "Jenny" "Heron" "Jenny" "Elle" "Heron"


Inspecting the output of the list through the below command:

LRANGE Names 0 -1


Using the LPOS command to find the first instance of “Jenny” as follows:

LPOS Names "Jenny"


As mentioned, when no optional arguments are specified, the LPOS command returns the first occurrence of the element.

The RANK Option

This option specifies the instance of the value to be returned and is useful when the list contains multiple occurrences of the identical value.

The created list contains multiple occurrences of Jenny and Heron. In the earlier example, since the RANK option was not specified, the first element instance was returned as the output.

Using the RANk option to return the position of the second instance of Jenny using the below example:

LPOS Names "Jenny" RANK 2


Here the RANK option is specified as 2. So, the LPOS command returns the position of the second instance of the given list element, which is 3. If the RANK option is provided as 1, it should return the first instance of the element specified; if 2 is provided, it outputs the index of the second instance; 3 produces the index of the third instance, and so on.

If a rank is specified higher than the number of occurrences, it returns nil:

LPOS Names "Jenny" RANK 20


Also, the RANK option can be used as a negative rank where it works backward from the tail of the list:

LPOS Names "Jenny" RANK -1


Here, -1 is used to return the position of the last occurrence of the value. In this case, the position of “Jenny” is the fifth index.

The COUNT Option

This option is used to return the position of multiple instances of a specified value or element:

 LPOS Names "Jenny" COUNT 2


Also, this option can be used to return the position of all instances. Here a person can use zero(0) to tell the command to return all the matches as per the necessity:

LPOS Names "Jenny" COUNT 0


The COUNT option can be combined with the RANK option to return all instances from a certain point as follows:

LPOS Names "Jenny" RANK 2 COUNT 0


The MAXLEN Option

The MAXLEN is used to limit the comparisons to a specified amount and is useful to limit the amount of time the command takes to process in times when the list is large, and a person needs to find a match early.

For example,

LPOS Names "Jenny" MAXLEN 2


Here when the match is found, it returns the position or index of the given element.

When using a different value:

LPOS Names "Elle" MAXLEN 2


As expected, the element “Elle” is not found within the specified maximum limit of 2.

Also, a person can use zero(0) to specify an unlimited number of comparisons,

LPOS Names "Elle" MAXLEN 0



In summary, the LPOS command plays a major role in Redis list data structures when returning the index of the matching elements on a list. The LPOS command accepts various arguments which extend the command’s behavior. Overall, it operates constantly near the head and tail, or the MAXLEN option is specified, which is highly efficient.

About the author

Nimesha Jinarajadasa

Being a Full-stack Senior Software Engineer for more than five years, I love technology, as technology has the power to solve our many problems within just a minute. I try to learn more and create more opportunities for this new world.