TairDoc是一种完全兼容RedisJSON的文档数据结构,支持JSON数据的增删改查。

主要特性

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

前提条件

实例为Tair(Redis企业版)性能增强型
说明 最新小版本将提供更丰富的功能与稳定的服务,建议将实例的小版本升级到最新,具体操作请参见升级小版本。若实例为集群架构读写分离架构,请将代理节点的小版本也升级到最新,避免代理节点无法识别部分命令。

注意事项

操作对象为性能增强型实例中的TairDoc数据。

命令列表

表 1. TairDoc命令
命令 语法 说明
JSON.SET JSON.SET key path json [NX | XX]

创建key并将JSON的值存储在对应的path中,若key及目标path已经存在,则更新对应的JSON值。

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

获取目标key、path中存储的JSON数据。

JSON.DEL JSON.DEL key path

删除目标key中path对应的JSON数据,若未指定path,则删除key。若指定的key不存在或path不存在,则忽略。

JSON.TYPE JSON.TYPE key path

获取目标key中path对应值的类型,结果可能包括booleanstringnumberarrayobjectrawreferenceconstnull等。

JSON.NUMINCRBY JSON.NUMINCRBY key path value

对目标key中path对应的值增加value,path对应的值和待增加的value必须是int或double类型。

JSON.STRAPPEND JSON.STRAPPEND key path json-string

在指定path对应值中添加json-string字符串,path对应值的类型也需要为字符串。

JSON.STRLEN JSON.STRLEN key path

获取目标key中path对应值的字符串长度,path对应值的类型需要为字符串。

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

在指定path对应数组(array)的末尾添加JSON数据,支持添加多个JSON。

JSON.ARRPOP JSON.ARRPOP key path [index]

移除并返回path对应数组(array)中指定位置(index)的元素。

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

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

JSON.ARRLEN JSON.ARRLEN key path

获取path对应数组(array)的长度。

JSON.ARRTRIM JSON.ARRTRIM key path start stop

修剪目标key的path对应的数组(array),保留start至stop范围内的数据。

DEL DEL <key> [key ...] 使用原生Redis的DEL命令可以删除一条或多条TairDoc数据。
说明 本文的命令语法定义如下:
  • 大写关键字:命令关键字。
  • 斜体:变量。
  • [options]:可选参数,不在括号中的参数为必选。
  • A|B:该组参数互斥,请进行二选一或多选一。
  • ...:前面的内容可重复。

JSON.SET

类别 说明
语法 JSON.SET key path json [NX | XX]
时间复杂度

O(N)

命令描述

创建key并将JSON的值存储在对应的path中,若key及目标path已经存在,则更新对应的JSON值。

说明 若key不存在,path必须是root(即.)。
选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
  • json:待新增或更新的JSON数据。
  • NX:当path不存在时写入。
  • XX:当path存在时写入。
返回值
  • 执行成功:OK。
  • 指定了XX且path不存在:nil。
  • 指定了NX且path已存在:nil。
  • 其它情况返回相应的异常信息。
示例

命令示例:

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

返回示例:

OK

JSON.GET

类别 说明
语法 JSON.GET key path [FORMAT XML | YAML] [ROOTNAME root] [ARRNAME arr]
时间复杂度

O(N)

命令描述

获取目标key、path中存储的JSON数据。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
  • FORMAT:指定返回的JSON格式,支持XML、YAML格式。
  • ROOTNAME :指定XML语法ROOT元素的标签。
  • ARRNAME:指定XML语法ARRAY元素的标签。
说明 ROOTNAME与ARRNAME参数需在指定FORMAT参数为XML时配合使用。
返回值
  • 执行成功:对应的JSON数据。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"foo": "bar", "baz" : 42}'命令。

命令示例:

JSON.GET doc . FORMAT XML ROOTNAME ROOT ARRNAME ARR

返回示例:

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

JSON.DEL

类别 说明
语法 JSON.DEL key path
时间复杂度

O(N)

命令描述

删除目标key中path对应的JSON数据,若未指定path,则删除key。若指定的key不存在或path不存在,则忽略。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
返回值
  • 执行成功:1。
  • 执行失败:0。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"foo": "bar", "baz" : 42}'命令。

命令示例:

JSON.DEL doc .foo

返回示例:

(integer) 1

JSON.TYPE

类别 说明
语法 JSON.TYPE key path
时间复杂度

O(N)

命令描述

获取目标key中path对应值的类型,结果可能包括booleanstringnumberarrayobjectrawreferenceconstnull等。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
返回值
  • 执行成功:返回查询到的类型。
  • 执行失败:0。
  • 若key或path不存在:nil。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"foo": "bar", "baz" : 42}'命令。

命令示例:

