This topic describes the commands supported by TairDocs.

Overview

A TairDoc is a document data structure. You can use TairDoc to add, modify, query, or delete JavaScript Object Notation (JSON) data.

Key features:

  • Supports JSON standards.
  • Fully compatible with RedisJSON.
  • Supports the syntax of JSONPath and JSON Pointer.
  • Stores data in a binary tree and simplifies the retrieval of child elements.
  • Supports conversion from the JSON format to the Extensible Markup Language (XML) or YAML Ain't Markup Language (YAML) format.

Prerequisites

The commands described in this topic take effect only if the following conditions are met:

  • A performance-enhanced instance of ApsaraDB for Redis Enterprise Edition is used.
  • The TairDoc to be managed is stored on the performance-enhanced instance.

Commands

Table 1. TairDoc commands
Command Syntax Description
JSON.SET JSON.SET <key> <path> <json> [NX or XX] Writes a JSON value to a TairDoc path of a specified key. If the specified key does not exist, the path must be the root directory. If the specified key and path exist, the specified JSON value overwrites the current JSON value in the path.
JSON.GET JSON.GET <key> [PATH] [FORMAT <XML/YAML>] [ROOTNAME <root>] [ARRNAME <arr>] Retrieves JSON data from a TairDoc path of a specified key.
JSON.DEL JSON.DEL <key> [path] Deletes JSON data from a TairDoc path of a specified key. If the path is not specified, the key is deleted. This command does not take effect if the key or path does not exist.
JSON.TYPE JSON.TYPE <key> [path] Retrieves the type of JSON data from a TairDoc path of a specified key.
JSON.NUMINCRBY JSON.NUMINCRBY <key> [path] <value> Increases JSON data in a TairDoc path by a specified value. The path must exist, and both the JSON data and increased value must be of int or double type.
JSON.STRAPPEND JSON.STRAPPEND <key> [path] <json-string> Appends a string specified in json-string to the end of the string in a TairDoc path. If you do not specify the path, the root directory is used.
JSON.STRLEN JSON.STRLEN <key> [path] Retrieves the JSON value length in a TairDoc path. If you do not specify the path, the root directory is used.
JSON.ARRAPPEND JSON.ARRAPPEND <key> <path> <json> [<json> ...] Appends one or more JSON values to the end of an array in a TairDoc path.
JSON.ARRPOP JSON.ARRPOP <key> <path> [index] Removes an element specified by index from an array in a specified TairDoc path and return the removed element.
JSON.ARRINSERT JSON.ARRINSERT <key> <path> <index> <json> [<json> ...] Adds one or more JSON elements to an array in a TairDoc path. The index parameter specifies the position to which the JSON elements are added.
JSON.ARRLEN JSON.ARRLEN <key> [path] Retrieves the length of the array in a TairDoc path.
JSON.ARRTRIM JSON.ARRTRIM <key> <path> <start> <stop> Trims a JSON array in a TairDoc path. The start value and the stop value specify the range in which the JSON data is retained.
DEL DEL <key> [key ...] Deletes one or more TairDocs.

JSON.SET

  • Syntax

    JSON.SET <key> <path> <json> [NX | XX]

  • Time complexity

    O(N)

  • Description

    This command is used to write a JSON value to the path of a specified key. If the specified key does not exist, the path must be the root directory. If the specified key and path exist, the specified JSON value overwrites the current JSON value in the path.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
    • If the specified key does not exist, the path must be the root directory.
    • If the specified key and path exist, the specified JSON value overwrites the current JSON value in the path.
    json If the specified key and path exist, the specified JSON value overwrites the current JSON value in the TairDoc.
    NX Specifies that a JSON value is written only if the required path does not exist.
    XX Specifies that a JSON value is written only if the required path exists.
  • Returned values
    • OK: the operation is successful.
    • null: The operation fails. This occurs when you specify the NX or XX parameter.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"foo": "bar", "baz" : 42}'
    OK
    127.0.0.1:6379> JSON.SET doc .foo '"flower"'
    OK
    127.0.0.1:6379> JSON.GET doc .foo
    "flower"
    127.0.0.1:6379> JSON.SET doc .not-exists 123 XX
    
    127.0.0.1:6379> JSON.SET doc .not-exists 123 NX
    OK
    127.0.0.1:6379> JSON.GET doc .not-exists
    123

