Tair擴充資料結構Doc介紹 - ApsaraDB for Redis

TairDoc是類似RedisJSON的文檔資料結構，支援JSON資料的增刪改查。

TairDoc簡介

主要特性

完整地支援JSON標準。
部分相容JSONPath RFC draft-4標準。
說明
僅JSON.GET命令支援。
完整地支援JSONPointer文法。
文檔作為二進位樹儲存，可以快速存取JSON資料的子項目。
支援JSON到XML或YAML格式的轉換。

發布記錄

隨Tair記憶體型同時發布TairDoc，支援完整的JSONPointer文法與部分JSONPath文法（僅JSON.GET命令支援JSONPath文法）。
2022年5月17號發布1.8.4版，JSON.GET命令全面支援JSONPath文法，請將小版本升級至1.8.4及以上。
該版本新增支援Dot Wild Card Selector（節點萬用字元選取器）、Index Selector（索引選取器）與Filter Selector（條件過濾選取器）等。

前提條件

執行個體為Tair記憶體型。

說明

最新小版本將提供更豐富的功能與穩定的服務，建議將執行個體的小版本升級到最新，具體操作請參見升級小版本。如果您的執行個體為叢集架構或讀寫分離架構，請將代理節點的小版本也升級到最新，否則可能出現命令無法識別的情況。

注意事項

操作對象為Tair執行個體中的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對應值的類型，結果可能包括`boolean`、`string`、`number`、`array`、`object`、`raw`、`reference`、`const`、`null`等。
JSON.MERGE	`JSON.MERGE key path value`	將value的Json合并到指定Key的path路徑中。可對目標路徑下的值實現新增、更新、刪除等操作。
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：TairDoc的key，用於指定作為命令調用對象的TairDoc。 path：目標key的path，根項目支援`.`或`$`。 json：待新增或更新的JSON資料。 NX：當path不存在時寫入。 XX：當path存在時寫入。
傳回值	執行成功：OK。指定了XX且path不存在：nil。指定了NX且path已存在：nil。若返回`ERR could not find object to add, please check path`：表示您輸入的path有誤。其它情況返回相應的異常資訊。
樣本	命令樣本： 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 } } }' 返回樣本： `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，支援JSONPath與JSON文法，按需靈活地查詢，更多資訊請參見JSONPath介紹和JSONPointer介紹。 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對應值的類型，結果可能包括`boolean`、`string`、`number`、`array`、`object`、`raw`、`reference`、`const`、`null`等。
選項	key：TairDoc的key，用於指定作為命令調用對象的TairDoc。 path：目標key的path。
傳回值	執行成功：返回查詢到的類型。執行失敗：0。若key或path不存在：nil。其它情況返回相應的異常資訊。
樣本	提前執行`JSON.SET doc . '{"foo": "bar", "baz" : 42}'`命令。命令樣本： `JSON.TYPE doc .foo` 返回樣本： `string`

JSON.MERGE

類別	說明
文法	`JSON.MERGE key path value`
時間複雜度	O(N)
命令描述	將value的Json合并到指定Key的path路徑中。可對目標路徑下的值實現新增、更新、刪除等操作。
選項	key：TairDoc的Key，用於指定作為命令調用對象的TairDoc。 path：目標Key的path，支援部分JSONPath文法，例如`$.a.b.c`、`$.a['b']`，但不支援`$..`、`$*`等複雜運算式。 value：待合并的Json，格式相容Json Merge Patch RFC7386。
傳回值	執行成功：OK。若value有誤：parse merge patch error。其它情況返回相應的異常資訊。
樣本	提前執行`JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}'`命令。命令樣本： `JSON.MERGE doc $ '{"f1": null, "f2":{"a":3, "b":4}, "f3":[2,4,6]}'` 返回樣本： `OK` 此時，執行`JSON.GET doc .`的結果如下： `"{\"f2\":{\"a\":3,\"b\":4},\"f3\":[2,4,6]}"`

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`

JSONPath介紹

TairDoc支援JSONPath的相容文法如下表所示：

JSONPath	說明
$	根項目。
@	當前元素。
.name	子項目。
..	任意位置符合要求的元素。
*	萬用字元，表示所有子項目或數組元素。
[ ]	數組索引，索引從0開始，例如[0]；支援挑選清單，例如[0,1]，表示0和1；也支援添加元素名，例如['name']。
[start:end:step]	數組切片選取器（Array Slice Selector），表示從start開始，到end結束，按照step為步長來擷取元素，例如[0:3:1]，表示從第0位到第3位。若步長為負數，則從後向前擷取。
?...	條件過濾選取器。
()	支援運算式，優先順序為：`( ) > && > \|\|`，更多資訊，請參見JSONPath。

查詢樣本

建立JSON文檔。

命令執行個體：

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

預計返回：

OK

查詢文檔。

查詢樣本如下：

Root Selector

# 查詢整個JSON對象。
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}}}]"

Dot Selector

# 查詢store中bicycle的所有資訊。
JSON.GET dockey $.store.bicycle.*

# 預期輸出：
"["red",19.95]"

# 查詢store中bicycle的price資訊。
JSON.GET dockey $.store.bicycle.price

# 預期輸出：
"[19.95]"

Index Selector

# 查詢store中第一本book的所有資訊。
JSON.GET dockey $.store.book[0]

# 預期輸出：
"[{"category":"reference","author":"Nigel Rees","title":"Sayings of the Century","price":8.95}]"

# 查詢store中所有book的title資訊。
JSON.GET dockey "$.store.book[*]['title']"

# 預期輸出：
"["Sayings of the Century","Sword of Honour","Moby Dick","The Lord of the Rings"]"

Array Slice Selector

# 使用數組分區的方式查詢book中第1至第3本書的所有資訊，步長為1。
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}]"

Descendant Selector

# 查詢store中所有price資訊，包含book和bicycle的price資訊。
JSON.GET dockey $..price

# 預期輸出：
"[8.95,12.99,8.99,22.99,19.95]"

List Selector

# # 查詢store中第一本和第三本book的所有資訊。
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}]"

Filter Selector

# @運算式
# 查詢store中book中包含isbn元素的資訊。
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}]"


# COMP運算式
# 查詢store中price小於10的book資訊。
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}]"

# 組合運算式
# 查詢目標book資訊，條件為price為12.99或者price比bicycle的price貴或者category為reference。
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}]"

JSONPointer介紹

TairDoc支援完整的JSONPointer文法，更多資訊，請參見JavaScript Object Notation (JSON) Pointer。

樣本如下。

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

命令樣本：

# 擷取doc中.baz的第一個值。
JSON.GET doc /baz/0

返回樣本：

"1"