本章节介绍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