JSON.GET

  • Syntax

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

  • Time complexity

    O(N)

  • Description

    This command is used to retrieve JSON data from a TairDoc path of a specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
    FORMAT The format of the JSON data to be returned. Valid values: XML and YAML.
    ROOTNAME The tag that specifies a root element in an XML document.
    ARRNAME The tag that specifies an array element in an XML document.
  • Returned values
    • The JSON data stored in the path is returned if the operation is successful.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"foo": "bar", "baz" : 42}'
    OK
    127.0.0.1:6379> JSON.GET doc
    {"foo":"bar","baz":42}
    127.0.0.1:6379> JSON.GET doc .foo
    "bar"
    127.0.0.1:6379> JSON.GET doc .not-exists
    ERR pointer illegal or array index error or object type is not array or map
    
    127.0.0.1:6379> JSON.GET doc . format xml
    <? xml version="1.0" encoding="UTF-8"? ><root><foo>bar</foo><baz>42</baz></root>
    127.0.0.1:6379> JSON.GET doc . format xml rootname ROOT arrname ARRAY
    <? xml version="1.0" encoding="UTF-8"? ><ROOT><foo>bar</foo><baz>42</baz></ROOT>
    127.0.0.1:6379> JSON.GET doc . format yaml
    
    foo: bar
    baz: 42

JSON.DEL

  • Syntax

    JSON.DEL <key> [path]

  • Time complexity

    O(N)

  • Description

    This command is used to delete JSON data from a TairDoc path of a specified key. If the path is not specified, the key is deleted. This command does not take effect if the key or path does not exist.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
  • Returned values
    • 1: the operation is successful.
    • 0: the operation fails.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"foo": "bar", "baz" : 42}'
    OK
    127.0.0.1:6379> JSON.DEL doc .foo
    1
    127.0.0.1:6379> JSON.DEL doc .not-exists
    ERR old item is null for remove or replace
    
    127.0.0.1:6379> JSON.DEL not-exists
    0
    127.0.0.1:6379> JSON.GET doc
    {"baz":42}
    127.0.0.1:6379> JSON.DEL doc
    1
    127.0.0.1:6379> JSON.GET doc
    
    127.0.0.1:6379>

JSON.TYPE

  • Syntax

    JSON.TYPE <key> [path]

  • Time complexity

    O(N)

  • Description

    This command is used to retrieve the type of JSON data from a TairDoc path of a specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
  • Returned values
    • The type of JSON data is returned if the operation is successful. The type includes boolean, null, number, string, array, object, raw, reference, or const.
    • null: the specified key or path does not exist.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"foo": "bar", "baz" : 42}'
    OK
    127.0.0.1:6379> JSON.TYPE doc
    object
    127.0.0.1:6379> JSON.TYPE doc .foo
    string
    127.0.0.1:6379> JSON.TYPE doc .baz
    number
    127.0.0.1:6379> JSON.TYPE doc .not-exists
    
    127.0.0.1:6379>

JSON.NUMINCRBY

  • Syntax

    JSON.NUMINCRBY <key> [path] <value>

  • Time complexity

    O(N)

  • Description

    This command is used to increase JSON data in a TairDoc path by a specified value. The path must exist, and the JSON data and increased value must be both of the type of int or double.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
    value The increment to be added to the JSON data in the specified path.
  • Returned values
    • The increased value in the specified path is returned if the operation is successful.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"foo": "bar", "baz" : 42}'
    OK
    127.0.0.1:6379> JSON.NUMINCRBY doc .baz 1
    43
    127.0.0.1:6379> JSON.NUMINCRBY doc .baz 1.5
    44.5
    127.0.0.1:6379> JSON.NUMINCRBY doc .foo 1
    ERR node not exists or not number type
    
    127.0.0.1:6379> JSON.NUMINCRBY doc .not-exists 1
    ERR node not exists or not number type
    
    127.0.0.1:6379>

