{ "schema_version": 2, "id": "commands/lpos", "title": "LPOS", "url": "https://redis.io/docs/latest/commands/lpos/", "summary": "Returns the index of matching elements in a list.", "since": "6.0.6", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-07-24T11:07:00+02:00", "page_type": "content", "content_hash": "229f352bbbd179f9d068dc87459dccec2359d2dcc44ca7663eeecea6b6594a1d", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "The command returns the index of matching elements inside a Redis list.\nBy default, when no options are given, it will scan the list from head to tail,\nlooking 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." }, { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
key\n\nThe name of the key that holds the list.\n\n
\n\n
element\n\nThe value to search for.\n\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "
RANK rank\n\nThe rank of the first match to return: `1` is the first match from the head, `-1` the first from the tail.\n\n
\n\n
COUNT num-matches\n\nThe number of matches to return. `0` returns all matches.\n\n
\n\n
MAXLEN len\n\nCompare at most `len` elements. `0` (the default) scans the whole list.\n\n
" }, { "id": "details", "title": "Details", "role": "content", "text": "The optional arguments and options can modify the command's behavior.\nThe `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.\n\nIn the above example, the element `c` is present multiple times. If you want the index of the second match, write:\n\n[code example]\n\nThat is, the second occurrence of `c` is at position 6.\nA negative integer as the `RANK` argument tells `LPOS` to invert the search direction, starting from the tail to the head.\n\nTo get the first element position starting from the tail of the list:\n\n[code example]\n\nNote 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.\n\nSometimes 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.\n\n[code example]\n\nYou 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.\n\n[code example]\n\nWhen `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.\n\n[code example]\n\nWhen `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`.\n\nFinally, 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.\n\nWhen `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." }, { "id": "examples", "title": "Examples", "role": "example", "text": "redis> RPUSH mylist a b c d 1 2 3 4 3 3 3\n(integer) 11\nredis> LPOS mylist 3\n(integer) 6\nredis> LPOS mylist 3 COUNT 0 RANK 2\n1) (integer) 8\n2) (integer) 9\n3) (integer) 10" }, { "id": "redis-software-and-redis-cloud-compatibility", "title": "Redis Software and Redis Cloud compatibility", "role": "content", "text": "| Redis
Software | Redis
Cloud | Notes |\n|:----------------------|:-----------------|:------|\n| ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\nAny of the following:\n* [Nil reply](../../develop/reference/protocol-spec#bulk-strings): if there is no matching element.\n* [Integer reply](../../develop/reference/protocol-spec#integers): an integer representing the matching element.\n* [Array reply](../../develop/reference/protocol-spec#arrays): If the COUNT option is given, an array of integers representing the matching elements (or an empty array if there are no matches).\n\n**RESP3:**\n\nAny of the following:\n* [Null reply](../../develop/reference/protocol-spec#nulls): if there is no matching element.\n* [Integer reply](../../develop/reference/protocol-spec#integers): an integer representing the matching element.\n* [Array reply](../../develop/reference/protocol-spec#arrays): If the COUNT option is given, an array of integers representing the matching elements (or an empty array if there are no matches)." } ], "examples": [ { "id": "details-ex0", "language": "plaintext", "code": "> RPUSH mylist a b c 1 2 3 c c\n> LPOS mylist c RANK 2\n6", "section_id": "details" }, { "id": "details-ex1", "language": "plaintext", "code": "> LPOS mylist c RANK -1\n7", "section_id": "details" }, { "id": "details-ex2", "language": "plaintext", "code": "> LPOS mylist c COUNT 2\n[2,6]", "section_id": "details" }, { "id": "details-ex3", "language": "plaintext", "code": "> LPOS mylist c RANK -1 COUNT 2\n[7,6]", "section_id": "details" }, { "id": "details-ex4", "language": "plaintext", "code": "> LPOS mylist c COUNT 0\n[2,6,7]", "section_id": "details" } ] }