TairDoc is a document data structure that is fully compatible with RedisJSON. You can use TairDoc to perform create, read, update, and delete (CRUD) operations.

Main features

  • All JSON standards supported.
  • Full compatibility with RedisJSON.
  • JSONPath and JSON Pointer syntax supported.
  • Binary tree data storage that simplifies the retrieval of child elements.
  • Conversion from the JSON format to the XML or YAML format.

Prerequisites

The instance is a performance-enhanced instance of the ApsaraDB for Redis Enhanced Edition (Tair). For more information about performance-enhanced instances, see Performance-enhanced instances.
Note The latest minor version provides more features and higher stability. We recommend that you update your instance to the latest minor version. For more information, see Update the minor version. If your instance is a cluster or read/write splitting instance, we recommend that you update the proxy nodes in the instance to the latest minor version. This ensures that all commands can be run as expected. For more information about cluster and read/write splitting instances, see Cluster master-replica instances and Read/write splitting instances.

Precautions

The TairDoc data to be managed is stored on the performance-enhanced instance.

Supported commands

Table 1. TairDoc 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 from the path of the TairDoc key.

JSON.DEL JSON.DEL key path

Deletes the JSON element from the path in the 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 the TairDoc key. Element types include boolean, string, number, array, object, raw, reference, const, and null.

JSON.NUMINCRBY JSON.NUMINCRBY key path value

Increases the JSON element value in the path of the 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 the TairDoc key. The json-string value and JSON element both must be of the string type.

JSON.STRLEN JSON.STRLEN key path

Retrieves the string length of the JSON element from the path of the 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 the path of the TairDoc key.

JSON.ARRPOP JSON.ARRPOP key path [index]

Removes and returns the element that matches the index in an array of the 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 the TairDoc key.

JSON.ARRLEN JSON.ARRLEN key path

Retrieves the length of an array in the path of the TairDoc key.

JSON.ARRTRIM JSON.ARRTRIM key path start stop

Trims the array in the path of the TairDoc key. This command 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.
Note The following section describes command syntax used in this topic:
  • Uppercase keyword: the command keyword.
  • Italic: Words in italic indicate variable information that you supply.
  • [options]: optional parameters. Parameters that are not included in brackets are required.
  • AB: specifies that these parameters are mutually exclusive. Select one of two or more parameters.
  • ...: specifies to repeat the preceding content.

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
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
  • json: the element that you want to add or update.
  • NX: specifies that the element is written only if the path does not exist.
  • XX: specifies that the element is written only if the path exists.
Output
  • If the operation is successful, OK is returned.
  • If the XX parameter is specified but the path does not exist, nil is returned.
  • If the NX parameter is specified and the path already exists, nil is returned.
  • Otherwise, an error message is returned.
Example

Sample command:

JSON.SET doc . '{"foo": "bar", "baz" : 42}'

Sample output:

OK

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 from the path of the TairDoc key.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
  • FORMAT: the JSON format of the element. Valid values: XML and YAML.
  • ROOTNAME : the tag of the root element in XML syntax.
  • ARRNAME: the tag of the array element in XML syntax.
Note The ROOTNAME and ARRNAME parameters are valid only if the FORMAT parameter is set to XML.
Output
  • If the operation is successful, the JSON element is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"foo": "bar", "baz" : 42}' command is run in advance.

Sample command:

JSON.GET doc . FORMAT XML ROOTNAME ROOT ARRNAME ARR

Sample output:

"<?xml version=\"1.0\" encoding=\"UTF-8\"?><ROOT><foo>bar</foo><baz>42</baz></ROOT>"

JSON.DEL

Item Description
Syntax JSON.DEL key path
Time complexity

O(N)
Command description

Deletes the JSON element from the path in the 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
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
Output
  • If the operation is successful, a value of 1 is returned.
  • If the operation fails, a value of 0 is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"foo": "bar", "baz" : 42}' command is run in advance.

Sample command:

JSON.DEL doc .foo

Sample output:

(integer) 1

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 the TairDoc key. Element types include boolean, string, number, array, object, raw, reference, const, and null.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
Output
  • If the operation is successful, the element type is returned.
  • If the operation fails, a value of 0 is returned.
  • If the key or path does not exist, nil is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"foo": "bar", "baz" : 42}' command is run in advance.

Sample command:

JSON.TYPE doc .foo

Sample output:

string

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 the 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
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
  • value: the value that you want to add to the element.
Output
  • If the operation is successful, the increased element in the path is returned.
  • If the key or path does not exist, the "error" message is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"foo": "bar", "baz" : 42}' command is run in advance.

