Redis ZRANGE BYSCORE 的时间窗口分页

如果 ZSET 的 score 存的是事件时间，按时间翻页最容易写成“每次取固定下标”。但时间窗口查询真正要先解决的是边界：这一页的结束时间是否还属于下一页、同一时间戳的多个成员怎么排、offset 很大时是否还能接受。Redis 6.2+ 推荐用 ZRANGE ... BYSCORE 表达这类查询，旧的 ZRANGEBYSCORE 仍能读懂，但已经被官方标记为弃用。

官方地址：https://redis.io/

下面假设 key 为 event:timeline，score 统一使用毫秒时间戳，member 是事件 ID。示例是静态说明，命令需要接入自己的 Redis 环境后再运行。

先把时间窗口写成可判断的分数范围

BYSCORE 会把 start 和 stop 当成分数边界，而不是成员下标。边界默认包含两端；在数字前加 ( 就变成排他边界，-inf 和 +inf 可以表示没有下限或上限。

# score 是毫秒时间戳；这里查询一个闭合的时间窗口
redis-cli ZRANGE event:timeline 1710000000000 1710003600000 BYSCORE WITHSCORES

# 只取大于起点的事件，终点仍然包含在窗口内
redis-cli ZRANGE event:timeline \(1710000000000 1710003600000 BYSCORE WITHSCORES

# 查询从窗口起点到当前所有事件，避免手工猜最大 score
redis-cli ZRANGE event:timeline 1710000000000 +inf BYSCORE WITHSCORES

如果业务仍在使用 ZRANGEBYSCORE key min max，它的时间范围语义相同；新代码可以直接迁移到上面的 ZRANGE key min max BYSCORE 形式，后续再按需要加 LIMIT 或 REV。

固定窗口内分页，先用 LIMIT 验证结果边界

在一个不会频繁变化的时间窗口里，可以把 LIMIT offset count 当成 SQL 的分页参数。第一页从 0 开始，第二页把 offset 向后移动一页大小；WITHSCORES 让客户端同时拿到下一次查询需要的分数信息。

# 第一页：窗口内跳过 0 个匹配成员，取 20 个
redis-cli ZRANGE event:timeline 1710000000000 1710003600000 BYSCORE LIMIT 0 20 WITHSCORES

# 第二页：仍是同一个窗口，跳过前 20 个匹配成员
redis-cli ZRANGE event:timeline 1710000000000 1710003600000 BYSCORE LIMIT 20 20 WITHSCORES

# count 为负数会从 offset 取到窗口末尾；列表很大时不要随意使用
redis-cli ZRANGE event:timeline 1710000000000 1710003600000 BYSCORE LIMIT 40 -1

这种写法适合导出、回放或短时间内数据不变的窗口。官方文档特别提醒，大 offset 仍要先遍历被跳过的成员，成本可能接近 O(N)；所以不要把深页 offset 当成长列表的默认接口。

实时翻页改用排他下界的时间游标

如果窗口持续有新事件写入，offset 分页会受到插入影响：第一页返回后，窗口前部新增成员，第二页的 offset 可能再次读到旧成员。更稳妥的方式是把上一页最后一个分数记作游标，下一页把它写成排他下界，并从 0 开始取。

# 假设上一页最后一个 score 是 1710001200456；括号排除它
# 这样不会把上一页的最后一个成员再次作为下一页首项
redis-cli ZRANGE event:timeline \(1710001200456 1710003600000 BYSCORE LIMIT 0 20 WITHSCORES

# 下一页只保留相同的窗口上界，游标来自上一页的最后一条记录
redis-cli ZRANGE event:timeline \(LAST_SCORE WINDOW_END BYSCORE LIMIT 0 PAGE_SIZE WITHSCORES

这里有一个不能忽略的边界：多个 member 可能拥有同一个 score。仅保存 last_score 时，如果一页在同分数成员中间结束，下一页用 (last_score 会把这个分数剩下的成员全部排除，形成遗漏。

因此，时间游标接口应让 score 在业务上足够细，并在同一时间戳下保留可排序的序号；或者把“同分数已消费到哪个位置”作为游标的一部分，在同分数段继续用窗口内 offset。关键是不要把“时间相同”误当成“成员唯一”。

倒序读取时，分数边界也要反过来

如果产品要从最新事件向旧事件翻页，可以加 REV。使用 REV BYSCORE 时，第一个分数参数是高边界，第二个是低边界；把正序的参数顺序原样复制过去，会得到空结果或错误的范围。

# 倒序读取：从窗口结束时间向窗口开始时间返回 20 个成员
redis-cli ZRANGE event:timeline 1710003600000 1710000000000 REV BYSCORE LIMIT 0 20 WITHSCORES

# 排除上一页的最高 score，避免倒序分页再次返回边界成员
redis-cli ZRANGE event:timeline \(LAST_SCORE 1710000000000 REV BYSCORE LIMIT 0 20 WITHSCORES

可以用下面这张小表快速检查参数：

最后可以把判断收敛成三句话：窗口稳定、数据量不大时用 LIMIT offset count；实时追加的数据优先用排他时间游标；同一 score 可能承载多条记录时，必须额外设计序号或同分数位置，否则分页仍可能遗漏。

相关问题

ZRANGE BYSCORE 和旧的 ZRANGEBYSCORE 有什么关系？

Redis 6.2+ 的 ZRANGE ... BYSCORE 是统一写法，旧命令在官方文档中标记为弃用。两者都按 score 范围取成员，新代码优先使用前者。

为什么用时间游标后还会漏数据？

最常见原因是同一时间戳对应多个成员，而游标只保存了 score。排他下界会跳过同 score 的剩余成员，需要让 score 带业务序号，或记录同分数段的消费位置。