---

Zset 有序集合

有序集合相对于字符串、列表、哈希、集合来说会有⼀些陌⽣。它保留了集合不能有重复成员的特点，但与集合不同的是，有序集合中的每个元素都有⼀个唯⼀的浮点类型的分数（score）与之关联，着使得有序集合中的元素是可以维护有序性的，但这个有序不是⽤下标作为排序依据⽽是⽤这个分数。如图 2-26 所⽰，该有序集合显⽰了三国中的武将的武⼒。

这里的有序指的是升序/降序

而 zset 内部就是按照升序排列的

图 2-26 有序集合

有序集合提供了获取指定分数和元素范围查找、计算成员排名等功能，合理地利⽤有序集合，可以帮助我们在实际开发中解决很多问题。

有序集合中的元素是不能重复的，但分数允许重复。类⽐于⼀次考试之后，每个⼈⼀定有⼀个唯⼀的分数，但分数允许相同。

表 2-7 列表、集合、有序集合三者的异同点。

列表的有序是指顺序很重要，比如 a,b,c 和 c,b,a 是不一样的

有序集合的有序是指升序/降序

普通命令

ZADD

zadd

添加或者更新指定的元素以及关联的分数到 zset 中，分数应该符合 double 类型，+inf/-inf 作为正负极限也是合法的。

ZADD 的相关选项：

• XX：仅仅⽤于更新已经存在的元素，不会添加新元素。
• NX：仅⽤于添加新元素，不会更新已经存在的元素。

这里说的元素是 member，而不是 score

如果不添加 XX 或者 NX 时，如果当前 member 已经存在就更新 score，如果当前 member 不存在就添加新 member

如果添加了 XX，如果当前 member 已经存在就更新 score，不存在就不管，即只做修改不做添加

如果添加了 NX，如果当前 member 不存在就添加新 member，存在就不管，即只做添加不做修改

• CH（change）：默认情况下，ZADD 返回的是本次添加的元素个数，但指定这个选项之后，就会还包含本次更新的元素的个数，会影响 zadd 的返回值。
• INCR：此时命令类似 ZINCRBY 的效果，将元素的分数加上指定的分数。此时只能指定⼀个元素和分数。此时的返回值是修改后的分数

• LT（less than）：这个选项指定只有当给定分数小于目标成员当前分数时，才会对该成员进行添加或更新操作。这个选项不会阻止添加新元素。LT 选项适用于那些只想在成员的分数降低时才更新分数的场景，如调整排名或分数减少的特定业务逻辑。
• GT（greater than）：与 LT 相对，GT 选项指定只有当给定分数大于目标成员当前分数时，才执行添加或更新操作。这个选项不会阻止添加新元素。GT 适用于只有在分数提高时才需要更新的场景，例如更新最高分、促销活动中的积分增加等。
• 这两个选项在 Redis 6.2.0 版本引入，旨在让用户能够根据分数范围决定是否添加或更新元素。

语法：

ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member
...]

member 和 score 称为一个 “pair”，可以通过 member 查找 score，也可以通过 score 查找 member

命令有效版本：1.2.0 之后

时间复杂度：O(log(N))，N 指的是有序集合中的元素个数

由于 zset 是有序结构，要求新增的元素要放到合适的位置。之所以是 logN 而不是 N，是因为 zset 内部的数据结构是跳表

返回值：本次添加成功的元素个数（如果是修改操作，不算是个数，即0）。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 1 "uno"
(integer) 1
redis> ZADD myzset 2 "two" 3 "three"
(integer) 2
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "one"
2) "1"
3) "uno"
4) "1"
5) "two"
6) "2"
7) "three"
8) "3"
redis> ZADD myzset 10 one 20 two 30 three
(integer) 0
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "uno"
2) "1"
3) "one"
4) "10"
5) "two"
6) "20"
7) "three"
8) "30"
redis> ZADD myzset CH 100 one 200 two 300 three
(integer) 3
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "uno"
2) "1"
3) "one"
4) "100"
5) "two"
6) "200"
7) "three"
8) "300"
redis> ZADD myzset XX 1 one 2 two 3 three 4 four 5 five
(integer) 0
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "one"
2) "1"
3) "uno"
4) "1"
5) "two"
6) "2"
7) "three"
8) "3"
redis> ZADD myzset NX 100 one 200 two 300 three 400 four 500 five
(integer) 2
redis> ZRANGE myzset 0 -1 WITHSCORES
 1) "one"
 2) "1"
 3) "uno"
 4) "1"
 5) "two"
 6) "2"
 7) "three"
 8) "3"
 9) "four"
