Redis HPERSIST 命令详细教程HPERSIST移除 Hash 中一个或多个字段的过期时间把字段从“易失”变为“永久”。它从 Redis 7.4.0 起提供只读不写数据本身只改动过期元数据。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、概览与语法HPERSIST key FIELDS numfields field [field ...]项目说明数据类型Hash 的字段级过期时间支持版本Redis 7.4.0 起key一个 Hash KeyFIELDS必填关键字不可省略numfields字段数量必须与后续字段参数个数一致field至少一个字段名不支持通配符返回值数组元素顺序与输入字段一致时间复杂度O(N)N 为指定字段数量ACLwrite、hash、fast命令标记write、fast命令描述中给出了术语定义带有过期时间的字段称为 volatile易失移除后成为 persistent永久不再关联 TTL。$TRAE_REF二、逐字段返回值数值含义-2该字段不存在或整个 Key 不存在-1该字段存在但本来就没有过期时间1成功移除了该字段的过期时间即使只指定一个字段也返回数组不能当成单个整数处理。-1与-2的区别很关键前者表示字段存在且已是永久状态操作无效果但数据正常后者表示字段根本不存在。$TRAE_REF三、基础示例以下命令需要 Redis 7.4 或更新版本在测试实例的 redis-cli 中执行。文中结果是预期说明未实际连接 Redis 运行。DEL tutorial:{hpersist}:profile HSET tutorial:{hpersist}:profile name Alice temp draft HEXPIRE tutorial:{hpersist}:profile 300 FIELDS 2 name temp HTTL tutorial:{hpersist}:profile FIELDS 2 name temp HPERSIST tutorial:{hpersist}:profile FIELDS 1 temp HTTL tutorial:{hpersist}:profile FIELDS 2 name temp HPERSIST tutorial:{hpersist}:profile FIELDS 2 name absent预期结果HEXPIRE 返回[1, 1]第一次 HTTL 返回两个递减的正数HPERSIST 对 temp 返回[1]第二次 HTTL 中 temp 变为-1name 仍为正数最后一次 HPERSIST 返回[1, -2]name 被成功转为永久absent 因不存在返回 -2。四、字段 TTL 与 Key TTL 的区别这是最容易混淆的地方。HPERSIST 只作用于字段级过期时间不影响整个 Key 的过期时间。操作对象设置命令查询命令移除命令Hash 字段HEXPIRE、HPEXPIRE、HEXPIREAT、HPEXPIREATHTTL、HPTTL、HEXPIRETIME、HPEXPIRETIMEHPERSIST整个 KeyEXPIRE、PEXPIRE、EXPIREAT、PEXPIREATTTL、PTTL、EXPIRETIME、PEXPIRETIMEPERSISTDEL tutorial:{hpersist}:two HSET tutorial:{hpersist}:two a 1 EXPIRE tutorial:{hpersist}:two 600 HEXPIRE tutorial:{hpersist}:two 300 FIELDS 1 a TTL tutorial:{hpersist}:two HTTL tutorial:{hpersist}:two FIELDS 1 a HPERSIST tutorial:{hpersist}:two FIELDS 1 a TTL tutorial:{hpersist}:two HTTL tutorial:{hpersist}:two FIELDS 1 a预期结果TTL 约为 600HTTL 约为 300两者独立存在HPERSIST 后 HTTL 变为-1但 TTL 仍约为 600说明 Key 级过期时间未受影响。要让整个 Key 永久有效应使用 PERSIST。五、边界情况与错误处理场景行为Key 不存在按输入字段数返回多个 -2字段不存在该项返回 -2字段存在但无 TTL该项返回 -1属于“无需操作”而非失败字段有 TTL该项返回 1TTL 被移除值保持不变Key 是 String、List 等非 Hash报 WRONGTYPE 错误numfields 与实际字段数不符报语法错误未写 FIELDS 关键字报语法错误HPERSIST 不会改变字段的值也不会改变 Key 的 TTL。若字段已经到期它的表现与不存在一致返回 -2无法“复活”已删除的数据。六、客户端示例前提为已安装 redis-py 且服务端为 Redis 7.4 或更新版本。使用通用接口显式展示 FIELDS 语法。importredis rredis.Redis(hostlocalhost,port6379,decode_responsesTrue)ktutorial:{hpersist}:pythontry:r.delete(k)r.hset(k,mapping{a:A,b:B})r.execute_command(HEXPIRE,k,300,FIELDS,2,a,b)fields[a,absent]resultr.execute_command(HPERSIST,k,FIELDS,len(fields),*fields)print(result)# [1, -2]forname,valueinzip(fields,result):ifvalue1:print(name,已转为永久)elifvalue-1:print(name,本来就是永久)else:print(name,不存在)print(r.execute_command(HTTL,k,FIELDS,2,a,b))# [-1, 约300]finally:r.delete(k)r.close()七、并发、原子性与适用场景HPERSIST 对多个字段原子执行但“先 HTTL 判断再 HPERSIST”是跨命令流程中间可能有其他客户端重新设置 TTL 或删除字段。需要严格条件操作时应使用脚本或事务设计。典型场景把原本设了短 TTL 的字段在满足某条件后转为长期有效例如支付完成后把订单缓存字段转永久、修正误设的过期时间、在数据迁移前冻结字段生命周期。需要注意的是转为永久意味着该字段将一直占用内存直到被显式删除或整个 Key 消失把大量字段转为永久会削弱缓存自动清理的效果应配合容量规划。八、练习、排错与总结练习新建tutorial:{hpersist}:exercise写入 a1、b2用HEXPIRE ... 300 FIELDS 2 a b设置字段 TTL执行HPERSIST ... FIELDS 2 a absent预期返回[1, -2]用 HTTL 确认 a 为 -1、b 仍为正数最后执行PERSIST观察 Key 级 TTL 的变化理解两级过期的独立性。排错要点返回 -1 表示字段本来就永久不是失败返回 -2 表示字段或 Key 不存在可用 HEXISTS 与 EXISTS 区分unknown command 时确认服务端版本不低于 7.4HTTL 仍有数值说明命令未作用到该字段检查字段名拼写与 numfields 是否匹配。清理使用DEL tutorial:{hpersist}:profile tutorial:{hpersist}:two tutorial:{hpersist}:exercise。速记7.4 起支持、移除字段 TTL 而非 Key TTL、返回 -2/-1/1、不改变字段值、大量转永久需评估内存。 
长河君 · 2026/10/2 15:22:45 · 阅读 1.2k Redis命令：HPERSIST
Redis HPERSIST 命令详细教程HPERSIST移除 Hash 中一个或多个字段的过期时间把字段从“易失”变为“永久”。它从 Redis 7.4.0 起提供只读不写数据本身只改动过期元数据。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、概览与语法HPERSIST key FIELDS numfields field [field ...]项目说明数据类型Hash 的字段级过期时间支持版本Redis 7.4.0 起key一个 Hash KeyFIELDS必填关键字不可省略numfields字段数量必须与后续字段参数个数一致field至少一个字段名不支持通配符返回值数组元素顺序与输入字段一致时间复杂度O(N)N 为指定字段数量ACLwrite、hash、fast命令标记write、fast命令描述中给出了术语定义带有过期时间的字段称为 volatile易失移除后成为 persistent永久不再关联 TTL。$TRAE_REF二、逐字段返回值数值含义-2该字段不存在或整个 Key 不存在-1该字段存在但本来就没有过期时间1成功移除了该字段的过期时间即使只指定一个字段也返回数组不能当成单个整数处理。-1与-2的区别很关键前者表示字段存在且已是永久状态操作无效果但数据正常后者表示字段根本不存在。$TRAE_REF三、基础示例以下命令需要 Redis 7.4 或更新版本在测试实例的 redis-cli 中执行。文中结果是预期说明未实际连接 Redis 运行。DEL tutorial:{hpersist}:profile HSET tutorial:{hpersist}:profile name Alice temp draft HEXPIRE tutorial:{hpersist}:profile 300 FIELDS 2 name temp HTTL tutorial:{hpersist}:profile FIELDS 2 name temp HPERSIST tutorial:{hpersist}:profile FIELDS 1 temp HTTL tutorial:{hpersist}:profile FIELDS 2 name temp HPERSIST tutorial:{hpersist}:profile FIELDS 2 name absent预期结果HEXPIRE 返回[1, 1]第一次 HTTL 返回两个递减的正数HPERSIST 对 temp 返回[1]第二次 HTTL 中 temp 变为-1name 仍为正数最后一次 HPERSIST 返回[1, -2]name 被成功转为永久absent 因不存在返回 -2。四、字段 TTL 与 Key TTL 的区别这是最容易混淆的地方。HPERSIST 只作用于字段级过期时间不影响整个 Key 的过期时间。操作对象设置命令查询命令移除命令Hash 字段HEXPIRE、HPEXPIRE、HEXPIREAT、HPEXPIREATHTTL、HPTTL、HEXPIRETIME、HPEXPIRETIMEHPERSIST整个 KeyEXPIRE、PEXPIRE、EXPIREAT、PEXPIREATTTL、PTTL、EXPIRETIME、PEXPIRETIMEPERSISTDEL tutorial:{hpersist}:two HSET tutorial:{hpersist}:two a 1 EXPIRE tutorial:{hpersist}:two 600 HEXPIRE tutorial:{hpersist}:two 300 FIELDS 1 a TTL tutorial:{hpersist}:two HTTL tutorial:{hpersist}:two FIELDS 1 a HPERSIST tutorial:{hpersist}:two FIELDS 1 a TTL tutorial:{hpersist}:two HTTL tutorial:{hpersist}:two FIELDS 1 a预期结果TTL 约为 600HTTL 约为 300两者独立存在HPERSIST 后 HTTL 变为-1但 TTL 仍约为 600说明 Key 级过期时间未受影响。要让整个 Key 永久有效应使用 PERSIST。五、边界情况与错误处理场景行为Key 不存在按输入字段数返回多个 -2字段不存在该项返回 -2字段存在但无 TTL该项返回 -1属于“无需操作”而非失败字段有 TTL该项返回 1TTL 被移除值保持不变Key 是 String、List 等非 Hash报 WRONGTYPE 错误numfields 与实际字段数不符报语法错误未写 FIELDS 关键字报语法错误HPERSIST 不会改变字段的值也不会改变 Key 的 TTL。若字段已经到期它的表现与不存在一致返回 -2无法“复活”已删除的数据。六、客户端示例前提为已安装 redis-py 且服务端为 Redis 7.4 或更新版本。使用通用接口显式展示 FIELDS 语法。importredis rredis.Redis(hostlocalhost,port6379,decode_responsesTrue)ktutorial:{hpersist}:pythontry:r.delete(k)r.hset(k,mapping{a:A,b:B})r.execute_command(HEXPIRE,k,300,FIELDS,2,a,b)fields[a,absent]resultr.execute_command(HPERSIST,k,FIELDS,len(fields),*fields)print(result)# [1, -2]forname,valueinzip(fields,result):ifvalue1:print(name,已转为永久)elifvalue-1:print(name,本来就是永久)else:print(name,不存在)print(r.execute_command(HTTL,k,FIELDS,2,a,b))# [-1, 约300]finally:r.delete(k)r.close()七、并发、原子性与适用场景HPERSIST 对多个字段原子执行但“先 HTTL 判断再 HPERSIST”是跨命令流程中间可能有其他客户端重新设置 TTL 或删除字段。需要严格条件操作时应使用脚本或事务设计。典型场景把原本设了短 TTL 的字段在满足某条件后转为长期有效例如支付完成后把订单缓存字段转永久、修正误设的过期时间、在数据迁移前冻结字段生命周期。需要注意的是转为永久意味着该字段将一直占用内存直到被显式删除或整个 Key 消失把大量字段转为永久会削弱缓存自动清理的效果应配合容量规划。八、练习、排错与总结练习新建tutorial:{hpersist}:exercise写入 a1、b2用HEXPIRE ... 300 FIELDS 2 a b设置字段 TTL执行HPERSIST ... FIELDS 2 a absent预期返回[1, -2]用 HTTL 确认 a 为 -1、b 仍为正数最后执行PERSIST观察 Key 级 TTL 的变化理解两级过期的独立性。排错要点返回 -1 表示字段本来就永久不是失败返回 -2 表示字段或 Key 不存在可用 HEXISTS 与 EXISTS 区分unknown command 时确认服务端版本不低于 7.4HTTL 仍有数值说明命令未作用到该字段检查字段名拼写与 numfields 是否匹配。清理使用DEL tutorial:{hpersist}:profile tutorial:{hpersist}:two tutorial:{hpersist}:exercise。速记7.4 起支持、移除字段 TTL 而非 Key TTL、返回 -2/-1/1、不改变字段值、大量转永久需评估内存。