JSON.STRAPPEND

  • Syntax

    JSON.STRAPPEND <key> [path] <json-string>

  • Time complexity

    O(N)

  • Description

    This command is used to append a string specified in json-string to the end of the string in a TairDoc path. If you do not specify the path, the root directory is used.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
    json-string The string to be appended to the specified path.
  • Returned values
    • The length of the increased value in the path is returned if the operation is successful.
    • -1: the specified key does not exist.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"foo": "bar", "baz" : 42}'
    OK
    127.0.0.1:6379> JSON.STRAPPEND doc .foo rrrrr
    8
    127.0.0.1:6379> JSON.GET doc .foo
    "barrrrrr"
    127.0.0.1:6379> JSON.STRAPPEND doc .not-exists
    ERR node not exists or not string type
    
    127.0.0.1:6379> JSON.STRAPPEND not-exists abc
    -1

JSON.STRLEN

  • Syntax

    JSON.STRLEN <key> [path]

  • Time complexity

    O(N)

  • Description

    This command is used to retrieve the JSON value length in a TairDoc path. If you do not specify the path, the root directory is used.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
  • Returned values
    • The length of the value in the path is returned if the operation is successful.
    • -1: the specified key does not exist.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"foo": "bar", "baz" : 42}'
    OK
    127.0.0.1:6379> JSON.STRLEN doc .foo
    3
    127.0.0.1:6379> JSON.STRLEN doc .baz
    ERR node not exists or not string type
    
    127.0.0.1:6379> JSON.STRLEN not-exists
    -1

JSON.ARRAPPEND

  • Syntax

    JSON.ARRAPPEND <key> <path> <json> [<json> ...]

  • Time complexity

    O(M×N). M specifies the number of JSON elements to be appended and N specifies the number of elements in the array.

  • Description

    This command is used to append one or more JSON values to the end of an array in a TairDoc path.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
    json The JSON value to be appended to a specified array.
  • Returned values
    • The number of elements in the array is returned if the operation is successful. The added elements are included.
    • -1: the specified key does not exist.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"id": [1,2,3]}'
    OK
    127.0.0.1:6379> JSON.GET doc .id
    [1,2,3]
    127.0.0.1:6379> JSON.ARRAPPEND doc .id null false true
    6
    127.0.0.1:6379> JSON.GET doc .id
    [1,2,3,null,false,true]
    127.0.0.1:6379> JSON.GET doc .id.2
    3
    127.0.0.1:6379> JSON.ARRAPPEND not-exists .a 1
    -1

JSON.ARRPOP

  • Syntax

    JSON.ARRPOP <key> <path> [index]

  • Time complexity

    O(M×N). M specifies the child elements that the specified key contains and N specifies the number of elements in the array.

  • Description

    This command is used to remove an element specified by index from an array in a specified TairDoc path and return the removed element.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
    index The index of the array, which specifies the value to be removed. If you do not specify this parameter, the last value in the array is removed. A negative value specifies reverse numbering from the end of the array.
  • Returned values
    • The removed element is returned if the operation is successful.
    • An error message is returned if the array is empty: 'ERR array index outflow'.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"id": [1,2,3]}'
    OK
    127.0.0.1:6379> JSON.ARRPOP doc .id 1
    2
    127.0.0.1:6379> JSON.GET doc .id
    [1,3]
    127.0.0.1:6379> JSON.ARRPOP doc .id -1
    3
    127.0.0.1:6379> JSON.GET doc .id
    [1]
    127.0.0.1:6379> JSON.ARRPOP doc .id 10
    ERR array index outflow
    
    127.0.0.1:6379> JSON.ARRPOP doc .id
    1
    127.0.0.1:6379> JSON.ARRPOP doc .id
    ERR array index outflow
    
    127.0.0.1:6379>

