Redis命令：LPOS

Redis LPOS 命令详细教程LPOS用于在列表中查找与给定值匹配的元素并返回其索引位置。它支持从表头或表尾开始查找、指定从第几个匹配开始、一次返回多个匹配位置以及限制比较的元素数量是“按值定位”列表元素的只读命令。它从 Redis 6.0.6 起提供在此之前只能用 LRANGE 自己遍历实现。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、概览与语法LPOS key element [RANK rank] [COUNT num-matches] [MAXLEN len]项目说明数据类型List支持版本Redis 6.0.6 起key目标列表 Keyelement要查找的元素按字节精确匹配允许空字符串RANK rank从第几个匹配开始返回1 表示第一个匹配负数表示从表尾倒数-1 为最后一个匹配COUNT num-matches一次返回多个匹配位置0 表示返回全部匹配MAXLEN len最多比较的元素数量0 表示不限制返回值单结果模式返回匹配元素的 0 基索引无匹配返回空值带 COUNT 时返回索引数组无匹配返回空数组时间复杂度O(N)N 为需要比较的元素数受 MAXLEN 影响ACLread、list、fast命令标记readonly、fast官方说明LPOS 报告列表中匹配元素的索引默认从列表表头开始扫描并返回第一个匹配返回的索引始终以表头为 0 基准即使从表尾方向查找也一样。$TRAE_REF二、基础示例以下命令在测试实例的 redis-cli 中执行。文中结果是预期说明未实际连接 Redis 运行。示例沿用官方文档的数据与结果。DEL tutorial:{lpos}:mylist RPUSH tutorial:{lpos}:mylist a b c 1 2 3 c c LPOS tutorial:{lpos}:mylist c预期结果RPUSH 返回8LPOS 返回(integer) 2即第一个c的索引。列表索引从表头以 0 开始计数a是 0、b是 1、c是 2。注意 LPOS 只查找不修改执行后列表内容与长度不变与 LREM 的“查找并删除”不同。三、RANK 参数从第几个匹配开始列表中c出现了 3 次索引 2、6、7。RANK 用于指定以第几个匹配为返回目标LPOS tutorial:{lpos}:mylist c RANK -1 LPOS tutorial:{lpos}:mylist c RANK 2 LPOS tutorial:{lpos}:mylist c RANK 100预期结果RANK -1从表尾倒数返回最后一个匹配(integer) 7RANK 2返回第二个匹配(integer) 6RANK 100超出实际匹配次数返回空值。RANK 为 0 是无效值报错ERR RANK cant be zero. Use 1 to start searching from the first matching element in the head and negative ranks to start searching from the tail。四、COUNT 参数批量返回匹配COUNT 把单个索引变为索引数组返回从起点开始的前 N 个匹配LPOS tutorial:{lpos}:mylist c COUNT 2 LPOS tutorial:{lpos}:mylist c RANK -1 COUNT 2 LPOS tutorial:{lpos}:mylist c COUNT 0 LPOS tutorial:{lpos}:mylist c RANK 2 COUNT 3预期结果COUNT 2返回[2, 6]RANK -1 COUNT 2从最后一个匹配开始继续向表头方向收集返回[7, 6]COUNT 0返回全部匹配[2, 6, 7]RANK 2 COUNT 3从第二个匹配开始要 3 个但只剩 2 个返回[6, 7]。要点COUNT 模式下的顺序与搜索方向一致负 RANK 时索引是倒序给出的COUNT 0 表示“不限数量”而不是“返回 0 个”。五、MAXLEN 参数限制比较范围MAXLEN 限制最多比较多少个元素防止在大列表上全量扫描LPOS tutorial:{lpos}:mylist c COUNT 0 MAXLEN 3 LPOS tutorial:{lpos}:mylist c RANK -1 COUNT 0 MAXLEN 3预期结果第一条只比较表头前 3 个元素a,b,c在索引 2 命中后停止返回[2]第二条从表尾方向比较 3 个元素c,c,3命中索引 7 和 6 后到达比较上限返回[7, 6]。MAXLEN 计的是“比较次数”而不是“返回的匹配数”负 RANK 时从表尾倒数比较。MAXLEN 0 表示不限制。六、返回值与空结果的两种形态调用模式有匹配无匹配不带 COUNT返回整数索引返回空值nil带 COUNT返回索引数组返回空数组LPOS tutorial:{lpos}:mylist no-such LPOS tutorial:{lpos}:mylist no-such COUNT 0 LPOS tutorial:{lpos}:mylist no-such RANK 5预期结果第一条返回(nil)第二条返回空数组(empty list or set)第三条在单结果模式下 RANK 超出匹配次数同样返回(nil)。客户端代码必须区分这两种形态判断“元素是否存在”适合用单结果模式判断 nil收集全部位置适合用 COUNT 模式判断空数组。七、边界情况与错误处理场景行为Key 不存在视为空列表返回空值或 COUNT 模式下的空数组Key 类型不是 List报 WRONGTYPEelement 为空字符串允许可与列表中的空字符串元素匹配RANK 为 0报错ERR RANK cant be zero...COUNT 为负数报错ERR COUNT cant be negativeMAXLEN 为负数报错ERR MAXLEN cant be negative参数选项拼写错误报ERR syntax errorRedis 版本低于 6.0.6报 unknown command 错误SET tutorial:{lpos}:str text LPOS tutorial:{lpos}:str a LPOS tutorial:{lpos}:mylist c RANK 0预期结果第一条在 String 类型上报 WRONGTYPE第二条报 RANK 为 0 的错误。八、与相近命令的区别命令方向是否修改列表说明LPOS按值查找返回索引否6.0.6 起支持LINDEX按索引取元素否与 LPOS 互为反向一个按值找位置一个按位置取值LINSERT按值定位插入是1需要 pivot 已存在LSET按索引覆盖元素否长度不变常与 LPOS 组合实现“查找并替换”LREM按值删除是-N可删除前 N 个匹配无位置信息返回组合用法LPOS key target拿到索引后LSET key index new_value即为精确替换带 COUNT 的 LPOS 可先确认重复元素的全部位置再逐个处理。LREM 只能按值从前/后删除指定数量拿不到索引。九、客户端示例前提为已安装 redis-py 并准备好本地测试实例。redis-py 的lpos签名为lpos(name, value, rankNone, countNone, maxlenNone)单结果返回 int 或 None带 count 返回列表。importredis rredis.Redis(hostlocalhost,port6379,decode_responsesTrue)keytutorial:{lpos}:pytry:r.delete(key)r.rpush(key,a,b,c,1,2,3,c,c)print(r.lpos(key,c))# 2print(r.lpos(key,c,rank-1))# 7print(r.lpos(key,c,count0))# [2, 6, 7]print(r.lpos(key,c,rank2,count3))# [6, 7]print(r.lpos(key,c,count0,maxlen3))# [2]print(r.lpos(key,no-such))# Noneprint(r.lpos(key,no-such,count0))# []finally:r.delete(key)r.close()JavaJedis示例选项参数使用redis.clients.jedis.params.LPosParamsimportredis.clients.jedis.params.LPosParams;try(JedisjedisnewJedis(localhost,6379)){Stringkeytutorial:{lpos}:java;jedis.del(key);jedis.rpush(key,a,b,c,1,2,3,c,c);System.out.println(jedis.lpos(key,c));// 2System.out.println(jedis.lpos(key,c,newLPosParams().rank(-1)));// 7System.out.println(jedis.lpos(key,c,newLPosParams().rank(2),3));// [6, 7]jedis.del(key);}十、原子性与性能注意事项只读与原子性LPOS 是只读命令不修改列表可在副本节点执行分担读压力单命令原子执行结果反映某一时刻的列表状态。慢命令风险无 MAXLEN 时最坏情况要比较整个列表O(N)Redis 处理命令是单线程的在百万级元素列表上做COUNT 0会阻塞其他命令属于典型慢命令。大列表上应尽量指定 MAXLEN 或缩小查找范围并通过 SLOWLOG 观测。事务与 PipelineLPOS 可在 MULTI/EXEC 和 Lua 脚本中正常使用“LPOS 查位置 LSET 修改”两条命令不是原子的并发修改同一列表时需要用 WATCH 或 Lua 脚本包裹。集群LPOS 只涉及单个 Key在 Redis Cluster 中没有跨槽限制。十一、典型业务场景查找并精确替换有序配置列表、轮播位等场景中先用LPOS key old_value定位再用 LSET 覆盖比重建整个列表更轻量。重复元素巡检用COUNT 0查出某元素的全部出现位置评估是否需要去重再配合 LREM 或 LSET 清理。调试与观测开发期快速确认元素是否在列表中、位于第几位辅助排查 LPUSH/RPUSH 的顺序问题。限流查找只想确认“最近 N 个元素里有没有它”时用MAXLEN控制比较量把开销从 O(N) 降到 O(N_prefix)。十二、练习、排错与总结练习新建tutorial:{lpos}:ex用 RPUSH 写入a b a a执行LPOS ex a确认返回0LPOS ex a RANK -1返回3LPOS ex a COUNT 0返回[0, 2, 3]LPOS ex a COUNT 0 MAXLEN 2返回[0]LPOS ex nosuch返回空值COUNT 0模式返回空数组。排错要点返回空值或空数组时先确认元素值是否与写入时大小写、空格完全一致精确字节匹配报 unknown command 时检查 Redis 版本是否低于 6.0.6报 RANK/COUNT/MAXLEN 相关错误时检查参数取值RANK 非 0、COUNT 与 MAXLEN 非负慢日志出现 LPOS 时加 MAXLEN 或改用其他结构。清理使用DEL tutorial:{lpos}:mylist tutorial:{lpos}:str tutorial:{lpos}:py tutorial:{lpos}:java tutorial:{lpos}:ex。速记6.0.6 起支持、按值查找返回 0 基索引、RANK 指定第几个匹配且负数从表尾倒数、COUNT 批量返回且 0 为全部、MAXLEN 限制比较元素数、单结果无匹配返回空值而 COUNT 模式返回空数组、只读不修改列表、大列表务必防全量扫描。