{ "schema_version": 2, "id": "commands/zrangebyscore", "title": "ZRANGEBYSCORE", "url": "https://redis.io/docs/latest/commands/zrangebyscore/", "summary": "Returns members in a sorted set within a range of scores.", "since": "1.0.5", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-07-24T11:07:00+02:00", "page_type": "content", "content_hash": "04879f70e8da58ddd0d700ab26465579604df89626c2b215314bc10122ac1f6b", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "Returns all the elements in the sorted set at `key` with a score between `min`\nand `max` (including elements with score equal to `min` or `max`).\nThe elements are considered to be ordered from low to high scores.\n\nThe elements having the same score are returned in lexicographical order (this\nfollows from a property of the sorted set implementation in Redis and does not\ninvolve further computation).\n\nThe optional `LIMIT` argument can be used to only get a range of the matching\nelements (similar to _SELECT LIMIT offset, count_ in SQL). A negative `count`\nreturns all elements from the `offset`.\nKeep in mind that if `offset` is large, the sorted set needs to be traversed for\n`offset` elements before getting to the elements to return, which can add up to\nO(N) time complexity.\n\nThe optional `WITHSCORES` argument makes the command return both the element and\nits score, instead of the element alone.\nThis option is available since Redis 2.0." }, { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
key\n\nThe name of the key that holds the sorted set.\n\n
\n\n
min\n\nThe minimum score. The bound is inclusive unless prefixed with `(`. Use `-inf` for no lower bound.\n\n
\n\n
max\n\nThe maximum score. The bound is inclusive unless prefixed with `(`. Use `+inf` for no upper bound.\n\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "
WITHSCORES\n\nAlso return the score of each member.\n\n
\n\n
LIMIT offset count\n\nSkip `offset` matching members and return up to `count` of them. A negative `count` returns all remaining members.\n\n
" }, { "id": "examples", "title": "Examples", "role": "example", "text": "redis> ZADD myzset 1 \"one\"\n(integer) 1\nredis> ZADD myzset 2 \"two\"\n(integer) 1\nredis> ZADD myzset 3 \"three\"\n(integer) 1\nredis> ZRANGEBYSCORE myzset -inf +inf\n1) \"one\"\n2) \"two\"\n3) \"three\"\nredis> ZRANGEBYSCORE myzset 1 2\n1) \"one\"\n2) \"two\"\nredis> ZRANGEBYSCORE myzset (1 2\n1) \"two\"\nredis> ZRANGEBYSCORE myzset (1 (2\n(empty array)" }, { "id": "details", "title": "Details", "role": "content", "text": "" }, { "id": "exclusive-intervals-and-infinity", "title": "Exclusive intervals and infinity", "role": "content", "text": "`min` and `max` can be `-inf` and `+inf`, so that you are not required to know\nthe highest or lowest score in the sorted set to get all elements from or up to\na certain score.\n\nBy default, the interval specified by `min` and `max` is closed (inclusive).\nIt is possible to specify an open interval (exclusive) by prefixing the score\nwith the character `(`.\nFor example:\n\n[code example]\n\nWill return all elements with `1 < score <= 5` while:\n\n[code example]\n\nWill return all the elements with `5 < score < 10` (5 and 10 excluded)." }, { "id": "pattern-weighted-random-selection-of-an-element", "title": "Pattern: weighted random selection of an element", "role": "content", "text": "Normally `ZRANGEBYSCORE` is simply used in order to get range of items\nwhere the score is the indexed integer key, however it is possible to do less\nobvious things with the command.\n\nFor example a common problem when implementing Markov chains and other algorithms\nis to select an element at random from a set, but different elements may have\ndifferent weights that change how likely it is they are picked.\n\nThis is how we use this command in order to mount such an algorithm:\n\nImagine you have elements A, B and C with weights 1, 2 and 3.\nYou compute the sum of the weights, which is 1+2+3 = 6\n\nAt this point you add all the elements into a sorted set using this algorithm:\n\n[code example]\n\nThis means that you set:\n\n[code example]\n\nSince this involves approximations, in order to avoid C is set to,\nlike, 0.998 instead of 1, we just modify the above algorithm to make sure\nthe last score is 1 (left as an exercise for the reader...).\n\nAt this point, each time you want to get a weighted random element,\njust compute a random number between 0 and 1 (which is like calling\n`rand()` in most languages), so you can just do:\n\n RANDOM_ELE = ZRANGEBYSCORE key RAND() +inf LIMIT 0 1" }, { "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 | Deprecated as of Redis v6.2.0. |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\n* [Array reply](../../develop/reference/protocol-spec#arrays): a list of the members with, optionally, their scores in the specified score range.\n\n**RESP3:**\n\n* [Array reply](../../develop/reference/protocol-spec#arrays): a list of the members with, optionally, their scores in the specified score range." } ], "examples": [ { "id": "exclusive-intervals-and-infinity-ex0", "language": "plaintext", "code": "ZRANGEBYSCORE zset (1 5", "section_id": "exclusive-intervals-and-infinity" }, { "id": "exclusive-intervals-and-infinity-ex1", "language": "plaintext", "code": "ZRANGEBYSCORE zset (5 (10", "section_id": "exclusive-intervals-and-infinity" }, { "id": "pattern-weighted-random-selection-of-an-element-ex0", "language": "plaintext", "code": "SUM = ELEMENTS.TOTAL_WEIGHT // 6 in this case.\nSCORE = 0\nFOREACH ELE in ELEMENTS\n SCORE += ELE.weight / SUM\n ZADD KEY SCORE ELE\nEND", "section_id": "pattern-weighted-random-selection-of-an-element" }, { "id": "pattern-weighted-random-selection-of-an-element-ex1", "language": "plaintext", "code": "A to score 0.16\nB to score .5\nC to score 1", "section_id": "pattern-weighted-random-selection-of-an-element" } ] }