1、指令速查

JSON.ARRTRIM <key> <path> <start> <stop>

• key：Redis 鍵名

• path：JSONPath，默認 $ 根；可用 .[*]/.. 多路徑匹配

• start / stop：要保留的 [start, stop] 閉區間索引

  • 支持負值（從尾部數）
  • 越界也不會報錯，而是自動鉗位
  • start > stop 或 start ≥ 數組長度 ? 結果為空數組，返回 0

返回值：與路徑對應的新數組長度；若路徑不是數組 ? nil。

時間復雜度

• 單路徑 → O(N)，N 為數組長度
• 多路徑 → O(N × 匹配數)

2、核心特性 & 場景

功能	應用示例
滑動窗口	日志只保留最近 k 條、限流計數器
排行榜截斷	取前 100 名：start=0 stop=99
RingBuffer	寫前 ARRTRIM -capacity -1
批量歸檔	先 ARRTRIM 保留近檔，再把彈出數據寫冷庫

3、CLI 實戰：給耳機音量檔裁剪“窗口”

3.1 初始化并追加

# 12 個檔位
JSON.ARRAPPEND key $.[1].max_level 140 160 180 200 220 240 260 280
# -> (integer) 12

3.2 僅保留第 5-9 位（含 4 – 8）

redis> JSON.ARRTRIM key $.[1].max_level 4 8
1) (integer) 5

數組變為 [140, 160, 180, 200, 220]。

3.3 保留最近 3 條（負索引）

redis> JSON.ARRTRIM key $.[1].max_level -3 -1
1) (integer) 3

4、越界 & 容錯細節（v2.0+）

• start < 0 → 從尾部數
• stop > len-1 → 自動截到尾
• start > stop → 數組置空，返回 0
• 空數組裁剪仍返回 0 而非錯誤

因此大膽裁剪不必先算長度，適合高并發窗口滑動。

5、跨語言實戰

5.1 Python（redis-py ≥ 5.0）

from redis import Redis
r = Redis(decode_responses=True)# 僅保留最近 100 條
r.execute_command("JSON.ARRTRIM", "chat:room:42", "$.msgs", -100, -1)

5.2 Node.js（@redis/client）

import { createClient } from 'redis';
const cli = createClient(); await cli.connect();// 排行榜：只留前 50
await cli.json.arrTrim('rank:game', '$.players', 0, 49);

5.3 Go（go-redis/v9）

_, _ = rdb.Do(ctx, "JSON.ARRTRIM","sensor:temp", "$.records", -3600, -1).Result() // 保留最近一小時秒級點

6、最佳實踐

1. 寫后即裁

   JSON.ARRAPPEND key $.logs '"new"'  \
   && JSON.ARRTRIM key $.logs -1000 -1   # 保 1000 條
   

   兩條指令可用 MULTI/EXEC 或 Lua 保證原子順序。

2. 配合定時任務
   對歷史不敏感場景，每 N 分鐘統一裁剪降壓。

3. 避免大范圍多路徑
   通配 $..* 上萬數組會致 O(N2)；拆文檔或逐鍵裁剪。

4. 鏈式操作
   ARRTRIM 后再 ARRLEN 檢測是否需縮容或歸檔。

7、與數組家族的最終協同

需求	推薦組合
固定大小消息隊列	ARRAPPEND → ARRTRIM -max -1
排行榜更新	分數變動后排序（客戶端）→ ARRTRIM 0 99
限流計數	寫前 ARRTRIM -window -1 → ARRLEN 判斷是否超閾
熱→冷數據遷移	先 ARRTRIM 出窗口外數據，用 ARRPOP 逐條搬遷

8、結語：數組六神技大集合

增	查	刪	量	彈	裁
ARRAPPEND / ARRINSERT	ARRINDEX	ARRPOP	ARRLEN	ARRPOP	ARRTRIM

至此，RedisJSON 數組全家桶已完全解鎖：

• 增：動態插入 / 追加
• 查：定位元素
• 量：獲取長度
• 刪：單條彈出 or 批量裁剪

合理組合即可構建高效、原子、安全的數組數據結構。希望本系列能讓你在高并發 JSON 數據處理上游刃有余！🎉