Tair (Redis® OSS-Compatible):Doc

Prerequisites

Before you begin, make sure you have:

• A Tair DRAM-based instance

• Instance minor version 1.8.4 or later (required for full JSONPath support via JSON.GET)

To update your instance to the latest minor version, see Update the minor version of an instance.

For cluster or read/write splitting instances, update proxy nodes to the latest minor version to make sure all commands work as expected.

Command list

Syntax conventions used in this reference:

• UPPERCASE: command keyword

• _italic_: variable

• [option]: optional parameter

• A | B: mutually exclusive options

• ...: parameter can be repeated

JSON.SET

Syntax: JSON.SET key path json [NX | XX]

Creates a TairDoc key and stores a JSON element at the specified path. If the key and path already exist, updates the element.

Parameters:

Return values:

Example — create a JSON document:

The following command creates a doc key at the root path ($) and stores a bookstore document with four books and a bicycle:

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

Expected output:

OK

JSON.GET

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

Retrieves the JSON element at the specified path. Supports both JSONPath and JSON Pointer syntax.

Parameters:

Return values:

Example — retrieve a document as XML:

First, create the document:

JSON.SET doc . '{"foo": "bar", "baz" : 42}'

Then retrieve it as XML, specifying ROOT as the root tag name and ARR as the array tag name:

JSON.GET doc . FORMAT XML ROOTNAME ROOT ARRNAME ARR

Expected output:

"<?xml version=\"1.0\" encoding=\"UTF-8\"?><ROOT><foo>bar</foo><baz>42</baz></ROOT>"

JSON.DEL

Syntax: JSON.DEL key path

Deletes the JSON element at the specified path. If no path is given, deletes the entire key. Silently does nothing if the key or path does not exist.

Parameters:

Return values:

Example — delete a field:

First, create the document:

JSON.SET doc . '{"foo": "bar", "baz" : 42}'

Delete the foo field:

JSON.DEL doc .foo

Expected output — 1 indicates the element was deleted:

(integer) 1

JSON.TYPE

Syntax: JSON.TYPE key path

Returns the type of the JSON element at the specified path.

Parameters:

Return values:

Example — get the type of a field:

First, create the document:

JSON.SET doc . '{"foo": "bar", "baz" : 42}'

Get the type of the foo field ("bar" is a string):

JSON.TYPE doc .foo

Expected output:

string

JSON.MERGE

Syntax: JSON.MERGE key path value

Merges a JSON value into the specified path. Supports adding new values, updating existing values, and deleting values at the specified path.

Parameters:

Return values:

Example — add, update, and delete values in one operation:

First, create the document:

JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}'

Merge changes: set f1 to null (deletes it), update f2.a and add f2.b, and add a new f3 array:

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

Expected output:

OK

Verify the result with JSON.GET doc .. The f1 key is removed because setting a field to null in a merge patch deletes it:

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

JSON.NUMINCRBY

Syntax: JSON.NUMINCRBY key path value

Increments the numeric JSON element at the specified path. Both the existing element and the increment value must be of the same type — either integer or double.

Parameters:

Return values:

Example — increment a numeric field:

First, create the document:

JSON.SET doc . '{"foo": "bar", "baz" : 42}'

Increment baz by 10 (42 + 10 = 52):

JSON.NUMINCRBY doc .baz 10

Expected output:

"52"

JSON.STRAPPEND

Syntax: JSON.STRAPPEND key path json-string

Appends a string to the JSON string element at the specified path. Both the existing element and the appended value must be of the string type.

Parameters:

Return values:

Example — append to a string field:

First, create the document:

JSON.SET doc . '{"foo": "bar", "baz" : 42}'

Append rrrrr to foo — "bar" becomes "barrrrrr", which has 8 characters:

JSON.STRAPPEND doc .foo rrrrr

Expected output:

(integer) 8

JSON.STRLEN

Syntax: JSON.STRLEN key path

Returns the character length of the JSON string element at the specified path. The element must be of the string type.

Parameters:

Return values:

Example — get the length of a string field:

First, create the document:

JSON.SET doc . '{"foo": "bar", "baz" : 42}'

Get the length of foo — "bar" has 3 characters:

