LPOS(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💅 LPOS — the "where is my lil element at" command

okay bestie, so this is LPOS(3valkey), from the Valkey Command Manual ✨. It's the glow-up of list searching. Let's get into it 💖

✨ NAME ✨

lpos — Returns the index of matching elements in a list. 👑

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

So the way this works is: the command returns the index of matching elements inside a List. Default vibe — no options given — is that it scans the list from head to tail, looking for the first match of "element". If it finds the element, you get its index back (that's the zero-based position in the list, iykyk). If there's no match at all? You get nil. That's it, that's the whole thing 🙈

> RPUSH mylist a b c 1 2 3 c c
> LPOS mylist c
2

Now the optional arguments and options can switch up the behavior, no cap:

The RANK option specifies the "rank" of the first element to return, in case there are multiple matches. A rank of 1 means return the first match, 2 means return the second match, and so forth. So basically it's "which one of you do I want" energy 💅

For instance, in the example above the element "c" shows up multiple times. If I want the index of the second match, I'll write:

> LPOS mylist c RANK 2
6

That is, the second occurrence of "c" is at position 6. ✨

A negative "rank" as the RANK argument tells LPOS to invert the search direction, starting from the tail to the head. So we're like, give me the first element starting from the tail of the list:

> LPOS mylist c RANK -1
7

Note bestie: the indexes are still reported in the "natural" way, that is, considering the first element starting from the head of the list at index 0, the next element at index 1, and so forth. This basically means that the returned indexes are stable whatever the rank is positive or negative. The numbering doesn't flip, only the search does. 🫶

Sometimes we want to return not just the Nth matching element, but the position of all the first N matching elements. This can be achieved using the COUNT option. Obsessed with this one ngl:

> LPOS mylist c COUNT 2
[2,6]

We can combine COUNT and RANK, so that COUNT will try to return up to the specified number of matches, but starting from the Nth match, as specified by the RANK option. Teamwork fr fr 🌈

> LPOS mylist c RANK -1 COUNT 2
[7,6]

When COUNT is used, it is possible to specify 0 as the number of matches, as a way to tell the command we want all the matches found returned as an array of indexes. This is better than giving a very large COUNT option because it is more general. Iconic behavior honestly 👑

> LPOS mylist c COUNT 0
[2,6,7]

When COUNT is used and no match is found, an empty array is returned. However when COUNT is not used and there are no matches, the command returns nil. Different vibes depending on which mode you're in, keep track 💀

Finally, the MAXLEN option tells the command to compare the provided element only with a given maximum number of list items. So for instance specifying MAXLEN 1000 will make sure that the command performs only 1000 comparisons, effectively running the algorithm on a subset of the list (the first part or the last part depending on the fact we use a positive or negative rank). This is useful to limit the maximum complexity of the command. It is also useful when we expect the match to be found very early, but want to be sure that in case this is not true, the command does not take too much time to run. Basically it's a lil safety net 🧚

When MAXLEN is used, it is possible to specify 0 as the maximum number of comparisons, as a way to tell the command we want unlimited comparisons. This is better than giving a very large MAXLEN option because it is more general. Same energy as the COUNT 0 thing, just for the length instead 💜

💌 REPLY 💌

RESP2

Any of the following:

  • valkey-protocol(7) Nil reply: if there is no matching element.
  • valkey-protocol(7) Integer reply: an integer representing the matching element.
  • valkey-protocol(7) Array reply: If the COUNT option is given, an array of integers representing the matching elements (or an empty array if there are no matches).

RESP3

Any of the following:

  • valkey-protocol(7) Null reply: if there is no matching element.
  • valkey-protocol(7) Integer reply: an integer representing the matching element.
  • valkey-protocol(7) Array reply: If the COUNT option is given, an array of integers representing the matching elements (or an empty array if there are no matches).

🔥 COMPLEXITY 🔥

O(N) where N is the number of elements in the list, for the average case. When searching for elements near the head or the tail of the list, or when the MAXLEN option is provided, the command may run in constant time. Fast fast ✨

🎀 ACL CATEGORIES 🎀

@list @read @slow

⭐ HISTORY ⭐

  • Available since: 6.0.6

🌸 EXAMPLES 🌸

127.0.0.1:6379> RPUSH mylist a b c d 1 2 3 4 3 3 3
(integer) 11
127.0.0.1:6379> LPOS mylist 3
(integer) 6
127.0.0.1:6379> LPOS mylist 3 COUNT 0 RANK 2
1) (integer) 8
2) (integer) 9
3) (integer) 10

look at that output, chef's kiss 😭💖

👀 SEE ALSO 👀

and that's the whole page bestie, go index some lists 💅

this is Valkey 9.0.0, dated 2025-10-21 — bookmark it, screenshot it, put it on your moodboard, whatever, just remember the date 🎀✨
📦 where this page comes from