Redis Stream（消息流） · 2. 命令速查与示例

返回分篇目录

本文按 Redis 8.2.10 核对编码与配置默认值；命令的引入版本另行标注。生产配置可能不同，可通过 CONFIG GET 查询。示例面向独立实验服务，运行结果和内存数字未在本次实测。

2. 命令速查与示例

按用途分组，共 27 项，覆盖 Redis 8.2.10 的本类型命令及子命令。点击命令名查看官方参数。示例在 redis-cli 中逐行输入，每次换例子前重置下面的教学数据。

准备与重置示例数据

在独立实验实例的 redis-cli 交互模式逐行输入，避免 shell 对引号、>、*、括号等符号进行解释。每个例子独立使用；换例子前重新执行下面的准备段，否则删除、弹出、过期和修改操作会影响后续结果。准备段仅重置列出的教学键，确认这些键不承载业务数据。

UNLINK learn:{stream}:events
XADD learn:{stream}:events 1-0 action login uid 42
XADD learn:{stream}:events 2-0 action score uid 42
XADD learn:{stream}:events 3-0 action logout uid 42
XGROUP CREATE learn:{stream}:events readers 0
XREADGROUP GROUP readers alice COUNT 2 STREAMS learn:{stream}:events >

示例的返回说明以刚完成准备段为前提，随机结果与剩余 TTL 不固定。带同一 {...} 的教学键便于在 Cluster 中满足相关多键操作的同槽要求。

写入、读取与裁剪

命令与用途	示例与结果	复杂度
XADD 追加事件	XADD learn:{stream}:events * action score uid 42 返回新 ID，具体值随执行时刻变化。	追加 O(1) 裁剪 O(R)
XLEN 流的条目数	XLEN learn:{stream}:events 准备数据中有 3 条，返回 3。	O(1)
XRANGE 正序读取区间	XRANGE learn:{stream}:events - + COUNT 2 返回 1-0、2-0 两条。	O(M)
XREVRANGE 倒序读取区间	XREVRANGE learn:{stream}:events + - COUNT 2 返回 3-0、2-0。	O(M)
XREAD 按游标读取	XREAD COUNT 2 STREAMS learn:{stream}:events 0-0 返回前两条；BLOCK 等待时使用有限超时。	随流数、返回量变化
XDEL 删除指定条目	XDEL learn:{stream}:events 3-0 返回 1；旧待确认引用可能仍需处理。	每个指定 ID O(1)
XDELEX 按引用策略删除	XDELEX learn:{stream}:events DELREF IDS 1 2-0 8.2 起可用；DELREF 删除正文及引用，不能当作处理成功确认。	每个指定 ID O(1)
XTRIM 裁剪历史	XTRIM learn:{stream}:events MAXLEN = 2 精确保留 2 条；裁剪和待确认记录需配合保留策略。	O(R)

消费与确认

命令与用途	示例与结果	复杂度
XREADGROUP 消费组读取新消息	XREADGROUP GROUP readers bob COUNT 1 STREAMS learn:{stream}:events > 前两条已由 alice 领取，bob 得到 3-0。	每条流 O(M)
XPENDING 查看待确认记录	XPENDING learn:{stream}:events readers - + 10 准备数据中包含 alice 的 1-0、2-0。	随返回/扫描量变化
XACK 确认处理完成	XACK learn:{stream}:events readers 1-0 确认数为 1，不删除正文。	每个指定 ID O(1)
XACKDEL 确认并按策略删除	XACKDEL learn:{stream}:events readers DELREF IDS 1 1-0 8.2 起可用；同时删除相关引用，必须在业务成功后使用。	每个指定 ID O(1)
XCLAIM 指定 ID 接管	XCLAIM learn:{stream}:events readers bob 0 2-0 演示立即接管 alice 的待处理消息；生产应设置合理空闲阈值。	O(log P)
XAUTOCLAIM 游标接管超时消息	XAUTOCLAIM learn:{stream}:events readers bob 0 0-0 COUNT 10 返回继续游标和接管条目；0 空闲阈值仅为演示。	小 COUNT 时 O(1)

消费组子命令

