本章节介绍TairDoc数据支持的命令。

TairDoc简介

TairDoc是一种文档数据结构，支持JSON数据的增删改查。

主要特性：

  • 完整地支持JSON标准。
  • 完全兼容RedisJSON。
  • 支持JSONPointer和JSONPath两种语法。
  • 文档作为二进制树存储，可以快速访问JSON数据的子元素。
  • 支持JSON到XML或YAML格式的转换。

使用前提

请注意，本章节介绍的命令只有在满足以下条件时才能生效。

  • Redis实例为云Redis企业版性能增强型实例。
  • 操作对象为性能增强型实例中的TairDoc数据。

命令列表

表 1. TairDoc命令
命令 语法 说明
JSON.SET JSON.SET <key> <path> <json> [NX or XX] 存储JSON的值在key的path中。对于不存在的key，path必须是root。对于已经存在的key，当path存在时，替换掉目前的JSON值。
JSON.GET JSON.GET <key> [PATH] [FORMAT <XML/YAML>] [ROOTNAME <root>] [ARRNAME <arr>] 获取一个TairDoc在path中存储的JSON数据。
JSON.DEL JSON.DEL <key> [path] 删除path对应的JSON数据。如果未指定path，则删除key。不存在的key和不存在的path将会被忽略。
JSON.TYPE JSON.TYPE <key> [path] 获取path对应的值的类型。
JSON.NUMINCRBY JSON.NUMINCRBY <key> [path] <value> 将path对应的值增加value。path必须存在且path对应的值和value必须是都是int或double类型的值。
JSON.STRAPPEND JSON.STRAPPEND <key> [path] <json-string> 将json-string中的字符串添加到path对应的字符串类型的值中。如果未设置path，默认为root。
JSON.STRLEN JSON.STRLEN <key> [path] 获取path对应值的长度。如果未设置path，默认为root。
JSON.ARRAPPEND JSON.ARRAPPEND <key> <path> <json> [<json> ...] 将JSON插入到path对应的array最后，JSON可以是多个。
JSON.ARRPOP JSON.ARRPOP <key> <path> [index] 移除并返回path对应的数组中index位置的元素。
JSON.ARRINSERT JSON.ARRINSERT <key> <path> <index> <json> [<json> ...] 将JSON插入到path对应的数组中，原有元素会往后移动。
JSON.ARRLEN JSON.ARRLEN <key> [path] 获取path对应数组的长度。
JSON.ARRTRIM JSON.ARRTRIM <key> <path> <start> <stop> 按照start和stop指定的范围修剪数组。
DEL DEL <key> [key ...] 使用原生Redis的DEL命令可以删除一条或多条TairDoc数据。

JSON.SET

  • 语法

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

  • 时间复杂度

    O(N)

  • 命令描述

    存储JSON的值在key的path中。对于不存在的key，path必须是root。对于已经存在的key，当path存在时，替换掉目前的JSON值。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
    • 如果key不存在，path必须为root。
    • 如果key存在，当path存在时，替换当前的JSON值。
    json 如果key存在，当path存在时，用JSON替换TairDoc中当前的JSON数据。
    NX 当path不存在时写入。
    XX 当path存在时写入。
  • 返回值
    • 成功：OK。
    • 指定了NX或XX时失败：null。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

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

  • 时间复杂度

    O(N)

  • 命令描述

    获取一个TairDoc在path中存储的JSON数据。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
    FORMAT 指定返回的JSON格式，支持XML或YAML。
    ROOTNAME 指定XML语法ROOT元素的标签。
    ARRNAME 指定XML语法ARRAY元素的标签。
  • 返回值
    • 成功：返回path中存储的JSON。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

    JSON.DEL <key> [path]

  • 时间复杂度

    O(N)

  • 命令描述

    删除path对应的JSON数据。如果未指定path，则删除key。不存在的key和不存在的path将会被忽略。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
  • 返回值
    • 成功：1。
    • 失败：0。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

    JSON.TYPE <key> [path]

  • 时间复杂度

    O(N)

  • 命令描述

    获取path对应的值的类型。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
  • 返回值
    • 成功：返回查询到的类型，可能的结果包括："boolean"、"null"、 "number"、"string"、"array"、"object"、"raw"、"reference"、"const"。
    • key或者path不存在：null。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

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

  • 时间复杂度

    O(N)

  • 命令描述

    将path对应的值增加value。path必须存在且path对应的值和value必须是都是int或double类型的值。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
    value 需要为path的值增加的数值。
  • 返回值
    • 成功：返回操作完成后path对应的值。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

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

  • 时间复杂度

    O(N)

  • 命令描述

    将json-string中的字符串添加到path对应的字符串类型的值中。如果未设置path，默认为root。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
    json-string 需要添加到path对应值的字符串。
  • 返回值
    • 成功：返回path对应的字符串扩展后的长度。
    • key不存在：-1。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

    JSON.STRLEN <key> [path]

  • 时间复杂度

    O(N)

  • 命令描述

    获取path对应值的长度。如果未设置path，默认为root。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
  • 返回值
    • 成功：返回path对应值的长度。
    • key不存在：-1。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

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

  • 时间复杂度

    O(M*N)，M是需要插入的元素（json）数量，N是数组元素数量。

  • 命令描述

    将JSON插入到path对应的array最后，JSON可以是多个。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
    json 需要插入的数据。
  • 返回值
    • 成功：返回操作完成后array中元素数量。
    • key不存在：-1。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

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

  • 时间复杂度

    O(M*N)，M是key包含的子元素，N是数组元素数量。

  • 命令描述

    移除并返回path对应的数组中index位置的元素。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
    index 数组的索引，不传默认为最后一个元素，负数表示反向取值。
  • 返回值
    • 成功：返回数组相应的节点。
    • 数组为空数组：‘ERR array index outflow’。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

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

  • 时间复杂度

    O(M*N)，M是要插入的元素（json）数量，N是数组元素数量。

  • 命令描述

    将JSON插入到path对应的数组中，原有元素会往后移动。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
    index 数组的索引，不传默认为最后一个元素，负数表示反向取值。
    json 需要插入的数据。
  • 返回值
    • 成功：返回操作完成后数组中元素的个数。
    • 数组为空数组：‘ERR array index outflow’。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

    JSON.ARRLEN <key> [path]

  • 时间复杂度

    O(N)

  • 命令描述

    获取path对应数组的长度。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
  • 返回值
    • 成功：数组的长度。
    • key不存在：-1。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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

  • 语法

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

  • 时间复杂度

    O(N)

  • 命令描述

    按照start和stop指定的范围修剪数组。

  • 参数及选项说明
    参数/选项 说明
    key TairDoc的key，用于指定作为命令调用对象的TairDoc。
    path TairDoc的path。
    start 修剪的开始位置，取值为从0开始的一个索引值，修剪后的数组包含该位置的元素。
    stop 修剪的结束位置，取值为从0开始的一个索引值，修剪后的数组包含该位置的元素。
  • 返回值
    • 成功：操作完成后数组的长度。
    • key不存在：-1。
    • 其它情况返回相应的异常信息。
  • 使用示例 
    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>

JSONPointer和JSONPath

TairDoc在支持JSONPointer的基础上支持了JSONPath的部分语法，示例如下：

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

具体的兼容方式如下表所示。

兼容项 JSONPath JSONPointer
根元素 . “”
获取元素 .a.b.c /a/b/c
数组 .a[2] /a/2
整体获取 .a["b.c"] /a/b.c
整体获取 .a['b.c'] /a/b.c