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

Precautions

The TairDocs to be managed are 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 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 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 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
  • 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 already 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 in a path of a 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 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 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
  • 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 a 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 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
  • 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 a TairDoc key. The json-string value and JSON element must both 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.
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 in a path of a 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 length of the 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 a path of a 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 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
  • 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 a 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 at 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 a 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 a TairDoc key and 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 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:

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
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