# LPOS

> Find the index of matching elements in a list.

URL: https://docs.hotkv.com/commands/lpos/

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

- Group: List
- Complexity: O(N) where N is the number of elements scanned
- 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

| 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

| 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

```
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

Same as Redis 7.4 and Valkey 8.

## See also

[LINDEX](https://docs.hotkv.com/commands/lindex/index.md), [LRANGE](https://docs.hotkv.com/commands/lrange/index.md), [LREM](https://docs.hotkv.com/commands/lrem/index.md)