RedisJSON 技术揭秘`JSON.CLEAR` 一键清空容器、重置数字的“软删除”-EW帮帮网

一、指令速查

JSON.CLEAR <key> [path]

参数	说明
`key`	Redis 键名
`path`	JSONPath（可选，缺省 `$` 根；支持 `*`、`..` 多路径）

返回值：整数——被清空的数组 / 对象数量 + 被置零的数值字段数量。已为空或为 0 的字段不会重复统计。

时间复杂度

单路径 → O(N)，N 为被清空容器的元素个数
多路径 → O(N × 匹配数)

二、行为要点

数组 / 对象 → 空容器：[] 或 {}
数值 → 0：int、float 皆置为 0
字符串 / 布尔 / null：保持原值
路径不存在：安静忽略，不报错

与 JSON.DEL 区别

场景	`CLEAR`	`DEL`
JSON 结构	保留字段	删除字段
数值	置 0	删除
引用路径不存在	忽略	忽略
典型用途	重置 / Soft-Delete	硬删除

三、CLI 实战

3.1 创建示例文档

JSON.SET doc $ '{
  "obj": {"a":1,"b":2},
  "arr": [1,2,3],
  "str": "foo",
  "bool": true,
  "int": 42,
  "float": 3.14
}'

3.2 清空所有一级容器 & 数字

redis> JSON.CLEAR doc $.*
(integer) 4   # obj + arr + int + float

3.3 查看结果

redis> JSON.GET doc $
[{
  "obj":{},
  "arr":[],
  "str":"foo",
  "bool":true,
  "int":0,
  "float":0
}]

四、精选应用场景

场景	玩法
每日统计归零	定时 `CLEAR stats $.counters.*`
多租户初始化	复制模板 JSON 后立即 `CLEAR tenant:xxx $.data`
循环缓存	写前先 `CLEAR` 再 append，避免残留旧元素
软删除字段	接口要求字段仍存在，可 `CLEAR` 容器并保留键

五、跨语言速用

5.1 Python（redis-py ≥ 5.0）

from redis import Redis
r = Redis(decode_responses=True)

affected = r.execute_command("JSON.CLEAR", "doc", "$.obj")
print("清空字段数:", affected)  # 1

5.2 Node.js（@redis/client）

import { createClient } from 'redis';
const cli = createClient(); await cli.connect();

const affected = await cli.json.clear('doc', '$.arr');
console.log(affected); // 1

5.3 Go（go-redis/v9）

affected, _ := rdb.Do(ctx, "JSON.CLEAR", "doc", "$.int").Int()
log.Println(affected)  // 1

六、常见陷阱 & 性能提示

问题	排查要点
清空后仍占内存	容器本身仍在，巨大嵌套保持层级。若需彻底删除请用 `JSON.DEL`
想让字符串变空	`CLEAR` 不会置空字符串；需显式 `JSON.SET`
大型数组 O(N)	每次清空都会遍历元素；可考虑直接 `DEL` 再 `SET` 新空数组以节省 CPU
多路径忽略 nil	路径写错无错误提示，务必 `JSON.TYPE` 或 `EXISTS` 验证

七、最佳实践

定时任务批量清
对统计量、滑动窗口定期统一 JSON.CLEAR，避免写时阻塞。
事务 / Lua
若需要清空后立即写入默认值，用 MULTI/EXEC 或 Lua 保证原子顺序。
搭配 ARRTRIM
先 ARRTRIM 留窗口，再 CLEAR 子对象，实现分层管控。
监控返回值
通过返回的受影响字段数判断重置是否生效，写 Prometheus 指标告警。

八、总结

JSON.CLEAR 为 RedisJSON 家族补上“软删除 / 快速归零”能力，与之前介绍的“增、查、删、量、弹、裁”六神技形成完美闭环：

增/改：ARRAPPEND / ARRINSERT / SET
查：ARRINDEX / GET / TYPE
删：ARRPOP / DEL
量：ARRLEN
裁：ARRTRIM
清零：CLEAR

通过恰当地组合，你可以应对几乎所有 JSON 数据结构的生命周期管理场景。至此，RedisJSON 系列全部完结，愿你在高并发、高可维护的系统设计中灵活运用，码力倍增！🎉

RedisJSON 技术揭秘`JSON.CLEAR` 一键清空容器、重置数字的“软删除”