10) "400"
11) "five"
12) "500"
redis> ZADD myzset INCR 10 one
"11"
redis> ZRANGE myzset 0 -1 WITHSCORES
 1) "uno"
 2) "1"
 3) "two"
 4) "2"
 5) "three"
 6) "3"
 7) "one"
 8) "11"
 9) "four"
10) "400"
11) "five"
12) "500"
redis> ZADD myzset -inf "negative infinity" +inf "positive infinity"
(integer) 2
redis> ZRANGE myzset 0 -1 WITHSCORES
 1) "negative infinity"
 2) "-inf"
 3) "uno"
 4) "1"
 5) "two"
 6) "2"
 7) "three"
 8) "3"
 9) "one"
10) "11"
11) "four"
12) "400"
13) "five"
14) "500"
15) "positive infinity"
16) "inf"

ZCARD

zcard

获取⼀个 zset 的基数（cardinality），即 zset 中的元素个数。

语法：

ZCARD key

命令有效版本：1.2.0 之后

时间复杂度：O(1)

返回值：zset 内的元素个数。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZCARD myzset
(integer) 2

ZCOUNT

zcount

返回分数在 min 和 max 之间的元素个数，默认情况下，min 和 max 都是包含的（即闭区间），可以通过 ( 排除（变为开区间）。

语法：

ZCOUNT key min max

命令有效版本：2.0.0 之后

时间复杂度：O(log(N))，先根据 min 找到对应的元素，再根据 max 找到对应的元素，这两个操作都是 logN 的时间复杂度

实际上 zset 内部会记录每个元素当前的“排行”/“次序”

查询到元素，就直接知道了元素所在的“次序”，就可以直接把 max 对应的元素次序和 min 对应的元素次序，做一个减法即可

返回值：满⾜条件的元素列表个数。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZCOUNT myzset -inf +inf
(integer) 3
redis> ZCOUNT myzset 1 3
(integer) 3
redis> ZCOUNT myzset (1 3
(integer) 2
redis> ZCOUNT myzset (1 (3
(integer) 1

ZRANGE

zrange

返回指定区间⾥的元素，分数按照升序。带上 WITHSCORES 可以把分数也返回。

语法：

ZRANGE key start stop [WITHSCORES]

此处的 [start, stop] 为下标构成的区间. 从 0 开始, ⽀持负数

命令有效版本：1.2.0 之后

时间复杂度：O(log(N)+M)，此处先根据下标找到边界值，start 或者 stop 的，然后就需要遍历了

返回值：区间内的元素列表（按升序返回）。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "one"
2) "1"
3) "two"
4) "2"
5) "three"
6) "3"
redis> ZRANGE myzset 0 -1
1) "one"
2) "two"
3) "three"
redis> ZRANGE myzset 2 3
1) "three"
redis> ZRANGE myzset -2 -1
1) "two"
2) "three"

ZREVRANGE

zrevrange

z reverse range，返回指定区间⾥的元素，分数按照降序。带上 WITHSCORES 可以把分数也返回。

备注：这个命令可能在 6.2.0 之后废弃，并且功能合并到 ZRANGE 中。

语法：

ZREVRANGE key start stop [WITHSCORES]

命令有效版本：1.2.0 之后

时间复杂度：O(log(N)+M)

返回值：区间内的元素列表。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZREVRANGE myzset 0 -1 WITHSCORES
1) "three"
2) "3"
3) "two"
4) "2"
5) "one"
6) "1"
redis> ZREVRANGE myzset 0 -1
1) "three"
2) "two"
3) "one"
redis> ZREVRANGE myzset 2 3
1) "one"
redis> ZREVRANGE myzset -2 -1
1) "two"
2) "one"

ZRANGEBYSCORE

