In Redis, the LPOS command returns the index of matching elements inside a list.

Syntax

The syntax goes like this:

LPOS key element [RANK rank] [COUNT num-matches] [MAXLEN len]

The arguments in square brackets are optional. These are demonstrated in the following examples.

When we don’t specify any of the optional arguments, LPOS returns the first occurrence of the element.

Example

Suppose we create a list like this:

RPUSH animals Cat Dog Horse Cat Bird Cat Monkey Bird

Result:

(integer) 8

Let’s take a look at the list:

LRANGE animals 0 -1

Result:

1) "Cat"
2) "Dog"
3) "Horse"
4) "Cat"
5) "Bird"
6) "Cat"
7) "Monkey"
8) "Bird"

Let’s now use the LPOS command to find the first instance of Cat:

LPOS animals "Cat"

Result:

(integer) 0

As mentioned, when we don’t specify any of the optional arguments, LPOS returns the first occurrence of the element.

Lists are zero based, and so 0 is the first position in the list.

The RANK Option

We can use the RANK option to specify which instance of the value to return. This can be handy when the list contains multiple occurrences of the same value.

Our list contains multiple occurrences of Cat and multiple occurrences of Bird. Our previous example returns the first instance because we didn’t specify the RANK option.

Let’s use the RANK option to return the position of the second instance of Cat:

LPOS animals "Cat" RANK 2

Result:

(integer) 3

In this case we specified RANK 2, which means to return the position of the second instance of the value.

A rank of 1 returns the first instance, 2 returns the second, 3 returns the third, and so on.

Specifying a rank that’s higher than the number of occurrences returns nil:

LPOS animals "Cat" RANK 20

Result:

(nil)

Negative Rank

We can also use a negative rank. When doing this, it works back from the tail of the list:

LPOS animals "Cat" RANK -1

Result:

(integer) 5

Here, we used -1 which means that it returned the position of the last occurrence of the value. In this case it’s at position 5 in the list (remembering that lists are zero based).

The COUNT Option

We can use the COUNT option to return the position of multiple instances of the specified value:

LPOS animals "Cat" COUNT 2

Result:

1) (integer) 0
2) (integer) 3

We can also use this option to return the position of all instances. In this case we can use zero (0), which tells the command that we want all matches returned:

LPOS animals "Cat" COUNT 0

Result:

1) (integer) 0
2) (integer) 3
3) (integer) 5

We can combine this option with the RANK option to return all instances from a certain point.

Example:

LPOS animals "Cat" RANK 2 COUNT 0

Result:

1) (integer) 3
2) (integer) 5

The MAXLEN Option

The MAXLEN option can be used to limit the comparisons to a specified amount. This can be useful to limit the amount of time the command takes to run, especially if it’s a large list and we expect a match to be found early on.

Here’s an example:

LPOS animals "Cat" MAXLEN 2

Result:

(integer) 0

In this case there was a match, and the position was returned.

Let’s use a different value:

LPOS animals "Monkey" MAXLEN 2

Result:

(nil)

This time, the value wasn’t found within the value provided at the MAXLEN option.

We can use zero (0) to specify an unlimited number of comparisons:

LPOS animals "Monkey" MAXLEN 0

Result:

(integer) 6