Tair (Redis® OSS-Compatible):Doc

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 at a path in the key. If the key and path already exist, this command updates the element in the path in the key.

Parameter

• key: the key that you want to manage by running this command.

• path: the path in the key. The root element supports . and $.

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

• If the specified path is invalid, ERR could not find object to add, please check path is returned.

• Otherwise, an error message is returned.

Example

Sample command:

JSON.SET doc $ '{ "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 } ], "bicycle": { "color": "red", "price": 19.95 } } }'

Sample output:

OK

Item

Description

Syntax

JSON.GET key path [FORMAT XML | YAML] [ROOTNAME root] [ARRNAME arr]

Time complexity

O(N)

Command description

Retrieves a JSON element at a path in a TairDoc key.

Parameter

• key: the key that you want to manage by running this command.

• path: the path in the key. This parameter supports JSONPath syntax and JSON syntax for flexible query. For more information, see the "JSONPath" and "JSONPointer" sections of this topic.

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

Output

• If the operation is successful, the JSON element is returned.

• Otherwise, an error message is returned.

Example

Run the JSON.SET doc . '{"foo": "bar", "baz" : 42}' command 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>"

Item

Description

Syntax

JSON.DEL key path

Time complexity

O(N)

Command description

Deletes a JSON element from a 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

Run the JSON.SET doc . '{"foo": "bar", "baz" : 42}' command in advance.

Sample command:

JSON.DEL doc .foo

Sample output:

(integer) 1

Item

Description

Syntax

JSON.TYPE key path

Time complexity

O(N)

Command description

Retrieves the type of a JSON element at a 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

Run the JSON.SET doc . '{"foo": "bar", "baz" : 42}' command in advance.

Sample command:

JSON.TYPE doc .foo

Sample output:

string

Item

Description

Syntax

JSON.MERGE key path value

Time complexity

O(N)

Command description

Merges a JSON value into the JSON data stored at a path in a TairDoc key. This command allows you to perform operations such as adding new values, updating existing values, and deleting values at the specified path.

Parameter

• key: the key that you want to manage by running this command.

• path: the path in the key. This parameter supports partial JSONPath syntax such as $.a.b.c and $.a['b'], but does not support complex expressions such as $.. and $*.

• value: the JSON value to be merged, which supports the JSON Merge Patch format defined in RFC 7386.

Output

• If the operation is successful, OK is returned.

• If the specified value is invalid, an error indicating a problem with parsing the merge patch occurs.

• Otherwise, an error message is returned.

Example

Run the JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}' command in advance.

Sample command:

JSON.MERGE doc $ '{"f1": null, "f2":{"a":3, "b":4}, "f3":[2,4,6]}'

Sample output:

OK

JSON.GET doc . command output:

"{\"f2\":{\"a\":3,\"b\":4},\"f3\":[2,4,6]}"

Item

Description

Syntax

JSON.NUMINCRBY key path value

Time complexity

O(N)

Command description

Increments a JSON value at a path in a TairDoc key by the specified value. The JSON value and the value to increment must be both of the integer or double type.

Parameter

• key: the key that you want to manage by running this command.

• path: the path in the key.

• value: the value to increment.

Output

• If the operation is successful, the resulting value at the path is returned.

• If the key or path does not exist, an error occurs.

• Otherwise, an error message is returned.

Example

Run the JSON.SET doc . '{"foo": "bar", "baz" : 42}' command in advance.

Sample command:

JSON.NUMINCRBY doc .baz 10

Sample output:

"52"

Item

Description

Syntax

JSON.STRAPPEND key path json-string

Time complexity

O(N)

Command description

Appends the json-string value to a JSON value at a path in a TairDoc key. The json-string value and the JSON value must be both 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 string that you want to append to the JSON string at the path.

Output

• If the operation is successful, the new length of the string at the path is returned.

• If the key does not exist, a value of -1 is returned.

• Otherwise, an error message is returned.

Example

Run the JSON.SET doc . '{"foo": "bar", "baz" : 42}' command in advance.

Sample command:

JSON.STRAPPEND doc .foo rrrrr

Sample output:

(integer) 8

Item

Description

Syntax

JSON.STRLEN key path

Time complexity

O(N)

Command description

Retrieves the string length of a JSON element at a path in 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 string length of the JSON element at the path is returned.

• If the key does not exist, a value of -1 is returned.

• Otherwise, an error message is returned.

Example

Run the JSON.SET doc . '{"foo": "bar", "baz" : 42}' command in advance.

Sample command:

JSON.STRLEN doc .foo

Sample output:

(integer) 3

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 append and N specifies the number of elements in the array.

Command description

Appends JSON elements to an array at a path in a TairDoc key.

Parameter

• key: the key that you want to manage by running this command.

• path: the path in the key.

• json: the elements that you want to append 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

Run the JSON.SET doc . '{"id": [1,2,3]}' command in advance.

Sample command:

JSON.ARRAPPEND doc .id null false true

Sample output:

(integer) 6

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 specified index in an array at a path in 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 start 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.

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

Run the JSON.SET doc . '{"id": [1,2,3]}' command in advance.

Sample command:

JSON.ARRPOP doc .id 0

Sample output:

"1"

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 insert and N specifies the number of elements in the array.

Command description

Inserts JSON elements into an array at a path before the specified index in 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 start 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 elements that you want to insert into 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

Run the JSON.SET doc . '{"id": [1,2,3]}' command in advance.

Sample command:

JSON.ARRINSERT doc .id 0 10 15

Sample output:

(integer) 5

Item

Description

Syntax

JSON.ARRLEN key path

Time complexity

O(N)

Command description

Retrieves the length of an array at a path in 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

Run the JSON.SET doc . '{"id": [1,2,3]}' command in advance.

Sample command:

JSON.ARRLEN doc .id

Sample output:

(integer) 3

Item

Description

Syntax

JSON.ARRTRIM key path start stop

Time complexity

O(N)

Command description

Trims an array at a path in a TairDoc key. This command retains the elements in the array that are within the range of 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 array after the trim is returned.

• If the key does not exist, a value of -1 is returned.

• Otherwise, an error message is returned.

Example

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

Sample command:

JSON.ARRTRIM doc .id 3 4

Sample output:

(integer) 2

JSONPath element

Description

$

The root element.

@

The current element.

.name

A child element.

..

An element whose position meets the requirements.

*

A wildcard that can represent all child elements or array elements.

[ ]

The index of arrays. The index starts from 0. Example: [0]. Lists and element names are supported for this element. Examples: [0,1] and ['name'].

[start:end:step]

The array slice selector. Elements are obtained from start to end in increments of step. For example, [0:3:1] indicates that elements are selected from the zeroth one to the third one. In this example, if the increment is -1, elements are selected from the third one to the zeroth one.

?...

The filter selector.

()

Supports expressions with the priority sequence of ( ) > && > ||. For more information, see JSONPath.