zrangebyscore

返回分数在 min 和 max 之间的元素，默认情况下，min 和 max 都是包含的，可以通过 ( 排除。

备注：这个命令可能在 6.2.0 之后废弃，并且功能合并到 ZRANGE 中。

语法：

ZRANGEBYSCORE key min max [WITHSCORES]

命令有效版本：1.0.5 之后

时间复杂度：O(log(N)+M)

返回值：区间内的元素列表。

示例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZRANGEBYSCORE myzset -inf +inf
1) "one"
2) "two"
3) "three"
redis> ZRANGEBYSCORE myzset 1 2
1) "one"
2) "two"
redis> ZRANGEBYSCORE myzset (1 2
1) "two"
redis> ZRANGEBYSCORE myzset (1 (2
(empty array)

ZPOPMAX

zpopmax

删除并返回分数最⾼的 count 个元素。（类似于尾删）

语法：

ZPOPMAX key [count]

命令有效版本：5.0.0 之后

时间复杂度：O(log(N) * M)，N 是有序集合的元素个数，M 是要删除的元素个数

既然这个操作是尾删，为什么不把最后一个元素的位置特殊记录下来，这样后续查找删除就可以 O(1) 了，省去查找的过程。但实际上 Redis 确定有记录了尾部这样的特定位置，但删除时没有应用这个特性，而是直接调用了一个通用的删除函数，给定一个 member 的值，进行查找，找到位置后再删除。

没有这么做的原因可能是因为 O(logN) 速度并不是很慢，优化为 O(1) 性价比不高

返回值：元素和分数列表。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZPOPMAX myzset
1) "three"
2) "3"

如果存在多个元素，分数相同，同时为最大值，zpopmax 只删除的是其中一个，按照字典序决定先后

BZPOPMAX

bzpopmax

ZPOPMAX 的阻塞版本。

我们的这个有序集合 zset 可以视为一个优先级队列，有时可能需要带有阻塞功能

语法：

BZPOPMAX key [key ...] timeout

单位是秒

命令有效版本：5.0.0 之后

时间复杂度：O(log(N))

返回值：元素列表。

⽰例：

redis> DEL zset1 zset2
(integer) 0
redis> ZADD zset1 0 a 1 b 2 c
(integer) 3
redis> BZPOPMAX zset1 zset2 0
1) "zset1"
2) "c"
3) "2"

ZPOPMIN

zpopmin

删除并返回分数最低的 count 个元素。

语法：

ZPOPMIN key [count]

命令有效版本：5.0.0 之后

时间复杂度：O(log(N) * M)

返回值：分数和元素列表。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZPOPMIN myzset
1) "one"
2) "1"

BZPOPMIN

bzpopmin

ZPOPMIN 的阻塞版本。

语法：

BZPOPMIN key [key ...] timeout

命令有效版本：5.0.0 之后

时间复杂度：O(log(N))

返回值：元素列表。

⽰例：

redis> DEL zset1 zset2
(integer) 0
redis> ZADD zset1 0 a 1 b 2 c
(integer) 3
redis> BZPOPMIN zset1 zset2 0
1) "zset1"
2) "a"
3) "0"

ZRANK

zrank

返回指定元素的排名，升序。下标从0开始算

语法：

ZRANK key member

命令有效版本：2.0.0 之后

时间复杂度：O(log(N))

返回值：排名。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZRANK myzset "three"
(integer) 2
redis> ZRANK myzset "four"
(nil)

ZREVRANK

zrevrank

re-reverse

返回指定元素的排名，降序。下标从0开始算

语法：

ZREVRANK key member

命令有效版本：2.0.0 之后

时间复杂度：O(log(N))

返回值：排名。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZREVRANK myzset "one"
(integer) 2
redis> ZREVRANK myzset "four"
(nil)

ZSCORE

zscore

返回指定元素的分数。

语法：

ZSCORE key member

命令有效版本：1.2.0 之后

时间复杂度：O(1)

此处是 Redis 对于这样的查询做了特殊优化，用额外的空间进行优化到 O(1)

返回值：分数。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZSCORE myzset "one"
"1"

ZREM

zrem

删除指定的元素。

语法：

