LPOS

Syntax text Syntax diagram API methods

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

Client:

lpos(
    name: KeyT,
    value: str,
    rank: Optional[int] = None,
    count: Optional[int] = None,
    maxlen: Optional[int] = None
) → Union[str, List, None]

lpos(
    key: byte[],
    element: byte[]
) → Long  // A list containing position of the matching elements inside the list

lpos(
    key: byte[],
    element: byte[],
    params: LPosParams  // LPosParams
) → Long  // A list containing position of the matching elements inside the list

lpos(
    key: byte[],
    element: byte[],
    count: LPosParams params final long
) → List<Long>  // A list containing position of the matching elements inside the list

lpos(
    key: String,
    element: String
) → Long  // A list containing position of the matching elements inside the list

lpos(
    key: String,
    element: String,
    params: LPosParams  // LPosParams
) → Long  // A list containing position of the matching elements inside the list

lpos(
    key: K,  // the key.
    value: V  // the element to search for.
) → Long  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    args: LPosArgs  // command arguments to configureFIRST and MAXLEN options.
) → Long  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    count: int  // limit the number of matches.
) → List<Long>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    count: int,  // limit the number of matches.
    args: LPosArgs  // command arguments to configureFIRST and MAXLEN options.
) → List<Long>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V  // the element to search for.
) → RedisFuture<Long>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    args: LPosArgs  // command arguments to configureFIRST and MAXLEN options.
) → RedisFuture<Long>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    count: int  // limit the number of matches.
) → RedisFuture<List<Long>>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    count: int,  // limit the number of matches.
    args: LPosArgs  // command arguments to configureFIRST and MAXLEN options.
) → RedisFuture<List<Long>>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V  // the element to search for.
) → Mono<Long>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    args: LPosArgs  // command arguments to configureFIRST and MAXLEN options.
) → Mono<Long>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    count: int  // limit the number of matches.
) → Flux<Long>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

lpos(
    key: K,  // the key.
    value: V,  // the element to search for.
    count: int,  // limit the number of matches.
    args: LPosArgs  // command arguments to configureFIRST and MAXLEN options.
) → Flux<Long>  // V integer-reply representing the matching elements, or empty if there is no match. @since 5.3.2

LPos(
    ctx: context.Context,
    key: string,
    value: string,
    a: LPosArgs
) → *IntCmd

