JSON.SET
在 key 中设置路径处的 JSON 值
语法
JSON.SET key path value [NX | XX] [FPHA ]
引入版本：1.0.0
复杂度摘要：O(M+N)
设置或替换 path 解析的每个位置处的值。
如果key不存在，则只能通过设置根路径（$或.）来创建新的JSON文档。
当父对象存在时，JSON.SET 还可以创建新的对象成员。
必需参数
key
是要创建的新键还是要修改的现有 JSON 键。
path
解析为 JSON 文档中零个或多个位置的 JSONPath 表达式。
- 文档的根指定为
$或.。 - 如果
path解析为一个或多个现有位置，则每个匹配位置处的值将替换为value。 - 如果
path的最终标记是不存在的对象成员，并且父位置存在并且是对象，则创建该成员并将其设置为value。 - 如果任何中间路径元素不存在，则无法创建路径，并且命令返回nil。
可选参数 NX 和 XX 修改新键和现有 JSON 键的此行为。
value
要在指定路径设置的有效 JSON 值。
该值可以是标量（字符串、数字、布尔值或空）或复合值，例如对象或数组。
可选参数
NX
仅当 path 没有匹配项时才设置该值。
XX
仅当 path 具有一个或多个匹配项时才设置该值。
FPHA
强制浮点同构数组 (FPHA) 使用指定的 FP 类型。 Redis 8.8 中添加。
可用类型在精度和内存占用之间进行权衡。 FP64（64 位）和 FP32（32 位）为科学和一般计算工作负载提供更高的精度。 BF16 和 FP16（均为 16 位）使用的内存是 FP32 的一半，并且需要更少的内存，因此非常适合 AI 训练和推理。常见的策略是在 BF16/FP16 中存储和计算以提高速度，同时在 FP32 中累积结果以保持准确性。
由于 JSON 的数字表示是文本的，因此 Redis 无法始终推断出用于 FPHA 的最佳 FP 类型（例如，用于向量嵌入）。如果您的 JSON 是从具有给定 FP 类型的 FP 值数组生成的，则应在此处传递此类型。
如果给定 FPHA 中的至少一个指定值不符合指定的类型（溢出情况），该命令将发出“value out of range”错误。
示例
Replace an existing value
redis> JSON.SET doc $ '{"a":2}' OK redis> JSON.SET doc $.a '3' OK redis> JSON.GET doc $ "[{\"a\":3}]"
Add a new value
redis> JSON.SET doc $ '{"a":2}' OK redis> JSON.SET doc $.b '8' OK redis> JSON.GET doc $ "[{\"a\":2,\"b\":8}]"
Add a new value with FPHA
redis> JSON.SET 文档 $ '[[1,2,3,4e3],[5,6.0,7,8]]' FPHA FP16 OK redis> JSON.GET 文档 $ "[[[1.0,2.0,3.0,4000.0],[5.0,6.0,7.0,8.0]]]"
Update multiple matches
redis> JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}' OK redis> JSON.SET doc $..a 3 OK redis> JSON.GET doc "{\"f1\":{\"a\":3},\"f2\":{\"a\":3}}"
path does not exist and cannot be created
redis> JSON.SET doc $ 1 OK redis> JSON.SET doc $.x.y 2 (nil)
XX condition unmet
redis> JSON.SET nonexistentkey $ 5 XX (nil) redis> JSON.GET nonexistentkey (nil)
key does not exist and path is not root
redis> JSON.SET nonexistentkey $.x 5 (错误) ERR 新对象必须在根创建
Redis Software 与 Redis Cloud 兼容性
| Redis 软件 |
Redis Cloud |
说明 |
|---|---|---|
| ✅ 支持 |
✅ 灵活且每年一次 ✅ 免费和固定 |
返回值
RESP2
以下之一： * 简单字符串回复：OK（如果执行正确）。 * 空回复：如果 key 存在，但 path 不存在且无法创建，或者 NX 或 XX 条件不满足。 * 简单错误回复: (error) expected ... - 如果该值无效。 * 简单错误回复: (error) Error occurred on position ... expected ... - 如果路径无效。 * 简单错误回复: (error) ERR new objects must be created at the root - 如果 key 不存在且 path 不是根（$ 或 .）。 * 简单错误回复: (error) ERR wrong static path - 如果动态路径表达式没有匹配位置。 * 简单错误回复: (error) ERR index out of bounds - 如果路径引用数组边界之外的数组索引。 * 简单错误回复: (error) value out of range for ... - 如果 FP 数组的一个或多个值超出给定类型的范围。
RESP3
以下之一： * 简单字符串回复：OK（如果执行正确）。 * 空回复：如果 key 存在，但 path 不存在且无法创建，或者 NX 或 XX 条件不满足。 * 简单错误回复: (error) expected ... - 如果该值无效。 * 简单错误回复: (error) Error occurred on position ... expected ... - 如果路径无效。 * 简单错误回复: (error) ERR new objects must be created at the root - 如果 key 不存在且 path 不是根（$ 或 .）。 * 简单错误回复: (error) ERR wrong static path - 如果动态路径表达式没有匹配位置。 * 简单错误回复: (error) ERR index out of bounds - 如果路径引用数组边界之外的数组索引。 * 简单错误回复: (error) value out of range for ... - 如果 FP 数组的一个或多个值超出给定类型的范围。
参见
相关主题
资料来源：Redis 官方 JSON.SET 文档；中文内容参考 Redis 文档许可。