一、指令速查

JSON.CLEAR <key> [path]

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

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

时间复杂度

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

二、行为要点

1. 数组 / 对象 → 空容器：[] 或 {}

2. 数值 → 0：int、float 皆置为 0

3. 字符串 / 布尔 / null：保持原值

4. 路径不存在：安静忽略，不报错

5. 与 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 验证

七、最佳实践

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

八、总结

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

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

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