tencent cloud

腾讯云分布式缓存数据库（兼容 Redis）

文档腾讯云分布式缓存数据库（兼容 Redis）命令参考Redis 版与 Valkey 版命令兼容性扩展模块JSON Module 族

JSON Module 族

Download
聚焦模式
字号
最后更新时间： 2026-08-11 11:12:00
JSON Module（valkey-json）提供 JSON 文档的原生存储与操作能力，允许以树形结构直接存储、查询和修改 JSON 数据，通过 JSONPath 表达式（如 $.store.book[0].title）可精确访问嵌套层级中的任意节点。该模块适用于文档型配置存储、API 响应缓存、嵌套对象查询等需要灵活 JSON 结构操作的场景。该模块自 Valkey 8.0 起支持，不属于 Redis 内核命令集。其核心命令按功能可分为以下四类：
文档级读写
JSON.SET：设置或更新指定路径的 JSON 值（支持 NX/XX 条件）。
JSON.GET：获取一个或多个路径的 JSON 值。
JSON.DEL：删除指定路径的节点。
JSON.MGET：批量获取多个键中同一路径的值。
类型与结构查询
JSON.TYPE：返回指定路径节点的 JSON 类型（object/array/string/number/boolean/null）。
JSON.OBJLEN / JSON.OBJKEYS：返回对象的字段数量或字段名列表。
JSON.ARRLEN：返回数组的长度。
JSON.STRLEN：返回字符串值的长度。
数值与字符串原子操作
JSON.NUMINCRBY / JSON.NUMMULTBY：对数值节点进行原子递增或乘法运算。
JSON.STRAPPEND：在字符串节点末尾追加内容。
JSON.TOGGLE：切换布尔值。
数组操作
JSON.ARRAPPEND：向数组末尾追加元素。
JSON.ARRINSERT：在指定索引位置插入元素。
JSON.ARRPOP：弹出指定索引位置的元素。
JSON.ARRTRIM：裁剪数组，保留指定范围。
JSON.ARRINDEX：查找元素在数组中的索引位置。
更多信息请参见 Valkey 官方文档：valkey-json 模块。

命令支持概览

基础读写命令：JSON.SET、JSON.GET、JSON.MGET、JSON.MSET、JSON.DEL（含别名 JSON.FORGET），用于设置/获取/批量读取/批量设置/删除键中的 JSON 值。Valkey 8.0标准架构与集群架构均支持。
字符串操作命令：JSON.STRAPPEND、JSON.STRLEN，用于向 JSON 字符串追加内容和获取字符串长度。Valkey 8.0标准架构与集群架构均支持。
数值操作命令：JSON.NUMINCRBY、JSON.NUMMULTBY，用于对 JSON 数值进行加减和乘法运算。Valkey 8.0标准架构与集群架构均支持。
数组操作命令：JSON.ARRAPPEND、JSON.ARRINDEX、JSON.ARRINSERT、JSON.ARRLEN、JSON.ARRPOP、JSON.ARRTRIM，用于向数组追加元素、查找元素索引、插入元素、获取数组长度、弹出元素、修剪数组。Valkey 8.0标准架构与集群架构均支持。
对象操作命令：JSON.OBJKEYS、JSON.OBJLEN、JSON.CLEAR，用于获取对象键名、获取对象键数量、清空数组或对象。Valkey 8.0标准架构与集群架构均支持。
类型与调试命令：JSON.TYPE、JSON.TOGGLE、JSON.RESP、JSON.DEBUG，用于获取值类型、切换布尔值、以 RESP 格式返回 JSON 值、调试信息（JSON.DEBUG 的 KEYTABLE-CORRUPT、KEYTABLE-CLEAR、KEYTABLE-DISTRIBUTION 子命令需模块加载时启用 json.debug-mode）。
跨 Slot 限制：多数命令操作单个键，遵循标准键路由规则。JSON.MGET 和 JSON.MSET 为多键命令，集群架构下所有键必须位于同一哈希槽（Slot），否则触发 CROSSSLOT 错误。建议使用 Hash Tag（例如 {user}:profile、{user}:settings）确保同组键落入同一 Slot。

命令兼容性矩阵

该族命令在各版本与架构下的支持情况如下表所示（✓ 表示支持，✗ 表示不支持，— 表示该命令不存在跨 Slot 访问场景）。
命令
Valkey 9.0标准架构
Valkey 9.0集群架构
Valkey 8.0标准架构
Valkey 8.0集群架构
集群架构跨 Slot 支持
json.set
✓
✓
✓
✓
—
json.get
✓
✓
✓
✓
—
json.mget
✓
✓
✓
✓
✗
json.mset
✓
✓
✓
✓
✗
json.del
✓
✓
✓
✓
—
json.forget
✓
✓
✓
✓
—
json.strappend
✓
✓
✓
✓
—
json.strlen
✓
✓
✓
✓
—
json.numincrby
✓
✓
✓
✓
—
json.nummultby
✓
✓
✓
✓
—
json.arrappend
✓
✓
✓
✓
—
json.arrindex
✓
✓
✓
✓
—
json.arrinsert
✓
✓
✓
✓
—
json.arrlen
✓
✓
✓
✓
—
json.arrpop
✓
✓
✓
✓
—
json.arrtrim
✓
✓
✓
✓
—
json.objkeys
✓
✓
✓
✓
—
json.objlen
✓
✓
✓
✓
—
json.clear
✓
✓
✓
✓
—
json.type
✓
✓
✓
✓
—
json.toggle
✓
✓
✓
✓
—
json.resp
✓
✓
✓
✓
—
json.debug
✓
✓
✓
✓
—
上一篇: Search Module 族下一篇: 大版本命令使用差异

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