一、指令速查

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 系列全部完結，愿你在高并發、高可維護的系統設計中靈活運用，碼力倍增！🎉