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).
Each of the module's commands is 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, e.g.
<path> - Optional arguments are enclosed in square brackets, e.g.
[index] - Additional optional arguments are indicated by three period characters, i.e.
... - 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(N), where N is the size of the deleted value.
JSON.DEL <key> [path]
Delete a value.
path defaults to root if not provided. Non-existing keys and paths are ignored. Deleting an object's root is equivalent to deleting the key from Redis.
Integer, specifically the number of paths deleted (0 or 1).
Available since 1.0.0.
Time complexity: O(N), where N is the size of the value.
JSON.GET <key>
[INDENT indentation-string]
[NEWLINE line-break-string]
[SPACE space-string]
[NOESCAPE]
[path ...]
Return the value at path in JSON serialized form.
This command accepts multiple paths, and defaults to the value's root when none are given.
The following subcommands change the reply's format and are all set to the 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
The NOESCAPE option will disable the sending of \uXXXX escapes for non-ascii
characters. This option should be used for efficiency if you deal mainly with
such text. The escaping of JSON strings will be deprecated in the future and this
option will become the implicit default.
Pretty-formatted JSON is producible 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]
Bulk String, specifically the JSON serialization.
The reply's structure depends on the number of paths. A single path results in the value itself being returned, whereas multiple paths are returned as a JSON object in which each path is a key.
Available since 1.0.0.
Time complexity: O(M*N), where M is the number of keys and N is the size of the value.
JSON.MGET <key> [key ...] <path>
Returns the values at path from multiple keys. Non-existing keys and non-existing paths are reported as null.
Array of Bulk Strings, specifically the JSON serialization of the value at each key's path.
Available since 1.0.0.
Time complexity: O(M+N), where M is the size of the original value (if it exists) 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, when the entire path exists, the value that it contains is replaced with the json value.
A key (with its respective value) is added to a JSON Object (in a Redis RedisJSON data type key) if and only if it is the last child in the path. The optional subcommands modify this behavior for both new Redis 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(1).
JSON.TYPE <key> [path]
Report the type of JSON value at path.
path defaults to root if not provided. If the key or path do not exist, null is returned.
Simple String, specifically the type of value.
Available since 1.0.0.
Time complexity: O(1).
JSON.NUMINCRBY <key> <path> <number>
Increments the number value stored at path by number.
Bulk String, specifically the stringified new value.
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, specifically the stringified new value.
Available since 1.0.0.
Time complexity: O(N), where N is the new string's length.
JSON.STRAPPEND <key> [path] <json-string>
Append the json-string value(s) the string at path.
path defaults to root if not provided.
Integer, specifically the string's new length.
Available since 1.0.0.
Time complexity: O(1).
JSON.STRLEN <key> [path]
Report the length of the JSON String at path in key.
path defaults to root if not provided. If the key or path do not exist, null is returned.
Integer, specifically the string's length.
Available since 1.0.0.
Time complexity: O(1).
JSON.ARRAPPEND <key> <path> <json> [json ...]
Append the json value(s) into the array at path after the last element in it.
Integer, specifically the array's new size.
Available since 1.0.0.
Time complexity: O(N), where N is the array's size.
JSON.ARRINDEX <key> <path> <json-scalar> [start [stop]]
Search 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.
Note: out of range errors are treated by rounding the index to the array's start and end. An inverse index range (e.g. from 1 to 0) will return unfound.
Integer, specifically the position of the scalar value in the array, or -1 if unfound.
Available since 1.0.0.
Time complexity: O(N), where N is the array's size.
JSON.ARRINSERT <key> <path> <index> <json> [json ...]
Insert the json value(s) 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 are interpreted as starting from the end.
Integer, specifically the array's new size.
Available since 1.0.0.
Time complexity: O(1).
JSON.ARRLEN <key> [path]
Report the length of the JSON Array at path in key.
path defaults to root if not provided. If the key or path do not exist, null is returned.
Integer, specifically the array's length.
Available since 1.0.0.
Time complexity: O(N), where N is the array's size forindexother than the last element, O(1) otherwise.
JSON.ARRPOP <key> [path [index]]
Remove and return 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 indices are rounded to their respective array ends. Popping an empty array yields null.
Bulk String, specifically the popped JSON value.
Available since 1.0.0.
Time complexity: O(N), where N is the array's size.
JSON.ARRTRIM <key> <path> <start> <stop>
Trim 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. If start is larger than the array's size or start > stop, the result will be an empty array. If start is < 0 then it will be treated as 0. If stop is larger than the end of the array, it will be treated like the last element in it.
Integer, specifically the array's new size.
Available since 1.0.0.
Time complexity: O(N), where N is the number of keys in the object.
JSON.OBJKEYS <key> [path]
Return the keys in the object that's referenced by path.
path defaults to root if not provided. If the object is empty, or either key or path do not exist, then null is returned.
Array, specifically the key names in the object as Bulk Strings.
Available since 1.0.0.
Time complexity: O(1).
JSON.OBJLEN <key> [path]
Report the number of keys in the JSON Object at path in key.
path defaults to root if not provided. If the key or path do not exist, null is returned.
Integer, specifically the number of keys in the object.
Available since 1.0.0.
Time complexity: O(N), where N is the size of the JSON value.
JSON.DEBUG <subcommand & arguments>
Report information.
Supported subcommands are:
MEMORY <key> [path]- report the memory usage in bytes of a value.pathdefaults to root if not provided.HELP- reply with a helpful message
Depends on the subcommand used.
MEMORYreturns an integer, specifically the size in bytes of the valueHELPreturns an array, specifically with the help message
An alias for JSON.DEL.
Available since 1.0.0.
Time complexity: O(N), where N is the size of the JSON value.
JSON.RESP <key> [path]
Return the JSON in key in Redis Serialization Protocol (RESP).
path defaults to root if not provided. This command uses the following mapping from JSON to RESP:
- JSON Null is mapped to the RESP Null Bulk String
- JSON
falseandtruevalues are mapped to the respective RESP Simple Strings - JSON Numbers are mapped to RESP Integers or RESP Bulk Strings, depending on type
- JSON Strings are mapped 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-entries array of bulk strings.
Array, specifically the JSON's RESP form as detailed.