RedisJSON aims to provide full support for ECMA-404 The JSON Data Interchange Standard.
Below, the term JSON Value refers to any of the valid values. A Container is either a JSON Array or a JSON Object. A JSON Scalar is a JSON Number, a JSON String, or a literal (JSON False, JSON True, or JSON Null).
The module's commands are described below. Each section header shows the syntax for the command, where:
- Command and subcommand names are in uppercase, for example
JSON.SETorINDENT - Mandatory arguments are enclosed in angle brackets, for example
<path> - Optional arguments are enclosed in square brackets, for example
[index] - Additional optional arguments are indicated by three period characters, for example
... - The pipe character,
|, means an exclusive or
Commands usually require a key's name as their first argument. The path is generally assumed to be the root if not specified.
The time complexity of the command does not include that of the path. The size - usually denoted N - of a value is:
- 1 for scalar values
- The sum of sizes of items in a container
Available since 1.0.0.
Time complexity: O(M+N) when path is evaluated to a single value, where M is the size of the original value (if it exists) and N is the size of the new value. O(M+N) when path is evaluated to multiple values, where M is the size of the key and N is the size of the new value.
JSON.SET <key> <path> <json>
[NX | XX]Sets the JSON value at path in key.
For new Redis keys, the path must be the root. For existing keys, replaces the current value with the json value if the entire path exists.
Adds a key (with its respective value) to a JSON Object (in a RedisJSON data type key) only if it is the last child in the path. The optional subcommands modify this behavior for both new RedisJSON data type keys as well as the JSON Object keys in them:
NX- only set the key if it does not already existXX- only set the key if it already exists
Simple String - OK if executed correctly, or Null Bulk if the specified NX or XX
conditions were not met.
Available since 1.0.0.
Time complexity: O(N) when path is evaluated to a single value, where N is the size of the value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.GET <key>
[INDENT indentation-string]
[NEWLINE line-break-string]
[SPACE space-string]
[path ...]Returns the value at path in JSON serialized form.
This command accepts multiple path arguments. If no path is given, it defaults to the value's root.
The following subcommands change the reply's format (all are empty string by default):
INDENTsets the indentation string for nested levelsNEWLINEsets the string that's printed at the end of each lineSPACEsets the string that's put between a key and a value
Produce pretty-formatted JSON with redis-cli by following this example:
~/$ redis-cli --raw
127.0.0.1:6379> JSON.GET myjsonkey INDENT "\t" NEWLINE "\n" SPACE " " path.to.value[1]
Array of Bulk Strings - each string is the JSON serialization of each JSON value that matches a path.
When using a JSONPath, the root of the matching values is always an array. In contrast, the legacy path returns a single value.
If there are multiple paths that include both legacy path and JSONPath, the returned value conforms to the JSONPath version (an array of values).
127.0.0.1:6379> JSON.SET doc $ '{"a":2, "b": 3, "nested": {"a": 4, "b": null}}'
OKWith a single JSONPath (JSON array bulk string):
127.0.0.1:6379> JSON.GET doc $..b
"[3,null]"Using multiple paths with at least one JSONPath (map with array of JSON values per path):
127.0.0.1:6379> JSON.GET doc ..a $..b
"{\"$..b\":[3,null],\"..a\":[2,4]}"Available since 1.0.0.
Time complexity: O(M*N) when path is evaluated to a single value, where M is the number of keys and N is the size of the value. O(N1+N2+...+Nm) when path is evaluated to multiple values, where m is the number of keys and Ni is the size of the i-th key.
JSON.MGET <key> [key ...] <path>Returns the values at path from multiple key arguments. Returns null for nonexistent keys and nonexistent paths.
Array of Bulk Strings - the JSON serialization of the value at each key's path.
Given the following documents:
127.0.0.1:6379> JSON.SET doc1 $ '{"a":1, "b": 2, "nested": {"a": 3}, "c": null}'
OK
127.0.0.1:6379> JSON.SET doc2 $ '{"a":4, "b": 5, "nested": {"a": 6}, "c": null}'
OK127.0.0.1:6379> JSON.MGET doc1 doc2 $..a
1) "[1,3]"
2) "[4,6]"Available since 1.0.0.
Time complexity: O(N) when path is evaluated to a single value, where N is the size of the deleted value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.DEL <key> [path]Deletes a value.
path defaults to root if not provided. Ignores nonexistent keys and paths. Deleting an object's root is equivalent to deleting the key from Redis.
Integer - the number of paths deleted (0 or more).
127.0.0.1:6379> JSON.SET doc $ '{"a": 1, "nested": {"a": 2, "b": 3}}'
OK
127.0.0.1:6379> JSON.DEL doc $..a
(integer) 2Available since 2.0.0.
Time complexity: O(N), where N is the number of cleared values
JSON.CLEAR <key> [path]
Clear a container value (Array/Object).
path defaults to root if not provided. Non-existing keys and paths are ignored.
Integer, specifically the number of containers cleared.
Available since 1.0.0.
Time complexity: O(1) when path is evaluated to a single value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.NUMINCRBY <key> <path> <number>Increments the number value stored at path by number.
Bulk String - the stringified new value for each path, or null if the matching JSON value is not a number.
127.0.0.1:6379> JSON.SET doc . '{"a":"b","b":[{"a":2}, {"a":5}, {"a":"c"}]}'
OK
127.0.0.1:6379> JSON.NUMINCRBY doc $.a 2
"[null]"
127.0.0.1:6379> JSON.NUMINCRBY doc $..a 2
"[null,4,7,null]"Deprecated - will be dropped in the next version
Available since 1.0.0.
Time complexity: O(1).
JSON.NUMMULTBY <key> <path> <number>Multiplies the number value stored at path by number.
Bulk String - the stringified new values for each path, or null element if the matching JSON value is not a number.
127.0.0.1:6379> JSON.SET doc . '{"a":"b","b":[{"a":2}, {"a":5}, {"a":"c"}]}'
OK
127.0.0.1:6379> JSON.NUMMULTBY doc $.a 2
"[null]"
127.0.0.1:6379> JSON.NUMMULTBY doc $..a 2
"[null,4,10,null]"Available since 2.0.0.
Time complexity: O(1).
JSON.TOGGLE <key> <path>
Toggle a boolean value stored at path.
Integer, specifically the new value (0-false or 1-true), or null element for JSON values matching the path which are not boolean.
Available since 1.0.0.
Time complexity: O(1) when path is evaluated to a single value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.STRAPPEND <key> [path] <json-string>Appends the json-string values to the string at path.
path defaults to root if not provided.
Array of Integers - for each path, the string's new length, or null if the matching JSON value is not an array.
127.0.0.1:6379> JSON.SET doc $ '{"a":"foo", "nested": {"a": "hello"}, "nested2": {"a": 31}}'
OK
127.0.0.1:6379> JSON.STRAPPEND doc $..a '"baz"'
1) (integer) 6
2) (integer) 8
3) (nil)
127.0.0.1:6379> JSON.GET doc $
"[{\"a\":\"foobaz\",\"nested\":{\"a\":\"hellobaz\"},\"nested2\":{\"a\":31}}]"Available since 1.0.0.
Time complexity: O(1) when path is evaluated to a single value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.STRLEN <key> [path]Reports the length of the JSON String at path in key.
path defaults to root if not provided. Returns null if the key or path do not exist.
Array of Integers - for each path, the string's length, or null if the matching JSON value is not a string.
127.0.0.1:6379> JSON.SET doc $ '{"a":"foo", "nested": {"a": "hello"}, "nested2": {"a": 31}}'
OK
127.0.0.1:6379> JSON.STRLEN doc $..a
1) (integer) 3
2) (integer) 5
3) (nil)Available since 1.0.0.
Time complexity: O(1) when path is evaluated to a single value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.ARRAPPEND <key> <path> <json> [json ...]Append the json values into the array at path after the last element in it.
Array of Integers - for each path, the array's new size, or null if the matching JSON value is not an array.
127.0.0.1:6379> JSON.SET doc $ '{"a":[1], "nested": {"a": [1,2]}, "nested2": {"a": 42}}'
OK
127.0.0.1:6379> JSON.ARRAPPEND doc $..a 3 4
1) (integer) 3
2) (integer) 4
3) (nil)
127.0.0.1:6379> JSON.GET doc $
"[{\"a\":[1,3,4],\"nested\":{\"a\":[1,2,3,4]},\"nested2\":{\"a\":42}}]"Available since 1.0.0.
Time complexity: O(N) when path is evaluated to a single value, where N is the size of the array. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.ARRINDEX <key> <path> <json-scalar> [start [stop]]Searches for the first occurrence of a scalar JSON value in an array.
The optional inclusive start (default 0) and exclusive stop (default 0, meaning that the last element is included) specify a slice of the array to search.
Negative values are interpreted as starting from the end.
Note: out-of-range indexes round to the array's start and end. An inverse index range (such as the range from 1 to 0) will return unfound.
Array of Integers - the first position in the array of each JSON value that matches the path, -1 if unfound in the array, or null if the matching JSON value is not an array.
127.0.0.1:6379> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": [3,4]}}'
OK
127.0.0.1:6379> JSON.ARRINDEX doc $..a 2
1) (integer) 1
2) (integer) -1127.0.0.1:6379> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": false}}'
OK
127.0.0.1:6379> JSON.ARRINDEX doc $..a 2
1) (integer) 1
2) (nil)Available since 1.0.0.
Time complexity: O(N) when path is evaluated to a single value, where N is the size of the array. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.ARRINSERT <key> <path> <index> <json> [json ...]Inserts the json values into the array at path before the index (shifts to the right).
The index must be in the array's range. Inserting at index 0 prepends to the array. Negative index values start from the end of the array.
Array of Integers - for each path, the array's new size, or null if the matching JSON value is not an array.
127.0.0.1:6379> JSON.SET doc $ '{"a":[3], "nested": {"a": [3,4]}}'
OK
127.0.0.1:6379> JSON.ARRINSERT doc $..a 0 1 2
1) (integer) 3
2) (integer) 4
127.0.0.1:6379> JSON.GET doc $
"[{\"a\":[1,2,3],\"nested\":{\"a\":[1,2,3,4]}}]"127.0.0.1:6379> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": false}}'
OK
127.0.0.1:6379> JSON.ARRINSERT doc $..a 0 1 2
1) (integer) 6
2) (nil)Available since 1.0.0.
Time complexity: O(1) where path is evaluated to a single value. O(N) where path is evaluated to multiple values, where N is the size of the key.
JSON.ARRLEN <key> [path]Reports the length of the JSON Array at path in key.
path defaults to root if not provided. Returns null if the key or path do not exist.
Array of Integers - for each path, the array's length, or null if the matching JSON value is not an array.
127.0.0.1:6379> JSON.SET doc $ '{"a":[3], "nested": {"a": [3,4]}}'
OK
127.0.0.1:6379> JSON.ARRLEN doc $..a
1) (integer) 1
2) (integer) 2127.0.0.1:6379> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": false}}'
OK
127.0.0.1:6379> JSON.ARRLEN doc $..a
1) (integer) 4
2) (nil)Available since 1.0.0.
Time complexity: O(N) when path is evaluated to a single value, where N is the size of the array and the specified index is not the last element. O(1) when path is evaluated to a single value and the specified index is the last element. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.ARRPOP <key> [path [index]]Removes and returns an element from the index in the array.
path defaults to root if not provided. index is the position in the array to start popping from (defaults to -1, meaning the last element). Out-of-range indexes round to their respective array ends. Popping an empty array returns null.
Array of Bulk Strings - for each path, the popped JSON value, or null if the matching JSON value is not an array.
127.0.0.1:6379> JSON.SET doc $ '{"a":[3], "nested": {"a": [3,4]}}'
OK
127.0.0.1:6379> JSON.ARRPOP doc $..a
1) "3"
2) "4"
127.0.0.1:6379> JSON.GET doc $
"[{\"a\":[],\"nested\":{\"a\":[3]}}]"127.0.0.1:6379> JSON.SET doc $ '{"a":["foo", "bar"], "nested": {"a": false}, "nested2": {"a":[]}}'
OK
127.0.0.1:6379> JSON.ARRPOP doc $..a
1) "\"bar\""
2) (nil)
3) (nil)Available since 1.0.0.
Time complexity: O(N) when path is evaluated to a single value, where N is the size of the array. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.ARRTRIM <key> <path> <start> <stop>Trims an array so that it contains only the specified inclusive range of elements.
This command is extremely forgiving and using it with out-of-range indexes will not produce an error. There are a few differences between how RedisJSON v2.0 and legacy versions handle out-of-range indexes.
Behavior as of RedisJSON v2.0:
- If
startis larger than the array's size orstart>stop, returns 0 and an empty array. - If
startis < 0, then start from the end of the array. - If
stopis larger than the end of the array, it will be treated like the last element.
Array of Integers - for each path, the array's new size, or null if the matching JSON value is not an array.
127.0.0.1:6379> JSON.ARRTRIM doc $..a 1 1
1) (integer) 0
2) (integer) 1
127.0.0.1:6379> JSON.GET doc $
"[{\"a\":[],\"nested\":{\"a\":[4]}}]"127.0.0.1:6379> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": false}}'
OK
127.0.0.1:6379> JSON.ARRTRIM doc $..a 1 1
1) (integer) 1
2) (nil)Available since 1.0.0.
Time complexity: O(N) when path is evaluated to a single value, where N is the number of keys in the object. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.OBJKEYS <key> [path]Returns the keys in the object that's referenced by path.
path defaults to root if not provided. Returns null if the object is empty or either key or path do not exist.
Array of Arrays - for each path, an array of the key names in the object as Bulk Strings, or null if the matching JSON value is not an object.
127.0.0.1:6379> JSON.SET doc $ '{"a":[3], "nested": {"a": {"b":2, "c": 1}}}'
OK
127.0.0.1:6379> JSON.OBJKEYS doc $..a
1) (nil)
2) 1) "b"
2) "c"Available since 1.0.0.
Time complexity: O(1) when path is evaluated to a single value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.OBJLEN <key> [path]Reports the number of keys in the JSON Object at path in key.
path defaults to root if not provided. Returns null if the key or path do not exist.
Integer - the number of keys in the object.
Available since 1.0.0.
Time complexity: O(1) when path is evaluated to a single value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.TYPE <key> [path]Reports the type of JSON value at path.
path defaults to root if not provided. Returns null if the key or path do not exist.
Array of Simple Strings - for each path, the value's type.
127.0.0.1:6379> JSON.SET doc $ '{"a":2, "nested": {"a": true}, "foo": "bar"}'
OK
127.0.0.1:6379> JSON.TYPE doc $..foo
1) "string"
127.0.0.1:6379> JSON.TYPE doc $..a
1) "integer"
2) "boolean"
127.0.0.1:6379> JSON.TYPE doc $..dummy
(empty array)Available since 1.0.0.
Time complexity: O(N), where N is the size of the JSON value.
JSON.DEBUG <subcommand & arguments>Reports information.
Supported subcommands are:
MEMORY <key> [path]- report a value's memory usage in bytes.pathdefaults to root if not provided.HELP- reply with a helpful message
Depends on the subcommand used.
An alias for JSON.DEL.
Available since 1.0.0.
Time complexity: O(N) when path is evaluated to a single value, where N is the size of the value. O(N) when path is evaluated to multiple values, where N is the size of the key.
JSON.RESP <key> [path]Returns the JSON in key in Redis Serialization Protocol (RESP) form.
path defaults to root if not provided. This command uses the following mapping from JSON to RESP:
- JSON Null maps to the RESP Null Bulk String
- JSON
falseandtruevalues map to RESP Simple Strings - JSON Numbers map to RESP Integers or RESP Bulk Strings, depending on type
- JSON Strings map to RESP Bulk Strings
- JSON Arrays are represented as RESP Arrays in which the first element is the simple string
[followed by the array's elements - JSON Objects are represented as RESP Arrays in which the first element is the simple string
{. Each successive entry represents a key-value pair as a two-entry array of bulk strings.
Array - the JSON's RESP form as detailed.