DiceDB ZRANGE 命令详解有序集合区间查询的语法、语义与底层实现【免费下载链接】dicedbOpen-source, low-latency key/value engine built on Valkey with query subscriptions and hierarchical storage tiers.项目地址: https://gitcode.com/GitHub_Trending/dic/dicedbZRANGE 是 DiceDB 中用于从有序集合Sorted Set按排名或按分数区间取回元素的查询命令它允许开发者以 1-based 排名或分数范围精确截取有序集合的子集。本文以官方命令文档为骨架结合internal/cmd/cmd_zrange.go、internal/types/sortedset.go等源码实现与测试用例完整讲解其语法、语义、边界行为、错误处理以及配套的 ZRANGE.WATCH 订阅能力帮助你写出正确、高效的区间查询逻辑。命令语法与参数说明ZRANGE 的完整语法如下ZRANGE key start stop [BYSCORE | BYRANK]各参数含义参数说明key待查询的有序集合键名如果该键不存在或未存储有序集合类型行为见下文错误处理一节start区间的起始边界必须为整数stop区间的结束边界必须为整数BYSCORE可选参数表示按分数score区间取元素start/stop此时被解释为分数边界BYRANK可选参数按排名rank区间取元素这也是默认行为从 cmd_zrange.go 的源码可以看到命令要求参数个数为 3 或 4len(c.C.Args) 3 || len(c.C.Args) 4时报参数数量错误第 4 个可选参数通过strings.EqualFold做大小写不敏感匹配来区分BYSCORE与BYRANK若未提供第 4 个参数则默认byRank truevar byScore, byRank false, true if len(c.C.Args) 4 { byScore strings.EqualFold(c.C.Args[3], BYSCORE) byRank strings.EqualFold(c.C.Args[3], BYRANK) }核心语义1-based 排名与闭区间边界理解 ZRANGE 最关键的是三条语义规则默认按排名BYRANK取值排名是 1-based 的即集合中第一个元素的排名为 1 而不是 0start与stop均为闭区间inclusive两端点的元素只要存在都会被包含元素按分数从低到高升序排列响应中的1)、2)、3)前缀即为该元素在集合中的排名序号。因此ZRANGE s 1 3表示返回排名第 1 到第 3 的元素共 3 个如果希望取全部元素可以用覆盖整个集合的区间如1 NN 为集合大小。实战示例BYRANK 与 BYSCORE 的对比官方文档给出了完整可复现的示例。首先用 ZADD 构造一个包含 5 个元素的有序集合localhost:7379 ZADD s 10 a 20 b 30 c 40 d 50 e OK 5按排名取值默认 BYRANKlocalhost:7379 ZRANGE s 1 3 OK 1) 10, a 2) 20, b 3) 30, c返回排名 1、2、3 的a、b、c注意结果中每行的前缀就是元素排名。显式指定 BYRANK扩大区间localhost:7379 ZRANGE s 1 4 BYRANK OK 1) 10, a 2) 20, b 3) 30, c 4) 40, d排名 1 到 4 的元素全部返回端点 4 也被包含闭区间语义。按分数取值BYSCOREstart与stop不再代表排名而是分数边界同样为闭区间。localhost:7379 ZRANGE s 1 3 BYSCORE OK localhost:7379 ZRANGE s 30 100 BYSCORE OK 3) 30, c 4) 40, d 5) 50, e第一个 BYSCORE 示例中集合内不存在分数落在[1, 3]区间的元素因此返回空结果OK后没有任何条目第二个示例返回分数在[30, 100]闭区间内的c(30)、d(40)、e(50)并且前缀 3、4、5 表明这些元素在完整集合中的真实排名。这一点提醒我们BYSCORE 模式下返回元素的数量与排名区间无关仅取决于分数落在边界内的成员。反向取值的两种思路由于元素按分数升序排列官方文档给出了取反序的推荐做法存储分数时对分数取反号flipped sign例如需要降序展示时以负分数存入再用 BYRANK/BYSCORE 区间照常查询即可得到与升序相反的排列顺序。这一思路不改动命令本身而是通过编码层解决排序方向问题适合排行榜从高分到低分的典型诉求。边界情况与错误处理从 cmd_zrange.go 与 errors.go 可以看出 ZRANGE 在以下场景中的具体行为场景行为依据参数个数不为 3 或 4返回wrong number of arguments for ZRANGE commandErrWrongArgumentCount见 cmd_zrange.gostart/stop非整数返回value is not an integer or a floatErrInvalidNumberFormatstrconv.Atoi解析失败键不存在返回空结果非错误s.Get(key)返回nil时直接返回空元素列表键存在但类型不是有序集合返回wrongtype operation against a key holding the wrong kind of valueErrWrongTypeOperation类型断言失败以上行为均有对应的测试用例佐证tests/commands/ironhawk/zrange_test.go 覆盖了坏参数、非数字边界、不存在键、对字符串键执行 ZRANGE 等场景eval_test.go 则进一步覆盖了负索引、start stop、索引越界、无效选项等更细粒度的语义。源码解读从命令解析到有序集合遍历ZRANGE 的执行链路清晰地体现了 DiceDB 的命令架构命令注册cZRANGE通过CommandRegistry.AddCommand注册携带Eval、Execute与IsWatchable: true元信息见 cmd_zrange.go分片路由executeZRANGE通过sm.GetShardForKey(c.C.Args[0])依据 key 定位到对应分片shard再调用分片线程的 Store 执行evalZRANGE见 cmd_zrange.go类型检查从 Store 取出对象后校验obj.Type ! object.ObjTypeSortedSet防止对错误类型执行操作数据遍历核心算法在 types/sortedset.go 的SortedSet.ZRANGE方法中——byScore为真时走GetByScoreRange按分数区间取节点否则走GetByRankRange(start, stop, false)按排名区间取节点随后用首个节点的FindRank计算起始排名为每个元素填充wire.ZElement{Member, Score, Rank}返回给客户端。从底层数据结构看DiceDB 的有序集合基于github.com/wangjia184/sortedset实现types/sortedset.goZADD 的写入逻辑支持 NX/XX/GT/LT/CH/INCR 等选项ZADD 命令文档与此同时仓库中还维护着一套自研的 B-tree 有序集合实现internal/eval/sortedset/sorted_set.go其GetRange通过Ascend/Descend遍历并支持负索引归一化与越界裁剪可作为理解排序与区间语义的补充参考。进阶能力ZRANGE.WATCH 查询订阅ZRANGE 在 DiceDB 中是可订阅watchable命令IsWatchable: true对应的 ZRANGE.WATCH 会针对 ZRANGE 建立查询订阅客户端执行后进入 watch 模式当 key 被其他客户端更新时订阅方会收到完整的 ZRANGE 输出结果而非仅仅一条变更通知。client1:7379 ZADD users 10 alice 20 bob 30 charlie OK 3 client1:7379 ZRANGE.WATCH users 1 5 entered the watch mode for ZRANGE.WATCH users client2:7379 ZADD users 40 daniel OK 1 client1:7379 ... entered the watch mode for ZRANGE.WATCH users OK [fingerprint1007898011883907067] 1) 10, alice 2) 20, bob 3) 30, charlie 4) 40, daniel实现上cmd_zrange_watch.go 的evalZRANGEWATCH直接复用evalZRANGE完成查询再通过c.Fingerprint()为响应附加指纹fingerprint用于客户端识别结果版本executeZRANGEWATCH同样先做参数数量校验再路由到对应分片。这意味着你可以在排行榜、实时评分等场景中用 ZRANGE.WATCH 取代轮询 ZRANGE的陈旧模式让客户端在数据变更时自动收到最新的区间结果。小结ZRANGE 是 DiceDB 有序集合查询的基础命令默认 1-based 排名区间、闭区间边界、升序排列三大语义决定了绝大多数用法BYSCORE 模式将其扩展为按分数区间过滤配合负分数编码可实现降序查询ZRANGE.WATCH 则赋予其实时订阅能力。理解其参数校验、类型检查与底层遍历实现能帮助你在排行榜、区间统计、实时数据流等场景中准确、高效地使用这一命令。【免费下载链接】dicedbOpen-source, low-latency key/value engine built on Valkey with query subscriptions and hierarchical storage tiers.项目地址: https://gitcode.com/GitHub_Trending/dic/dicedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DiceDB ZRANGE 命令详解：有序集合区间查询的语法、语义与底层实现
DiceDB ZRANGE 命令详解有序集合区间查询的语法、语义与底层实现【免费下载链接】dicedbOpen-source, low-latency key/value engine built on Valkey with query subscriptions and hierarchical storage tiers.项目地址: https://gitcode.com/GitHub_Trending/dic/dicedbZRANGE 是 DiceDB 中用于从有序集合Sorted Set按排名或按分数区间取回元素的查询命令它允许开发者以 1-based 排名或分数范围精确截取有序集合的子集。本文以官方命令文档为骨架结合internal/cmd/cmd_zrange.go、internal/types/sortedset.go等源码实现与测试用例完整讲解其语法、语义、边界行为、错误处理以及配套的 ZRANGE.WATCH 订阅能力帮助你写出正确、高效的区间查询逻辑。命令语法与参数说明ZRANGE 的完整语法如下ZRANGE key start stop [BYSCORE | BYRANK]各参数含义参数说明key待查询的有序集合键名如果该键不存在或未存储有序集合类型行为见下文错误处理一节start区间的起始边界必须为整数stop区间的结束边界必须为整数BYSCORE可选参数表示按分数score区间取元素start/stop此时被解释为分数边界BYRANK可选参数按排名rank区间取元素这也是默认行为从 cmd_zrange.go 的源码可以看到命令要求参数个数为 3 或 4len(c.C.Args) 3 || len(c.C.Args) 4时报参数数量错误第 4 个可选参数通过strings.EqualFold做大小写不敏感匹配来区分BYSCORE与BYRANK若未提供第 4 个参数则默认byRank truevar byScore, byRank false, true if len(c.C.Args) 4 { byScore strings.EqualFold(c.C.Args[3], BYSCORE) byRank strings.EqualFold(c.C.Args[3], BYRANK) }核心语义1-based 排名与闭区间边界理解 ZRANGE 最关键的是三条语义规则默认按排名BYRANK取值排名是 1-based 的即集合中第一个元素的排名为 1 而不是 0start与stop均为闭区间inclusive两端点的元素只要存在都会被包含元素按分数从低到高升序排列响应中的1)、2)、3)前缀即为该元素在集合中的排名序号。因此ZRANGE s 1 3表示返回排名第 1 到第 3 的元素共 3 个如果希望取全部元素可以用覆盖整个集合的区间如1 NN 为集合大小。实战示例BYRANK 与 BYSCORE 的对比官方文档给出了完整可复现的示例。首先用 ZADD 构造一个包含 5 个元素的有序集合localhost:7379 ZADD s 10 a 20 b 30 c 40 d 50 e OK 5按排名取值默认 BYRANKlocalhost:7379 ZRANGE s 1 3 OK 1) 10, a 2) 20, b 3) 30, c返回排名 1、2、3 的a、b、c注意结果中每行的前缀就是元素排名。显式指定 BYRANK扩大区间localhost:7379 ZRANGE s 1 4 BYRANK OK 1) 10, a 2) 20, b 3) 30, c 4) 40, d排名 1 到 4 的元素全部返回端点 4 也被包含闭区间语义。按分数取值BYSCOREstart与stop不再代表排名而是分数边界同样为闭区间。localhost:7379 ZRANGE s 1 3 BYSCORE OK localhost:7379 ZRANGE s 30 100 BYSCORE OK 3) 30, c 4) 40, d 5) 50, e第一个 BYSCORE 示例中集合内不存在分数落在[1, 3]区间的元素因此返回空结果OK后没有任何条目第二个示例返回分数在[30, 100]闭区间内的c(30)、d(40)、e(50)并且前缀 3、4、5 表明这些元素在完整集合中的真实排名。这一点提醒我们BYSCORE 模式下返回元素的数量与排名区间无关仅取决于分数落在边界内的成员。反向取值的两种思路由于元素按分数升序排列官方文档给出了取反序的推荐做法存储分数时对分数取反号flipped sign例如需要降序展示时以负分数存入再用 BYRANK/BYSCORE 区间照常查询即可得到与升序相反的排列顺序。这一思路不改动命令本身而是通过编码层解决排序方向问题适合排行榜从高分到低分的典型诉求。边界情况与错误处理从 cmd_zrange.go 与 errors.go 可以看出 ZRANGE 在以下场景中的具体行为场景行为依据参数个数不为 3 或 4返回wrong number of arguments for ZRANGE commandErrWrongArgumentCount见 cmd_zrange.gostart/stop非整数返回value is not an integer or a floatErrInvalidNumberFormatstrconv.Atoi解析失败键不存在返回空结果非错误s.Get(key)返回nil时直接返回空元素列表键存在但类型不是有序集合返回wrongtype operation against a key holding the wrong kind of valueErrWrongTypeOperation类型断言失败以上行为均有对应的测试用例佐证tests/commands/ironhawk/zrange_test.go 覆盖了坏参数、非数字边界、不存在键、对字符串键执行 ZRANGE 等场景eval_test.go 则进一步覆盖了负索引、start stop、索引越界、无效选项等更细粒度的语义。源码解读从命令解析到有序集合遍历ZRANGE 的执行链路清晰地体现了 DiceDB 的命令架构命令注册cZRANGE通过CommandRegistry.AddCommand注册携带Eval、Execute与IsWatchable: true元信息见 cmd_zrange.go分片路由executeZRANGE通过sm.GetShardForKey(c.C.Args[0])依据 key 定位到对应分片shard再调用分片线程的 Store 执行evalZRANGE见 cmd_zrange.go类型检查从 Store 取出对象后校验obj.Type ! object.ObjTypeSortedSet防止对错误类型执行操作数据遍历核心算法在 types/sortedset.go 的SortedSet.ZRANGE方法中——byScore为真时走GetByScoreRange按分数区间取节点否则走GetByRankRange(start, stop, false)按排名区间取节点随后用首个节点的FindRank计算起始排名为每个元素填充wire.ZElement{Member, Score, Rank}返回给客户端。从底层数据结构看DiceDB 的有序集合基于github.com/wangjia184/sortedset实现types/sortedset.goZADD 的写入逻辑支持 NX/XX/GT/LT/CH/INCR 等选项ZADD 命令文档与此同时仓库中还维护着一套自研的 B-tree 有序集合实现internal/eval/sortedset/sorted_set.go其GetRange通过Ascend/Descend遍历并支持负索引归一化与越界裁剪可作为理解排序与区间语义的补充参考。进阶能力ZRANGE.WATCH 查询订阅ZRANGE 在 DiceDB 中是可订阅watchable命令IsWatchable: true对应的 ZRANGE.WATCH 会针对 ZRANGE 建立查询订阅客户端执行后进入 watch 模式当 key 被其他客户端更新时订阅方会收到完整的 ZRANGE 输出结果而非仅仅一条变更通知。client1:7379 ZADD users 10 alice 20 bob 30 charlie OK 3 client1:7379 ZRANGE.WATCH users 1 5 entered the watch mode for ZRANGE.WATCH users client2:7379 ZADD users 40 daniel OK 1 client1:7379 ... entered the watch mode for ZRANGE.WATCH users OK [fingerprint1007898011883907067] 1) 10, alice 2) 20, bob 3) 30, charlie 4) 40, daniel实现上cmd_zrange_watch.go 的evalZRANGEWATCH直接复用evalZRANGE完成查询再通过c.Fingerprint()为响应附加指纹fingerprint用于客户端识别结果版本executeZRANGEWATCH同样先做参数数量校验再路由到对应分片。这意味着你可以在排行榜、实时评分等场景中用 ZRANGE.WATCH 取代轮询 ZRANGE的陈旧模式让客户端在数据变更时自动收到最新的区间结果。小结ZRANGE 是 DiceDB 有序集合查询的基础命令默认 1-based 排名区间、闭区间边界、升序排列三大语义决定了绝大多数用法BYSCORE 模式将其扩展为按分数区间过滤配合负分数编码可实现降序查询ZRANGE.WATCH 则赋予其实时订阅能力。理解其参数校验、类型检查与底层遍历实现能帮助你在排行榜、区间统计、实时数据流等场景中准确、高效地使用这一命令。【免费下载链接】dicedbOpen-source, low-latency key/value engine built on Valkey with query subscriptions and hierarchical storage tiers.项目地址: https://gitcode.com/GitHub_Trending/dic/dicedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