ZREM key member [member ...]

命令有效版本：1.2.0 之后

时间复杂度：O(M*log(N))，M 是 member 的个数，N 是整个有序集合的元素个数

返回值：本次操作删除的元素个数。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZREM myzset "two"
(integer) 1
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "one"
2) "1"
3) "three"
4) "3"

ZREMRANGEBYRANK

zremrangebyrank

按照排序，升序删除指定范围的元素，左闭右闭。

语法：

ZREMRANGEBYRANK key start stop

命令有效版本：2.0.0 之后

时间复杂度：O(log(N)+M)，M 是 [start, stop] 的大小，N 是整个有序集合的元素个数，此处查找位置，只需要查找一次 start 和 stop，因此这部分只是一个 logN

返回值：本次操作删除的元素个数。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZREMRANGEBYRANK myzset 0 1
(integer) 2
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "three"
2) "3"

ZREMRANGEBYSCORE

zremrangebyscore

按照分数删除指定范围的元素，左闭右闭。可以用 ( 排除边界值

语法：

ZREMRANGEBYSCORE key min max

命令有效版本：1.2.0 之后

时间复杂度：O(log(N)+M)

返回值：本次操作删除的元素个数。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZADD myzset 3 "three"
(integer) 1
redis> ZREMRANGEBYSCORE myzset -inf (2
(integer) 1
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "two"
2) "2"
3) "three"
4) "3"

ZINCRBY

为指定的元素的关联分数添加指定的分数值。修改分数后还会自动移动保持有序集合的顺序

语法：

ZINCRBY key increment member

命令有效版本：1.2.0 之后

时间复杂度：O(log(N))

返回值：增加后元素的分数。

⽰例：

redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 2 "two"
(integer) 1
redis> ZINCRBY myzset 2 "one"
"3"
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "two"
2) "2"
3) "one"
4) "3"

集合间操作

zinter、zunion、zdiff 这几个是从 Redis 6.2 才有的，此处暂不涉及

图 2-27 有序集合的交集操作

ZINTERSTORE

zinterstore

求出给定有序集合中元素的交集并保存进⽬标有序集合中，在合并过程中以元素为单位进⾏合并，元素对应的分数按照不同的聚合⽅式和权重得到新的分数。

语法：

destination：把交集后的结果存储到 destination

numkeys：描述了后续有几个 key 要参与交集运算，这是一个整数。这么做的原因是 numkeys 描述出 key 的个数之后，就可以明确的指导后面的“选项”是从哪里开始了，避免选项和 keys 混淆

weights：权重，可以写成小数

aggregate：如果 member 相同，score 不同，交集合并之后，score 的算法是 取 sum/min/max，默认是 sum

ZINTERSTORE destination numkeys key [key ...] [WEIGHTS weight
[weight ...]] [AGGREGATE <SUM | MIN | MAX>]

命令有效版本：2.0.0 之后

时间复杂度：O(N*K)+O(M*log(M)) N 是输⼊的有序集合中，最⼩的有序集合的元素个数；K 是输⼊了⼏个有序集合；M 是最终结果的有序集合的元素个数。

这个时间复杂度可以化简一下得到一个近似值，K 一般不会很大，近似看作 1；假设 N 和 M 是接近的（这里不太严谨，只是近似来看）。此时时间复杂度就变为了 O(M)+O(M*logM)，又可以近似于 O(M*logM)

返回值：⽬标集合中的元素个数

⽰例：

redis> ZADD zset1 1 "one"
(integer) 1
redis> ZADD zset1 2 "two"
(integer) 1
redis> ZADD zset2 1 "one"
(integer) 1
redis> ZADD zset2 2 "two"
(integer) 1
redis> ZADD zset2 3 "three"
(integer) 1
redis> ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3
(integer) 2
redis> ZRANGE out 0 -1 WITHSCORES
1) "one"
2) "5"
3) "two"
4) "10"

图 2-28 有序集合的并集操作

ZUNIONSTORE

zunionstore

求出给定有序集合中元素的并集并保存进⽬标有序集合中，在合并过程中以元素为单位进⾏合并，元素对应的分数按照不同的聚合⽅式和权重得到新的分数。