命令与用途	示例与结果	复杂度
XGROUP 消费组命令入口	XGROUP HELP 必须指定子命令，本例列出可用操作。	取决于子命令
XGROUP CREATE 创建消费组	XGROUP CREATE learn:{stream}:events audit 0 创建另一个 audit 组，从历史起点开始。	O(1)
XGROUP CREATECONSUMER 创建消费者	XGROUP CREATECONSUMER learn:{stream}:events readers bob 首次创建返回 1。	O(1)
XGROUP DELCONSUMER 移除消费者	XGROUP DELCONSUMER learn:{stream}:events readers alice 移除 alice 及其待处理记录；先处理未完成消息，不用于正常确认。	O(1)
XGROUP DESTROY 销毁消费组	XGROUP DESTROY learn:{stream}:events readers 删除组和其待确认状态，正文仍保留。	O(P)
XGROUP SETID 调整消费组游标	XGROUP SETID learn:{stream}:events readers 0 只修改投递游标，可能重读历史，不自动清空 PEL。	O(1)
XGROUP HELP 查看消费组帮助	XGROUP HELP 返回子命令用法。	O(1)

信息查询与内部管理

命令与用途	示例与结果	复杂度
XINFO 流信息命令入口	XINFO HELP 必须指定子命令。	取决于子命令
XINFO STREAM 流概要	XINFO STREAM learn:{stream}:events 显示长度、首尾条目等信息。	普通概要 O(1)
XINFO GROUPS 消费组状态	XINFO GROUPS learn:{stream}:events 显示 readers 等组的信息。	O(G)
XINFO CONSUMERS 消费者状态	XINFO CONSUMERS learn:{stream}:events readers 显示 alice 的待处理和空闲情况。	O(C)
XINFO HELP 查看信息命令帮助	XINFO HELP 返回子命令用法。	O(1)
XSETID 设置流的内部末尾 ID	XSETID learn:{stream}:events 10-0 内部管理用途，通常由复制/恢复流程使用；不要用于普通事件生产。	O(1)

版本与复杂度补充

下表保留每条命令的引入版本、兼容状态及复杂度符号含义；复杂度不包含全部网络传输、内存分配和等待成本。

命令	引入版本与状态	复杂度说明
XADD	5.0.0	普通追加 O(1)，附带裁剪另计 O(R)；唤醒阻塞读者也有额外工作。
XLEN	5.0.0	O(1)。大值复制、扩容、网络输出和等待时间需另外考虑。
XRANGE	5.0.0	O(M)，M 为返回条目数；固定 COUNT 时可看作常数上界。
XREVRANGE	5.0.0	O(M)，M 为返回条目数；固定 COUNT 时可看作常数上界。
XREAD	5.0.0	8.2.10 定义未单列复杂度；实际工作随流数和返回条目数变化，等待时间另计。
XDEL	5.0.0	每个指定 ID O(1)，K 个 ID 为 O(K)。
XDELEX	8.2.0	每个指定 ID O(1)，K 个 ID 为 O(K)。
XTRIM	5.0.0	O(R)，R 为实际移除元素数。
XREADGROUP	5.0.0	每条流 O(M)，M 为返回消息数；服务被唤醒的阻塞读者会增加生产者工作。
XPENDING	5.0.0	明细随返回数变化；IDLE 过滤还随扫描数变化；摘要受消费者数量影响。
XACK	5.0.0	每个指定 ID O(1)，K 个 ID 为 O(K)。
XACKDEL	8.2.0	每个指定 ID O(1)，K 个 ID 为 O(K)。
XCLAIM	5.0.0	O(log P)，P 为消费组待处理条目数；批量 ID 增加工作量。
XAUTOCLAIM	6.2.0	小 COUNT 时 O(1)；一次扫描工作受 COUNT 限制，需用游标继续。
XGROUP	5.0.0	取决于所调用的子命令，入口本身不能独立执行。
XGROUP CREATE	5.0.0	O(1)。大值复制、扩容、网络输出和等待时间需另外考虑。
XGROUP CREATECONSUMER	6.2.0	O(1)。大值复制、扩容、网络输出和等待时间需另外考虑。
XGROUP DELCONSUMER	5.0.0	官方命令定义标为 O(1)；移除消费者时仍需处理其未完成消息的业务影响。
XGROUP DESTROY	5.0.0	O(P)，P 为该消费组待处理条目数。
XGROUP SETID	5.0.0	O(1)。大值复制、扩容、网络输出和等待时间需另外考虑。
XGROUP HELP	5.0.0	O(1)。
XINFO	5.0.0	取决于所调用的子命令，入口本身不能独立执行。
XINFO STREAM	5.0.0	普通概要 O(1)；FULL 模式随展示的流、组和待处理数据量增长。
XINFO GROUPS	5.0.0	O(G)，G 为消费组数量。
XINFO CONSUMERS	5.0.0	O(C)，C 为组内消费者数量。
XINFO HELP	5.0.0	O(1)。
XSETID	5.0.0	O(1)。大值复制、扩容、网络输出和等待时间需另外考虑。

通用键操作见键与过期时间，这里集中列出类型自身的命令。