ListPosition(
    key: RedisKey,  // The key of the list.
    element: RedisValue,  // The element to search for.
    rank: long,  // The rank of the first element to return, within the sub-list of matching indexes in the case of multiple matches.
    maxLength: long,  // The maximum number of elements to scan through before stopping, defaults to 0 (a full scan of the list.)
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The 0-based index of the first matching element, or -1 if not found.

ListPositions(
    key: RedisKey,  // The key of the list.
    element: RedisValue,  // The element to search for.
    count: long,  // of indexes of matching elements. If none are found, and empty array is returned.</returns> <remarks></remarks>
    rank: long,  // The rank of the first element to return, within the sub-list of matching indexes in the case of multiple matches.
    maxLength: long,  // The maximum number of elements to scan through before stopping, defaults to 0 (a full scan of the list.)
    flags: CommandFlags  // The flags to use for this operation.
) → long[]

ListPosition(
    key: RedisKey,  // The key of the list.
    element: RedisValue,  // The element to search for.
    rank: long,  // The rank of the first element to return, within the sub-list of matching indexes in the case of multiple matches.
    maxLength: long,  // The maximum number of elements to scan through before stopping, defaults to 0 (a full scan of the list.)
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The 0-based index of the first matching element, or -1 if not found.

ListPositions(
    key: RedisKey,  // The key of the list.
    element: RedisValue,  // The element to search for.
    count: long,  // of indexes of matching elements. If none are found, and empty array is returned.</returns> <remarks></remarks>
    rank: long,  // The rank of the first element to return, within the sub-list of matching indexes in the case of multiple matches.
    maxLength: long,  // The maximum number of elements to scan through before stopping, defaults to 0 (a full scan of the list.)
    flags: CommandFlags  // The flags to use for this operation.
) → long[]

ListPosition(
    key: RedisKey,  // The key of the list.
    element: RedisValue,  // The element to search for.
    rank: long,  // The rank of the first element to return, within the sub-list of matching indexes in the case of multiple matches.
    maxLength: long,  // The maximum number of elements to scan through before stopping, defaults to 0 (a full scan of the list.)
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The 0-based index of the first matching element, or -1 if not found.

ListPositions(
    key: RedisKey,  // The key of the list.
    element: RedisValue,  // The element to search for.
    count: long,  // of indexes of matching elements. If none are found, and empty array is returned.</returns> <remarks></remarks>
    rank: long,  // The rank of the first element to return, within the sub-list of matching indexes in the case of multiple matches.
    maxLength: long,  // The maximum number of elements to scan through before stopping, defaults to 0 (a full scan of the list.)
    flags: CommandFlags  // The flags to use for this operation.
) → long[]

ListPosition(
    key: RedisKey,  // The key of the list.
    element: RedisValue,  // The element to search for.
    rank: long,  // The rank of the first element to return, within the sub-list of matching indexes in the case of multiple matches.
    maxLength: long,  // The maximum number of elements to scan through before stopping, defaults to 0 (a full scan of the list.)
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The 0-based index of the first matching element, or -1 if not found.

ListPositions(
    key: RedisKey,  // The key of the list.
    element: RedisValue,  // The element to search for.
    count: long,  // of indexes of matching elements. If none are found, and empty array is returned.</returns> <remarks></remarks>
    rank: long,  // The rank of the first element to return, within the sub-list of matching indexes in the case of multiple matches.
    maxLength: long,  // The maximum number of elements to scan through before stopping, defaults to 0 (a full scan of the list.)
    flags: CommandFlags  // The flags to use for this operation.
) → long[]

lpos(
    key: K,
    value: V,
    options: LposOptions
) → Generic

lpos(
    key: K,
    value: V,
    options: LposOptions
) → Generic

Available since:: Redis Open Source 6.0.6
Time 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.
ACL categories:: @read, @list, @slow,
Compatibility:: Redis Software and Redis Cloud compatibility

The command returns the index of matching elements inside a Redis list. By default, when no options are given, it will scan the list from head to tail, looking for the first match of element. If the element is found, its index (the zero-based position in the list) is returned. Otherwise, if no match is found, nil is returned.

Required arguments

key

The name of the key that holds the list.

element

The value to search for.

Optional arguments

RANK rank

The rank of the first match to return: 1 is the first match from the head, -1 the first from the tail.

COUNT num-matches

The number of matches to return. 0 returns all matches.

MAXLEN len

Compare at most len elements. 0 (the default) scans the whole list.

Details

The optional arguments and options can modify the command's behavior. The RANK option specifies the rank of the first element to return when there are multiple matches. A rank of 1 means to return the first match, 2 to return the second match, and so on.

In the above example, the element c is present multiple times. If you want the index of the second match, write:

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

That is, the second occurrence of c is at position 6. A negative integer as the RANK argument tells LPOS to invert the search direction, starting from the tail to the head.

To get the first element position starting from the tail of the list:

> LPOS mylist c RANK -1
7

Note that the indexes are zero based, so the first element starting from the head of the list is at index0, the next element is at index 1, and so on. This means that the returned indexes are stable whatever the rank is positive or negative.

Sometimes you want to get not just the Nth matching element, but the position of all the first N matching elements. This can be achieved using the COUNT option.

> LPOS mylist c COUNT 2
[2,6]

You 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.

> 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 you 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.

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

Finally, the MAXLEN option tells the command to compare the provided element only with a given maximum number of list items. For example, 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 ona positive or negative rank). This is useful to limit the maximum complexity of the command. It is also useful when you expect the match to be found very early, but you want to be sure that in case this is not true, the command does not take too much time to run.

When MAXLEN is used, it is possible to specify 0 as the maximum number of comparisons, as a way to tell the command you want unlimited comparisons. This is better than giving a very large MAXLEN option because it is more general.

Examples

Redis Software and Redis Cloud compatibility

Redis Software	Redis Cloud	Notes
✅ Standard ✅ Active-Active	✅ Standard ✅ Active-Active

Return information

RESP2 RESP3

Any of the following:

Nil reply: if there is no matching element.
Integer reply: an integer representing the matching element.
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).