JSON.TYPE doc .foo

返回示例:

string

JSON.NUMINCRBY

类别 说明
语法 JSON.NUMINCRBY key path value
时间复杂度

O(N)

命令描述

对目标key中path对应的值增加value,path对应的值和待增加的value必须是int或double类型。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
  • value:待增加的数值。
返回值
  • 执行成功:返回操作完成后path对应的值。
  • 若key或path不存在:error。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"foo": "bar", "baz" : 42}'命令。

命令示例:

JSON.NUMINCRBY doc .baz 10

返回示例:

"52"

JSON.STRAPPEND

类别 说明
语法 JSON.STRAPPEND key path json-string
时间复杂度

O(N)

命令描述

在指定path对应值中添加json-string字符串,path对应值的类型也需要为字符串。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
  • json-string:待添加到path对应值的字符串。
返回值
  • 执行成功:返回操作完成后path对应值的字符串长度。
  • key不存在:-1。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"foo": "bar", "baz" : 42}'命令。

命令示例:

JSON.STRAPPEND doc .foo rrrrr

返回示例:

(integer) 8

JSON.STRLEN

类别 说明
语法 JSON.STRLEN key path
时间复杂度

O(N)

命令描述

获取目标key中path对应值的字符串长度,path对应值的类型需要为字符串。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
返回值
  • 执行成功:返回path对应值的字符串长度。
  • key不存在:-1。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"foo": "bar", "baz" : 42}'命令。

命令示例:

JSON.STRLEN doc .foo

返回示例:

(integer) 3

JSON.ARRAPPEND

类别 说明
语法 JSON.ARRAPPEND key path json [json ...]
时间复杂度

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

命令描述

在指定path对应数组(array)的末尾添加JSON数据,支持添加多个JSON。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
  • json:需要插入的数据。
返回值
  • 执行成功:返回操作完成后数组(array)中的元素数量。
  • key不存在:-1。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"id": [1,2,3]}'命令。

命令示例:

JSON.ARRAPPEND doc .id null false true

返回示例:

(integer) 6

JSON.ARRPOP

类别 说明
语法 JSON.ARRPOP key path [index]
时间复杂度

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

命令描述

移除并返回path对应数组(array)中指定位置(index)的元素。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
  • index:数组的索引,起始下标为0,负数表示反向取值,若不传该参数默认为最后一个元素。
返回值
  • 执行成功:移除并返回该元素。
  • 数组为空数组:‘ERR array index outflow’。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"id": [1,2,3]}'命令。

命令示例:

JSON.ARRPOP doc .id 0

返回示例:

"1"

JSON.ARRINSERT

类别 说明
语法 JSON.ARRINSERT key path [index] json [json ...]
时间复杂度

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

命令描述

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

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
  • index:数组的索引,起始下标为0,负数表示反向取值,若不传该参数默认为最后一个元素。
  • json:需要插入的数据。
返回值
  • 执行成功:返回操作完成后数组(array)中的元素数量。
  • 数组为空数组:‘ERR array index outflow’。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"id": [1,2,3]}'命令。

命令示例:

JSON.ARRINSERT doc .id 0 10 15

返回示例:

(integer) 5

JSON.ARRLEN

类别 说明
语法 JSON.ARRLEN key path
时间复杂度

O(N)

命令描述

获取path对应数组(array)的长度。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
返回值
  • 执行成功:数组(array)的长度。
  • key不存在:-1。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"id": [1,2,3]}'命令。

命令示例:

JSON.ARRLEN doc .id

返回示例:

(integer) 3

JSON.ARRTRIM

类别 说明
语法 JSON.ARRTRIM key path start stop
时间复杂度

O(N)

命令描述

修剪目标key的path对应的数组(array),保留start至stop范围内的数据。

选项
  • key:TairDoc的key,用于指定作为命令调用对象的TairDoc。
  • path:目标key的path。
  • start:修剪的开始位置,取值为从0开始的一个索引值,修剪后的数组包含该位置的元素。
  • stop:修剪的结束位置,取值为从0开始的一个索引值,修剪后的数组包含该位置的元素。
返回值
  • 执行成功:返回操作完成后数组的长度。
  • key不存在:-1。
  • 其它情况返回相应的异常信息。
示例

提前执行JSON.SET doc . '{"id": [1,2,3,4,5,6]}'命令。

命令示例:

JSON.ARRTRIM doc .id 3 4

返回示例:

(integer) 2

JSONPointer和JSONPath

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

提前执行JSON.SET doc . '{"foo": "bar", "baz" : [1,2,3]}'命令。

JSONPointer JSONPath

命令示例:

JSON.GET doc .baz[0]

返回示例:

"1"

命令示例:

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