JSON.STRLEN doc .foo

Expected output:

(integer) 3

JSON.ARRAPPEND

Syntax: JSON.ARRAPPEND key path json [json ...]

Appends one or more JSON elements to the end of an array. Time complexity is O(M×N), where M is the number of elements to append and N is the current array length.

Parameters:

Return values:

Example — append multiple elements to an array:

First, create the document:

JSON.SET doc . '{"id": [1,2,3]}'

Append null, false, and true to the id array. The array grows from 3 to 6 elements:

JSON.ARRAPPEND doc .id null false true

Expected output:

(integer) 6

JSON.ARRPOP

Syntax: JSON.ARRPOP key path [index]

Removes and returns the element at the specified index in an array. Time complexity is O(M×N), where M is the number of child elements in the key and N is the array length.

Parameters:

Return values:

Example — remove the first element of an array:

First, create the document:

JSON.SET doc . '{"id": [1,2,3]}'

Remove and return the element at index 0 (the first element, 1):

JSON.ARRPOP doc .id 0

Expected output:

"1"

JSON.ARRINSERT

Syntax: JSON.ARRINSERT key path [index] json [json ...]

Inserts one or more JSON elements into an array before the specified index. Time complexity is O(M×N), where M is the number of elements to insert and N is the current array length.

Parameters:

Return values:

Example — insert elements at the beginning of an array:

First, create the document:

JSON.SET doc . '{"id": [1,2,3]}'

Insert 10 and 15 before index 0. The resulting array is [10, 15, 1, 2, 3]:

JSON.ARRINSERT doc .id 0 10 15

Expected output:

(integer) 5

JSON.ARRLEN

Syntax: JSON.ARRLEN key path

Returns the number of elements in an array.

Parameters:

Return values:

Example — get the length of an array:

First, create the document:

JSON.SET doc . '{"id": [1,2,3]}'

Get the number of elements in the id array:

JSON.ARRLEN doc .id

Expected output:

(integer) 3

JSON.ARRTRIM

Syntax: JSON.ARRTRIM key path start stop

Trims an array so that only elements within the [start, stop] range (inclusive) remain. All elements outside this range are removed.

Parameters:

Return values:

Example — trim an array to a subrange:

First, create the document:

JSON.SET doc . '{"id": [1,2,3,4,5,6]}'

Trim the array to keep only elements at index 3 and 4 (values 4 and 5). Elements outside this range are discarded:

JSON.ARRTRIM doc .id 3 4

Expected output — 2 elements remain:

(integer) 2

JSONPath

JSON.GET supports the JSONPath RFC draft-4 syntax for flexible queries. Full JSONPath support requires version 1.8.4 or later.

Supported selectors:

Query examples:

The following examples use this bookstore document. Create it first:

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

JSON.GET 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}}}]"

JSON.GET dockey $.store.bicycle.*

"["red",19.95]"

JSON.GET dockey $.store.bicycle.price

"[19.95]"

JSON.GET dockey $.store.book[0]

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

JSON.GET dockey "$.store.book[*]['title']"

"["Sayings of the Century","Sword of Honour","Moby Dick","The Lord of the Rings"]"

JSON.GET dockey $.store.book[0:2:1]

"[{"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}]"

JSON.GET dockey $..price

"[8.95,12.99,8.99,22.99,19.95]"

JSON.GET dockey $.store.book[0,2]

"[{"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}]"

JSON.GET dockey $.store.book[?(@.isbn)]

"[{"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}]"

JSON.GET dockey '$.store.book[?(@.price < 10)]'

"[{"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}]"

JSON.GET dockey "$..book[?((@.price == 12.99 || @.price > $.store.bicycle.price) || @.category == 'reference')]"

"[{"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}]"

JSON Pointer

TairDoc fully supports the JSON Pointer syntax (RFC 6901). Use /-delimited paths to navigate into a document.

Example — retrieve a nested array element:

First, create the document:

JSON.SET doc . '{"foo": "bar", "baz" : [1,2,3]}'

Retrieve the first element of the baz array using JSON Pointer path /baz/0:

JSON.GET doc /baz/0

Expected output:

"1"