Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

LPOS

Last updated 
LPOS key element [RANK rank] [COUNT num-matches] [MAXLEN len]
Group
List
Complexity
O(N) where N is the number of elements scanned
Arity
-3 (at least 3 words, counting the command name)
Flags
read-only
Keys
first 1, last 1, step 1
HotKV Cloud
All plans
On-Premise
no license needed

LPOS scans the list stored at key for elements equal to element and returns their indexes (counted from the head, starting at 0). By default it returns the index of the first match.

Options

Section titled “Options”
Option Effect
RANK rank Which match to start from. 1 (the default) is the first match, 2 the second, and so on. A negative rank scans from the tail: -1 is the last match. Cannot be 0.
COUNT num-matches Return up to this many matches as an array. 0 means all matches.
MAXLEN len Compare at most len elements, starting from the end the scan begins at. 0 (the default) means no limit.

Options can be given in any order, and are checked before the key is looked up.

Return value

Section titled “Return value”
Case RESP2 RESP3
No COUNT, a match found Integer: the index Same
No COUNT, no match or key does not exist Nil bulk string Null
With COUNT Array of integers (empty if there are no matches) Same

Errors:

  • ERR RANK can't be zero: use 1 to start from the first match, 2 from the second ... or use negative to start from the end of the list for RANK 0.
  • ERR value is not an integer or out of range if the RANK value is not an integer, and ERR value is out of range, value must between -9223372036854775807 and 9223372036854775807 for a rank of -9223372036854775808.
  • ERR COUNT can't be negative or ERR MAXLEN can't be negative if those values are negative or not integers.
  • ERR syntax error for an unknown option or a missing value.
  • WRONGTYPE if key holds a value that is not a list.

Examples

Section titled “Examples”
127.0.0.1:6379> RPUSH items a b c a b a
(integer) 6
127.0.0.1:6379> LPOS items a
(integer) 0
127.0.0.1:6379> LPOS items a RANK 2
(integer) 3
127.0.0.1:6379> LPOS items a RANK -1
(integer) 5
127.0.0.1:6379> LPOS items a COUNT 0
1) (integer) 0
2) (integer) 3
3) (integer) 5
127.0.0.1:6379> LPOS items a COUNT 0 MAXLEN 3
1) (integer) 0
127.0.0.1:6379> LPOS items z
(nil)

Compatibility

Section titled “Compatibility”

Same as Redis 7.4 and Valkey 8.

See also

Section titled “See also”

LINDEX, LRANGE, LREM