路径
访问 JSON 文档中的特定元素
路径允许您访问 JSON 文档中的特定元素。由于不存在 JSON 路径语法的标准，因此 Redis JSON 会实现自己的语法。JSON 的语法基于常见的最佳实践，并有意类似于 JSONPath。
JSON 支持两种查询语法：JSONPath 语法和 JSON 第一版中的旧版路径语法。
JSON 根据路径查询的第一个字符知道要使用哪种语法。如果查询以字符 开头，则它使用 JSONPath 语法。否则，它默认为传统路径语法。$
返回的值是一个 JSON 字符串，其中包含 JSON 序列化字符串的顶级数组。 如果使用多路径，则返回值是一个 JSON 字符串，其中包含一个顶级对象，其值是序列化的 JSON 值数组。
JSONPath 支持
RedisJSON v2.0 引入了 JSONPath 支持。它遵循 Goessner 在他的文章中描述的语法。
JSONPath 查询可以解析为 JSON 文档中的多个位置。在这种情况下，JSON 命令会将作应用于每个可能的位置。这是对传统路径查询的重大改进，传统路径查询仅在第一个路径上运行。
请注意，在使用 JSONPath 时，命令响应的结构通常有所不同。有关更多详细信息，请参阅 Commands 页面。
新语法支持方括号表示法，这允许在键名称中使用特殊字符，如冒号 “：” 或空格。
如果要在来自 CLI 的查询中包含双引号，请将 JSONPath 括在单引号内。例如：
JSON.GET store '$.inventory["mountain_bikes"]'
JSONPath syntax
The following JSONPath syntax table was adapted from Goessner's path syntax comparison.
Syntax element
Description
$
The root (outermost JSON element), starts the path.
. or []
Selects a child element.
..
Recursively descends through the JSON document.
*
Wildcard, returns all elements.
[]
Subscript operator, accesses an array element.
[,]
Union, selects multiple elements.
[start:end:step]
Array slice where start, end, and step are index values. You can omit values from the slice (for example, [3:], [:8:2]) to use the default values: start defaults to the first index, end defaults to the last index, and step defaults to 1. Use [*] or [:] to select all elements.
?()
Filters a JSON object or array. Supports comparison operators (==, !=, <, <=, >, >=, =~) , logical operators (&&, ||) , and parenthesis ((, )) .
()
Script expression.
@
The current element, used in filter or script expressions.
JSONPath examples
The following JSONPath examples use this JSON document, which stores details about items in a store's inventory:
{
"inventory": {
"mountain_bikes": [
{
"id": "bike:1",
"model": "Phoebe",
"description": "This is a mid-travel trail slayer that is a fantastic daily driver or one bike quiver. The Shimano Claris 8-speed groupset gives plenty of gear range to tackle hills and there\u2019s room for mudguards and a rack too. This is the bike for the rider who wants trail manners with low fuss ownership.",
"price": 1920,
"specs": {"material": "carbon", "weight": 13.1},
"colors": ["black", "silver"],
},
{
"id": "bike:2",
"model": "Quaoar",
"description": "Redesigned for the 2020 model year, this bike impressed our testers and is the best all-around trail bike we've ever tested. The Shimano gear system effectively does away with an external cassette, so is super low maintenance in terms of wear and tear. All in all it's an impressive package for the price, making it very competitive.",
"price": 2072,
"specs": {"material": "aluminium", "weight": 7.9},
"colors": ["black", "white"],
},
{
"id": "bike:3",
"model": "Weywot",
"description": "This bike gives kids aged six years and older a durable and uberlight mountain bike for their first experience on tracks and easy cruising through forests and fields. A set of powerful Shimano hydraulic disc brakes provide ample stopping ability. If you're after a budget option, this is one of the best bikes you could get.",
"price": 3264,
"specs": {"material": "alloy", "weight": 13.8},
},
],
"commuter_bikes": [
{
"id": "bike:4",
"model": "Salacia",
"description": "This bike is a great option for anyone who just wants a bike to get about on With a slick-shifting Claris gears from Shimano\u2019s, this is a bike which doesn\u2019t break the bank and delivers craved performance. It\u2019s for the rider who wants both efficiency and capability.",
"price": 1475,
"specs": {"material": "aluminium", "weight": 16.6},
"colors": ["black", "silver"],
},
{
"id": "bike:5",
"model": "Mimas",
"description": "A real joy to ride, this bike got very high scores in last years Bike of the year report. The carefully crafted 50-34 tooth chainset and 11-32 tooth cassette give an easy-on-the-legs bottom gear for climbing, and the high-quality Vittoria Zaffiro tires give balance and grip.It includes a low-step frame , our memory foam seat, bump-resistant shocks and conveniently placed thumb throttle. Put it all together and you get a bike that helps redefine what can be done for this price.",
"price": 3941,
"specs": {"material": "alloy", "weight": 11.6},
},
],
}
}
First, create the JSON document in your database:
Access examples
The following examples use the JSON.GET command to retrieve data from various paths in the JSON document.
You can use the wildcard operator * to return a list of all items in the inventory:
For some queries, multiple paths can produce the same results. For example, the following paths return the names of all mountain bikes:
The recursive descent operator .. can retrieve a field from multiple sections of a JSON document. The following example returns the names of all inventory items:
You can use an array slice to select a range of elements from an array. This example returns the names of the first 2 mountain bikes:
Filter expressions ?() let you select JSON elements based on certain conditions. You can use comparison operators (==, !=, <, <=, >, >=, and starting with version v2.4.2, also =~), logical operators (&&, ||), and parenthesis ((, )) within these expressions. A filter expression can be applied on an array or on an object, iterating over all the elements in the array or all the values in the object, retrieving only the ones that match the filter condition.
Paths within the filter condition use the dot notation with either @ to denote the current array element or the current object value, or $ to denote the top-level element. For example, use @.key_name to refer to a nested value and $.top_level_key_name to refer to a top-level value.
From version v2.4.2 onward, you can use the comparison operator =~ to match a path of a string value on the left side against a regular expression pattern on the right side. For more information, see the supported regular expression syntax docs.
Non-string values do not match. A match can only occur when the left side is a path of a string value and the right side is either a hard-coded string, or a path of a string value. See examples below.
The regex match is partial, meaning a regex pattern like "foo" matches a string such as "barefoots".
To make the match exact, use the regex pattern "^foo$".
Other JSONPath engines may use regex patterns between slashes (for example, /foo/),
and their match is exact. They can perform partial matches using a regex pattern such
as /.*foo.*/.
Filter examples
In the following example, the filter only returns mountain bikes with a price less than 3000 and
a weight less than 10:
This example filters the inventory for the model names of bikes made from alloy:
This example, valid from version v2.4.2 onwards, filters only bikes whose material begins with
"al-" using regex match. Note that this match is case-insensitive because of the prefix (?i) in
the regular expression pattern "(?i)al":
You can also specify a regex pattern using a property from the JSON object itself.
For example, we can add a string property named regex_pat to each mountain bike,
with the value "(?i)al" to match the material, as in the previous example. We
can then match regex_pat against the bike's material:
Update examples
You can also use JSONPath queries when you want to update specific sections of a JSON document.
For example, you can pass a JSONPath to the JSON.SET command to update a specific field. This example changes the price of the first item in the headphones list:
You can use filter expressions to update only JSON elements that match certain conditions. The following example sets the price of any bike to 1500 if its price is already less than 2000:
JSONPath queries also work with other JSON commands that accept a path as an argument. For example, you can add a new color option for a set of headphones with JSON.ARRAPPEND:
Legacy path syntax
RedisJSON v1 had the following path implementation. JSON v2 still supports this legacy path in addition to JSONPath.
Paths always begin at the root of a Redis JSON value. The root is denoted by a period character (.). For paths that reference the root's children, it is optional to prefix the path with the root.
Redis JSON supports both dot notation and bracket notation for object key access. The following paths refer to headphones, which is a child of inventory under the root:
.inventory.headphonesinventory["headphones"]['inventory']["headphones"]
To access an array element, enclose its index within a pair of square brackets. The index is 0-based, with 0 being the first element of the array, 1 being the next element, and so on. You can use negative offsets to access elements starting from the end of the array. For example, -1 is the last element in the array, -2 is the second to last element, and so on.
JSON key names and path compatibility
By definition, a JSON key can be any valid JSON string. Paths, on the other hand, are traditionally based on JavaScript's (and Java's) variable naming conventions.
Although JSON can store objects that contain arbitrary key names, you can only use a legacy path to access these keys if they conform to these naming syntax rules:
- Names must begin with a letter, a dollar sign (
$), or an underscore (_) character
- Names can contain letters, digits, dollar signs, and underscores
- Names are case-sensitive
Time complexity of path evaluation
The time complexity of searching (navigating to) an element in the path is calculated from:
- Child level - every level along the path adds an additional search
- Key search - O(N)†, where N is the number of keys in the parent object
- Array search - O(1)
This means that the overall time complexity of searching a path is O(N*M), where N is the depth and M is the number of parent object keys.
† While this is acceptable for objects where N is small, access can be optimized for larger objects.
On this page