JSON.ARRINSERT

  • Syntax

    JSON.ARRINSERT <key> <path> <index> <json> [<json> ...]

  • Time complexity

    O(M×N). M specifies the number of JSON elements to be appended and N specifies the number of elements in the array.

  • Description

    This command is used to add one or more JSON elements to an array in a TairDoc path. The index parameter specifies the position to which the JSON elements are added.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
    index The index of the array, which specifies the value to be removed. If you do not specify this parameter, the last value in the array is removed. A negative value specifies reverse numbering from the end of the array.
    json The JSON value to be inserted to a specified array.
  • Returned values
    • The number of elements in the array is returned if the operation is successful. The added elements are included.
    • An error message is returned if the array is empty: 'ERR array index outflow'.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"id": [2,3,5]}'
    OK
    127.0.0.1:6379> JSON.ARRINSERT doc .id 0 0 1
    5
    127.0.0.1:6379> JSON.GET doc .id
    [0,1,2,3,5]
    127.0.0.1:6379> JSON.ARRINSERT doc .id 4 4
    6
    127.0.0.1:6379> JSON.GET doc .id
    [0,1,2,3,4,5]
    127.0.0.1:6379>

JSON.ARRLEN

  • Syntax

    JSON.ARRLEN <key> [path]

  • Time complexity

    O(N)

  • Description

    This command is used to retrieve the length of the array in a TairDoc path.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
  • Returned values
    • The length of the queried array is returned if the operation is successful.
    • -1: the specified key does not exist.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"id": [2,3,5]}'
    OK
    127.0.0.1:6379> JSON.ARRLEN doc .id
    3
    127.0.0.1:6379> JSON.ARRLEN not-exists
    -1

JSON.ARRTRIM

  • Syntax

    JSON.ARRTRIM <key> <path> <start> <stop>

  • Time complexity

    O(N)

  • Description

    This command is used to trim a JSON array in a TairDoc path. The start value and the stop value specify the range in which the JSON data is retained.

  • Parameters and options
    Parameter/option Description
    key The key of the TairDoc that you want to manage.
    path The TairDoc path where you want to manage JSON data.
    start The start of the range in which elements are retained after a trim. The value is an index that starts from 0. The element at the start position is retained.
    stop The end of the range in which elements are retained after a trim. The value is an index that starts from 0. The element at the end position is retained.
  • Returned values
    • The length of the trimmed array is returned if the operation is successful.
    • -1: the specified key does not exist.
    • Otherwise, an exception is returned.
  • Example
    127.0.0.1:6379> JSON.SET doc . '{"id": [1,2,3,4,5,6]}'
    OK
    127.0.0.1:6379> JSON.ARRTRIM doc .id 3 4
    2
    127.0.0.1:6379> JSON.GET doc .id
    [4,5]
    127.0.0.1:6379> JSON.ARRTRIM doc .id 3 4
    ERR array index outflow
    
    127.0.0.1:6379> JSON.ARRTRIM doc .id -2 -5
    ERR array index outflow
    
    127.0.0.1:6379>

JSON Pointer and JSONPath

TairDoc supports the JSONPointer syntax and also supports some of the JSONPath syntax. The following table shows the syntax examples.

JSONPointer JSONPath
127.0.0.1:6379> JSON.SET doc . '{"foo": "bar", "baz" : [1,2,3]}'
OK
127.0.0.1:6379> JSON.GET doc .foo
"bar"
127.0.0.1:6379> JSON.GET doc .baz[0]
1
127.0.0.1:6379> JSON.SET doc "" '{"foo": "bar", "baz" : [1,2,3]}'
OK
127.0.0.1:6379> JSON.GET doc /foo
"bar"
127.0.0.1:6379> JSON.GET doc /baz/0
1

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

Compatible 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
Multiple elements in a path .a['b.c'] /a/b.c