RedisJSON JSON.OBJKEYS 怎样列出对象字段名

在 RedisJSON 中，如果你想查看一个 JSON 对象有哪些字段，直接使用 JSON.OBJKEYS。它返回对象的字段名列表，而不是字段值；如果路径匹配到多个对象，JSONPath 形式还会按匹配结果返回多组列表。

官方地址：https://redis.io/docs/latest/commands/json.objkeys/

先用根路径读取对象字段

命令的最小形式是 JSON.OBJKEYS key [path]。假设文档根部是一个对象，先写入一个包含基础字段和嵌套对象的示例，再读取根对象的字段名。

# 写入一个 JSON 对象，根部包含三个字段
redis-cli JSON.SET profile:1001 '$' '{"name":"Lin","age":30,"contact":{"city":"Hangzhou","zip":"310000"}}'

# 读取根对象的字段名，不读取字段值
redis-cli JSON.OBJKEYS profile:1001 '$'

# 省略 path 时使用默认根路径，适合简单的根对象查询
redis-cli JSON.OBJKEYS profile:1001

示例中的返回应理解为字段名列表，例如 name、age 和 contact。字段名的排列不应被当成业务排序依据，因为 JSON 对象本质上是无序的键值集合。

用路径读取嵌套对象

读取嵌套对象时，路径应指向对象所在的位置。例如上面的 contact 对象有 city 和 zip 两个字段。JSONPath 写法使用 $.contact；legacy path 则可以写成 .contact 或 contact。

# JSONPath 写法：定位 contact 对象并列出它的字段
redis-cli JSON.OBJKEYS profile:1001 '$.contact'

# legacy path 写法：只定位第一个匹配位置
redis-cli JSON.OBJKEYS profile:1001 '.contact'

# 把 JSON.OBJKEYS 与 JSON.GET 区分开：前者返回字段名，后者读取值
redis-cli JSON.GET profile:1001 '$.contact.city'

如果路径定位到字符串、数字或数组，而不是对象，命令就没有“对象字段名”可以返回。排查时先用 JSON.TYPE 或 JSON.GET 确认路径指向的节点类型，再决定是否继续使用 JSON.OBJKEYS。

JSONPath 多匹配时怎样读懂返回值

JSONPath 可以一次命中多个对象，例如文档中有多个服务节点，每个节点都有自己的配置字段。此时 JSON.OBJKEYS 会为每个匹配位置保留一组结果；某个匹配位置不是对象时，对应位置可能是 nil，不能把它和“整条路径不存在”混为一谈。

# 写入包含两个对象和一个非对象节点的数组
redis-cli JSON.SET services '$' '{"items":[{"name":"api","port":8080},{"name":"worker","queue":"jobs"},"offline"]}'

# $..items[*] 匹配数组中的三个位置，返回各自的字段名或空节点结果
redis-cli JSON.OBJKEYS services '$.items[*]'

可以用下面的判断表理解常见边界。JSONPath 模式下，多个匹配位置对应多个返回元素；legacy path 模式则只处理第一个匹配位置，二者不要混用。

建立排查与选型边界

实际使用时可以按“节点类型、路径语法、目标动作”三步排查。第一步确认 key 中存的是 JSON 文档且目标节点是对象；第二步确认你需要的是 JSONPath 多匹配还是 legacy path 的单匹配；第三步确认后续动作到底是列字段、统计数量还是读取和修改值。

• 只想知道字段名：使用 JSON.OBJKEYS。
• 只想知道字段数量：使用 JSON.OBJLEN，不要读取列表后在客户端计数。
• 想读取字段值：使用 JSON.GET，字段名列表不能替代值查询。
• 想修改或新增字段：使用 JSON.SET，不要把读取命令当成更新命令。

还要注意 JSONPath 的多匹配返回形态。如果应用只支持单个列表，却传入可能命中多个对象的路径，就应在应用层明确选择目标，或者把路径收窄到一个稳定节点。

相关问题

JSON.OBJKEYS 返回的是字段名还是字段值？

返回的是 JSON 对象的字段名列表。需要值时使用 JSON.GET，并把路径指向具体字段。

路径不存在时为什么没有字段列表？

因为命令只能列出实际匹配到的对象字段。先确认 key 存在，再检查 JSONPath 是否与文档层级、数组下标和字段名一致。

JSON.OBJKEYS 能不能直接统计字段数量？

可以在客户端对返回列表计数，但如果目标只是数量，JSON.OBJLEN 语义更直接，也避免传输完整字段名列表。

总结：JSON.OBJKEYS 的核心是“定位一个或多个 JSON 对象，再返回它们的字段名”。根路径适合简单对象，嵌套路径用于收窄范围，JSONPath 多匹配则要特别关注每个匹配位置的返回形态。