A TairDoc is a document data structure. You can use TairDocs to perform create, read, update, and delete (CRUD) operations on JSON data. This topic describes the commands supported by the TairDoc data structure.
Main features
- All JSON standards supported.
- Full compatibility with RedisJSON.
- JSONPath and JSON Pointer syntax supported.
- Binary tree data storage, which simplifies the retrieval of child elements.
- Conversion from the JSON format to the XML or YAML Ain't Markup Language (YAML) format.
Prerequisites
- The instance is a performance-enhanced instance of ApsaraDB for Redis Enhanced Edition (Tair). For more information, see Performance-enhanced instances.
- The instance is updated to the latest minor version. For more information, see Update the minor version.
Note If your instance is a cluster master-replica instance or read/write splitting instance, your proxy nodes must also be of the latest minor version to ensure that all commands can be executed as expected. For more information, see Cluster master-replica instances and Read/write splitting instances.
Precautions
The TairDocs to be managed are stored on the performance-enhanced instance.
Supported commands
Command | Syntax | Description |
---|---|---|
JSON.SET | JSON.SET <key> <path> <json> [NX | XX] |
Creates a TairDoc key and stores a JSON element in a path of the key. If the key and path already exist, this command updates the element in the path of the key. |
JSON.GET | JSON.GET <key> [PATH] [FORMAT <XML/YAML>] [ROOTNAME <root>] [ARRNAME <arr>] |
Retrieves the JSON element in a path of a TairDoc key. |
JSON.DEL | JSON.DEL <key> [path] |
Deletes the JSON element from the path in a TairDoc key. If the path is not specified, the key is deleted. If the key or path does not exist, this command is ignored. |
JSON.TYPE | JSON.TYPE <key> [path] |
Retrieves the type of the JSON element from the path in a TairDoc key. Element types
include |
JSON.NUMINCRBY | JSON.NUMINCRBY <key> [path] <value> |
Increases the JSON element value in the path of a TairDoc key. The element and the value that you want to add to the element both must be of the same data type of integer or double. |
JSON.STRAPPEND | JSON.STRAPPEND <key> [path] <json-string> |
Adds the json-string value to the JSON element in the path of a TairDoc key. The json-string value and JSON element must both be of the string type. |
JSON.STRLEN | JSON.STRLEN <key> [path] |
Retrieves the string length of the JSON element in a path of a TairDoc key. The JSON element must be of the string type. |
JSON.ARRAPPEND | JSON.ARRAPPEND <key> <path> <json> [<json> ...] |
Adds one or more JSON elements to the end of an array in a path of a TairDoc key. |
JSON.ARRPOP | JSON.ARRPOP <key> <path> [index] |
Removes and returns the element that matches the specified index in an array of a TairDoc key path. |
JSON.ARRINSERT | JSON.ARRINSERT <key> <path> <index> <json> [<json> ...] |
Adds one or more JSON elements to an array in the path of a TairDoc key. |
JSON.ARRLEN | JSON.ARRLEN <key> [path] |
Retrieves the length of an array in the path of a TairDoc key. |
JSON.ARRTRIM | JSON.ARRTRIM <key> <path> <start> <stop> |
Trims the array in the path of a TairDoc key and retains the elements in the array that are within the start value and the stop value. |
DEL | DEL <key> [key ...] |
Deletes one or more TairDoc keys. |
JSON.SET
Item | Description |
---|---|
Syntax | JSON.SET <key> <path> <json> [NX | XX] |
Time complexity |
O(N) |
Command description |
Creates a TairDoc key and stores a JSON element in a path of the key. If the key and path already exist, this command updates the element in the path of the key. Note If the key does not exist, the path is specified as root (or
. ).
|
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
JSON.GET
Item | Description |
---|---|
Syntax | JSON.GET <key> [PATH] [FORMAT <XML | YAML>] [ROOTNAME <root>] [ARRNAME <arr>] |
Time complexity |
O(N) |
Command description |
Retrieves the JSON element in a path of a TairDoc key. |
Parameter |
Note The ROOTNAME and ARRNAME parameters are valid only if the FORMAT parameter is set
to XML.
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.DEL
Item | Description |
---|---|
Syntax | JSON.DEL <key> [path] |
Time complexity |
O(N) |
Command description |
Deletes the JSON element from the path in a TairDoc key. If the path is not specified, the key is deleted. If the key or path does not exist, this command is ignored. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.TYPE
Item | Description |
---|---|
Syntax | JSON.TYPE <key> [path] |
Time complexity |
O(N) |
Command description |
Retrieves the type of the JSON element from the path in a TairDoc key. Element types
include |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.NUMINCRBY
Item | Description |
---|---|
Syntax | JSON.NUMINCRBY <key> [path] <value> |
Time complexity |
O(N) |
Command description |
Increases the JSON element value in the path of a TairDoc key. The element and the value that you want to add to the element both must be of the same data type of integer or double. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.STRAPPEND
Item | Description |
---|---|
Syntax | JSON.STRAPPEND <key> [path] <json-string> |
Time complexity |
O(N) |
Command description |
Adds the json-string value to the JSON element in the path of a TairDoc key. The json-string value and JSON element must both be of the string type. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.STRLEN
Item | Description |
---|---|
Syntax | JSON.STRLEN <key> [path] |
Time complexity |
O(N) |
Command description |
Retrieves the string length of the JSON element in a path of a TairDoc key. The JSON element must be of the string type. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.ARRAPPEND
Item | Description |
---|---|
Syntax | JSON.ARRAPPEND <key> <path> <json> [<json> ...] |
Time complexity |
O(M×N), where M specifies the number of JSON elements that you want to add and N specifies the number of elements in the array. |
Command description |
Adds one or more JSON elements to the end of an array in a path of a TairDoc key. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.ARRPOP
Item | Description |
---|---|
Syntax | JSON.ARRPOP <key> <path> [index] |
Time complexity |
O(M×N), where M specifies the child elements in the key and N specifies the number of elements in the array. |
Command description |
Removes and returns the element that matches the specified index in an array of a TairDoc key path. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.ARRINSERT
Item | Description |
---|---|
Syntax | JSON.ARRINSERT <key> <path> <index> <json> [<json> ...] |
Time complexity |
O(M×N), where M specifies the number of JSON elements that you want to add and N specifies the number of elements in the array. |
Command description |
Adds one or more JSON elements to an array in the path of a TairDoc key. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.ARRLEN
Item | Description |
---|---|
Syntax | JSON.ARRLEN <key> [path] |
Time complexity |
O(N) |
Command description |
Retrieves the length of an array in the path of a TairDoc key. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON.ARRTRIM
Item | Description |
---|---|
Syntax | JSON.ARRTRIM <key> <path> <start> <stop> |
Time complexity |
O(N) |
Command description |
Trims the array in the path of a TairDoc key and retains the elements in the array that are within the start value and the stop value. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
JSON Pointer and JSONPath
TairDoc supports the JSONPointer syntax and also supports some of the JSONPath syntax. The following table compares the examples of the two syntax type.
The JSON.SET doc . '{"foo": "bar", "baz" : [1,2,3]}'
command is run in advance.
JSONPointer | JSONPath |
---|---|
Sample command:
Sample output:
|
Sample command:
Sample output:
|
The following table shows how TairDoc supports the JSONPath and JSON Pointer syntax.
Item | JSONPath | JSONPointer |
---|---|---|
Root element | . | "" |
An individual element in a path | .a.b.c | /a/b/c |
Array | .a[2] | /a/2 |
Multiple elements in a path | .a["b.c"] | /a/b.c |
.a['b.c'] | /a/b.c |