语法：

ZUNIONSTORE destination numkeys key [key ...] [WEIGHTS weight
 [weight ...]] [AGGREGATE <SUM | MIN | MAX>]

命令有效版本：2.0.0 之后

时间复杂度：O(N)+O(M*log(M)) N 是输⼊的有序集合总的元素个数; M 是最终结果的有序集合的元素个数.

返回值：⽬标集合中的元素个数

⽰例：

redis> ZADD zset1 1 "one"
(integer) 1
redis> ZADD zset1 2 "two"
(integer) 1
redis> ZADD zset2 1 "one"
(integer) 1
redis> ZADD zset2 2 "two"
(integer) 1
redis> ZADD zset2 3 "three"
(integer) 1
redis> ZUNIONSTORE out 2 zset1 zset2 WEIGHTS 2 3
(integer) 3
redis> ZRANGE out 0 -1 WITHSCORES
1) "one"
2) "5"
3) "three"
4) "9"
5) "two"
6) "10"

命令⼩结

表 2-8 有序集合命令

内部编码

有序集合类型的内部编码有两种：

• ziplist（压缩列表）：当有序集合的元素个数小于 zset-max-ziplist-entries 配置（默认 128 个），同时每个元素的值都小于 zset-max-ziplist-value 配置（默认 64 字节）时，Redis 会⽤ ziplist 来作为有序集合的内部实现，ziplist 可以有效减少内存的使⽤。
• skiplist（跳表）：当 ziplist 条件不满⾜时，有序集合会使⽤ skiplist 作为内部实现，因为此时ziplist 的操作效率会下降。

跳表简单来说是一个“复杂链表”。在跳表中查询元素的时间复杂度是 O(logN)，相比于树形结构更适合按照范围获取元素

1. 当元素个数较少且每个元素较小时，内部编码为 ziplist：

127.0.0.1:6379> zadd zsetkey 50 e1 60 e2 30 e3
(integer) 3
127.0.0.1:6379> object encoding zsetkey
"ziplist"

2. 当元素个数超过 128 个，内部编码 skiplist：

127.0.0.1:6379> zadd zsetkey 50 e1 60 e2 30 e3 ... (省略) ... 82 e129
(integer) 129
127.0.0.1:6379> object encoding zsetkey
"skiplist"

3. 当某个元素⼤于 64 字节时，内部编码 skiplist：

1 127.0.0.1:6379> zadd zsetkey 50 "one string bigger than 64 bytes ... (省略) ..."
2 (integer) 1
3 127.0.0.1:6379> object encoding zsetkey
4 "skiplist"

使⽤场景

有序集合⽐较典型的使⽤场景就是排行榜系统。例如常⻅的⽹站上的热榜信息，榜单的维度可能是多⽅⾯的：按照时间、按照阅读量、按照点赞量（此时可以借助 zinterstore/zunionstore 按照加权方式来处理）。本例中我们使⽤点赞数这个维度，维护每天的热榜：

1. 添加⽤⼾赞数

例如⽤⼾ james 发布了⼀篇⽂章，并获得 3 个赞，可以使⽤有序集合的 zadd 和 zincrby 功能：

zadd user:ranking:2022-03-15 3 james

之后如果再获得赞，可以使⽤ zincrby：

zincrby user:ranking:2022-03-15 1 james

2. 取消⽤⼾赞数

由于各种原因（例如⽤⼾注销、⽤⼾作弊等）需要将⽤⼾删除，此时需要将⽤⼾从榜单中删除掉，可以使⽤ zrem。例如删除成员 tom：

zrem user:ranking:2022-03-15 tom

3. 展⽰获取赞数最多的 10 个⽤⼾

此功能使⽤ zrevrange 命令实现：

zrevrangebyrank user:ranking:2022-03-15 0 9

4. 展⽰⽤⼾信息以及⽤⼾分数

次功能将⽤⼾名作为键后缀，将⽤⼾信息保存在哈希类型中，⾄于⽤⼾的分数和排名可以使⽤ zscore 和 zrank 来实现。

hgetall user:info:tom
zscore user:ranking:2022-03-15 mike
zrank user:ranking:2022-03-15 mike