Introduction to TairDoc - - Alibaba Cloud ドキュメントセンター

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

Overview

Features

Fully supports the JSON standard.
Compatible with JSONPath RFC draft-ietf-jsonpath-base version 04.
Note
Only the JSON.GET command supports this draft version.
Fully supports JSON Pointer.
Stores data in binary trees to simplify the retrieval of child elements.
Supports the conversion from the JSON format to the XML or YAML format.

Release notes

TairDoc is released along with the Tair DRAM-based instance series. TairDoc is compatible with full JSON Pointer syntax and partial JSONPath syntax. Only JSON.GET supports JSONPath syntax.
On May 17, 2022, TairDoc V1.8.4 that fully supports JSONPath syntax for the JSON.GET command was released. We recommend that you update the minor version of your instance to 1.8.4 or later.
TairDoc V1.8.4 also supports specific selectors such as the dot wildcard selector, index selector, and filter selector.

Prerequisites

A Tair DRAM-based instance is created.

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 of an instance. 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.

Usage notes

The TairDoc data that you want to manage is stored on the Tair DRAM-based 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 at a path in the key. If the key and path already exist, this command updates the element in the path in the key.
JSON.GET	`JSON.GET key path [FORMAT XML \| YAML] [ROOTNAME root] [ARRNAME arr]`	Retrieves a JSON element at a path in a TairDoc key.
JSON.DEL	`JSON.DEL key path`	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.
JSON.TYPE	`JSON.TYPE key path`	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`.
JSON.MERGE	`JSON.MERGE key path value`	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.
JSON.NUMINCRBY	`JSON.NUMINCRBY key path value`	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.
JSON.STRAPPEND	`JSON.STRAPPEND key path json-string`	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.
JSON.STRLEN	`JSON.STRLEN key path`	Retrieves the string length of a JSON element at a path in a TairDoc key. The JSON element must be of the string type.
JSON.ARRAPPEND	`JSON.ARRAPPEND key path json [json ...]`	Appends one or more JSON elements to an array at a path in a TairDoc key.
JSON.ARRPOP	`JSON.ARRPOP key path [index]`	Removes and returns the element that matches the specified index in an array at a path in a TairDoc key.
JSON.ARRINSERT	`JSON.ARRINSERT key path [index] json [json ...]`	Inserts one or more JSON elements into an array at a path before the specified index in a TairDoc key.
JSON.ARRLEN	`JSON.ARRLEN key path`	Retrieves the length of an array at a path in a TairDoc key.
JSON.ARRTRIM	`JSON.ARRTRIM key path start stop`	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.
DEL	`DEL <key> [key ...]`	Deletes one or more TairDoc keys. This is a native Redis command.

Note

The following list describes the conventions for the command syntax used in this topic:

Uppercase keyword: indicates the command keyword.
Italic text: indicates variables.
[options]: indicates that the enclosed parameters are optional. Parameters that are not enclosed by brackets must be specified.
A|B: indicates that the parameters separated by the vertical bars (|) are mutually exclusive. Only one of the parameters can be specified.
...: indicates that the parameter preceding this symbol can be repeatedly specified.

JSON.SET

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

JSON.GET

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

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

Parameter	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	The `JSON.SET doc . '{"foo": "bar", "baz" : 42}'` command is run in advance. Sample command: `JSON.TYPE doc .foo` Sample output: `string`

JSON.MERGE

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 is compatible with the JSON Merge Patch format as defined by 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	The `JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}'` command is run 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]}"`

JSON.NUMINCRBY

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

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

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

Parameter	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 one or more 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	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

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

Parameter	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 one or more 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	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

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

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

JSONPath

The following table describes the elements of JSONPath syntax supported by TairDoc.

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. Example: [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.

Examples

Create a JSON document.

Sample command:

JSON.SET dockey $
'{
    "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
        }
    },
    "expensive": 10
}'

Expected output:

OK

Query the document.

Sample queries:

Root Selector

# Query the entire JSON document. 
JSON.GET dockey $

# Expected output:
"[{"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}}}]"

Dot Selector

# Query all information about the bicycle in the store. 
JSON.GET dockey $.store.bicycle.*

# Expected output:
"["red",19.95]"

# Query the price of the bicycle. 
JSON.GET dockey $.store.bicycle.price

# Expected output:
"[19.95]"

Index Selector

# Query all information about the first book in the store. 
JSON.GET dockey $.store.book[0]

# Expected output:
"[{"category":"reference","author":"Nigel Rees","title":"Sayings of the Century","price":8.95}]"

# Query the titles of all books in the store. 
JSON.GET dockey "$.store.book[*]['title']"

# Expected output:
"["Sayings of the Century","Sword of Honour","Moby Dick","The Lord of the Rings"]"

Array Slice Selector

# Query all information about the first three books by using the array slice selector in increments of 1. 
JSON.GET dockey $.store.book[0:2:1]

# Expected output:
"[{"category":"reference","author":"Nigel Rees","title":"Sayings of the Century","price":8.95},{"category":"fiction","author":"Herman Melville","title":"Moby Dick","isbn":"0-553-21311-3","price":8.99},{"category":"fiction","author":"Evelyn Waugh","title":"Sword of Honour","price":12.99}]"

Descendant Selector

# Query all the values of the price element in the store, including those of books and bicycles. 
JSON.GET dockey $..price

# Expected output:
"[8.95,12.99,8.99,22.99,19.95]"

List Selector

# # Query all information about the first and third books in the store. 
JSON.GET dockey $.store.book[0,2]

# Expected output:
"[{"category":"reference","author":"Nigel Rees","title":"Sayings of the Century","price":8.95},{"category":"fiction","author":"Herman Melville","title":"Moby Dick","isbn":"0-553-21311-3","price":8.99}]"

Filter Selector

# An @ expression.
# Query the information about books that have the isbn element in the store. 
JSON.GET dockey $.store.book[?(@.isbn)]
# Expected output:
"[{"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}]"


# A COMP expression.
# Query the information about books whose prices are less than 10. 
JSON.GET dockey '$.store.book[?(@.price < 10)]'
# Expected output:
"[{"category":"reference","author":"Nigel Rees","title":"Sayings of the Century","price":8.95},{"category":"fiction","author":"Herman Melville","title":"Moby Dick","isbn":"0-553-21311-3","price":8.99}]"

# A combined expression.
# Query the information about books whose prices are equal to 12.99 or greater than 19.95 or whose values of the category element are reference. 
JSON.GET dockey "$..book[?((@.price == 12.99 || @.price > $.store.bicycle.price) || @.category == 'reference')]"
# Expected output:
"[{"category":"reference","author":"Nigel Rees","title":"Sayings of the Century","price":8.95},{"category":"fiction","author":"J. R. R. Tolkien","title":"The Lord of the Rings","isbn":"0-395-19395-8","price":22.99},{"category":"fiction","author":"Evelyn Waugh","title":"Sword of Honour","price":12.99}]"

JSONPointer

TairDoc supports full JSONPointer syntax. For more information, see JavaScript Object Notation (JSON) Pointer.

The following code shows an example:

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

Sample command:

# Obtain the first value of the .baz element in doc. 
JSON.GET doc /baz/0

Sample output:

"1"