Sample command:

JSON.NUMINCRBY doc .baz 10

Sample output:

"52"

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 the TairDoc key. The json-string value and JSON element both must be of the string type.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
  • json-string: the sting that you want to add to the JSON element in the path.
Output
  • If the operation is successful, the increased string length of the JSON element in the path is returned.
  • If the key does not exist, a value of -1 is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"foo": "bar", "baz" : 42}' command is run in advance.

Sample command:

JSON.STRAPPEND doc .foo rrrrr

Sample output:

(integer) 8

JSON.STRLEN

Item Description
Syntax JSON.STRLEN key path
Time complexity

O(N)
Command description

Retrieves the string length of the JSON element from the path of the TairDoc key. The JSON element must be of the string type.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
Output
  • If the operation is successful, the string length of the JSON element in the path is returned.
  • If the key does not exist, a value of -1 is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"foo": "bar", "baz" : 42}' command is run in advance.

Sample command:

JSON.STRLEN doc .foo

Sample output:

(integer) 3

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 the path of the TairDoc key.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
  • json: the element that you want to add to the array.
Output
  • If the operation is successful, the number of elements in the array is returned.
  • If the key does not exist, a value of -1 is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"id": [1,2,3]}' command is run in advance.

Sample command:

JSON.ARRAPPEND doc .id null false true

Sample output:

(integer) 6

JSON.ARRPOP

Item Description
Syntax JSON.ARRPOP key path [index]
Time complexity

O(M×N), where M specifies the number of 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 index in an array of the TairDoc key path.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
  • index: the index in the array. The beginning index is 0. Negative values are used to designate elements starting at the end of the array. If this parameter is not specified, the index that matches the last element in the array is used.
Output
  • If the operation is successful, the element is removed and returned.
  • If the array is empty, the "ERR array index outflow" message is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"id": [1,2,3]}' command is run in advance.

Sample command:

JSON.ARRPOP doc .id 0

Sample output:

"1"

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 the TairDoc key.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
  • index: the index in the array. The beginning index is 0. Negative values are used to designate elements starting from the end of the array. If this parameter is not specified, the index that matches the last element in the array is used.
  • json: the element that you want to add to the array.
Output
  • If the operation is successful, the number of elements in the array is returned.
  • If the array is empty, the "ERR array index outflow" message is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"id": [1,2,3]}' command is run in advance.

Sample command:

JSON.ARRINSERT doc .id 0 10 15

Sample output:

(integer) 5

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 the TairDoc key.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
Output
  • If the operation is successful, the length of the array is returned.
  • If the key does not exist, a value of -1 is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"id": [1,2,3]}' command is run in advance.

Sample command:

JSON.ARRLEN doc .id

Sample output:

(integer) 3

JSON.ARRTRIM

Item Description
Syntax JSON.ARRTRIM key path start stop
Time complexity

O(N)
Command description

Trims the array in the path of the TairDoc key. This command retains the elements in the array that are within the start value and the stop value.

Parameter
  • Key: the key that you want to manage by running this command.
  • path: the path in the key.
  • start: the start of the range in which elements are retained after a trim. The parameter value is an index value that is equal to or greater than 0. The element at the start position is retained.
  • stop: the end of the range in which elements are retained after a trim. The parameter value is an index value that is equal to or greater than 0. The element at the end position is retained.
Output
  • If the operation is successful, the length of the trimmed array is returned.
  • If the key does not exist, a value of -1 is returned.
  • Otherwise, an error message is returned.
Example

The JSON.SET doc . '{"id": [1,2,3,4,5,6]}' command is run in advance.

Sample command:

JSON.ARRTRIM doc .id 3 4

Sample output:

(integer) 2

JSON Pointer and JSONPath

TairDoc supports the JSON Pointer syntax and also supports specific JSONPath syntax. The following table compares the examples of the two syntax types.

The JSON.SET doc . '{"foo": "bar", "baz" : [1,2,3]}' command is run in advance.

JSONPointer JSONPath

Sample command:

JSON.GET doc .baz[0]

Sample output:

"1"

Sample command:

JSON.GET doc /baz/0

Sample output:

"1"

The following table shows how TairDoc supports the JSONPath and JSON Pointer syntax.

Item JSONPath JSONPointer
A root element . ""
An individual element .a.b.c /a/b/c
An array .a[2] /a/2
A combination of multiple elements .a["b.c"] /a/b.c
.a['b.c'] /a/b.c