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
Main 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.
- TairDoc was released with the DRAM-based instance series of Tair. TairDoc fully supports JSON Pointer and partly supports JSONPath syntax. Only the JSON.GET command 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
Precautions
The TairDoc data to be managed is stored on Tair DRAM-based instances.
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 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.DEL key path | Retrieves the type of the JSON element from the path in the TairDoc key. Element types include |
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. This is a native Redis command. |
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. |
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 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 |
|
Output |
|
Example | The Sample command:
Sample output:
|
JSON.TYPE
Item | Description |
---|---|
Syntax | JSON.DEL 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 |
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 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 |
|
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 the TairDoc key. The json-string value and JSON element both must 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 from the path of the 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 the path of the 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 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 |
|
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 the 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 the 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 the TairDoc key. This command retains the elements in the array that are within the start value and the stop value. |
Parameter |
|
Output |
|
Example | The Sample command:
Sample output:
|
JSONPath
The following table describes the elements of JSONPath syntax supported by TairDoc.
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. |
- 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 query:
# 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}}}]"
# 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]"
# 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"]"
# Query all information about the first three books by using the array slice selector with 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}]"
# 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]"
# # Query all information about the first and third books. 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}]"
# An @ expression. # Query the information about books that have the isbn element. 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 complete JSONPointer syntax. For more information, see JavaScript Object Notation (JSON) Pointer.
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"