Doc
TairDoc是類似RedisJSON的文檔數(shù)據(jù)結(jié)構(gòu),支持JSON數(shù)據(jù)的增刪改查。
TairDoc簡介
主要特性
完整地支持JSON標(biāo)準(zhǔn)。
部分兼容JSONPath RFC draft-4標(biāo)準(zhǔn)。
說明僅JSON.GET命令支持。
完整地支持JSONPointer語法。
文檔作為二進(jìn)制樹存儲(chǔ),可以快速訪問JSON數(shù)據(jù)的子元素。
支持JSON到XML或YAML格式的轉(zhuǎn)換。
發(fā)布記錄
隨Tair內(nèi)存型同時(shí)發(fā)布TairDoc,支持完整的JSONPointer語法與部分JSONPath語法(僅JSON.GET命令支持JSONPath語法)。
2022年5月17號(hào)發(fā)布1.8.4版,JSON.GET命令全面支持JSONPath語法,請(qǐng)將小版本升級(jí)至1.8.4及以上。
該版本新增支持Dot Wild Card Selector(節(jié)點(diǎn)通配符選擇器)、Index Selector(索引選擇器)與Filter Selector(條件過濾選擇器)等。
前提條件
實(shí)例為Tair內(nèi)存型。
最新小版本將提供更豐富的功能與穩(wěn)定的服務(wù),建議將實(shí)例的小版本升級(jí)到最新,具體操作請(qǐng)參見升級(jí)小版本。如果您的實(shí)例為集群架構(gòu)或讀寫分離架構(gòu),請(qǐng)將代理節(jié)點(diǎn)的小版本也升級(jí)到最新,否則可能出現(xiàn)命令無法識(shí)別的情況。
注意事項(xiàng)
操作對(duì)象為Tair實(shí)例中的TairDoc數(shù)據(jù)。
命令列表
表 1. TairDoc命令
命令 | 語法 | 說明 |
| 創(chuàng)建key并將JSON的值存儲(chǔ)在對(duì)應(yīng)的path中,若key及目標(biāo)path已經(jīng)存在,則更新對(duì)應(yīng)的JSON值。 | |
| 獲取目標(biāo)key、path中存儲(chǔ)的JSON數(shù)據(jù)。 | |
| 刪除目標(biāo)key中path對(duì)應(yīng)的JSON數(shù)據(jù),若未指定path,則刪除key。若指定的key不存在或path不存在,則忽略。 | |
| 獲取目標(biāo)key中path對(duì)應(yīng)值的類型,結(jié)果可能包括 | |
| 將value的Json合并到指定Key的path路徑中。可對(duì)目標(biāo)路徑下的值實(shí)現(xiàn)新增、更新、刪除等操作。 | |
| 對(duì)目標(biāo)key中path對(duì)應(yīng)的值增加value,path對(duì)應(yīng)的值和待增加的value必須是int或double類型。 | |
| 在指定path對(duì)應(yīng)值中添加json-string字符串,path對(duì)應(yīng)值的類型也需要為字符串。 | |
| 獲取目標(biāo)key中path對(duì)應(yīng)值的字符串長度,path對(duì)應(yīng)值的類型需要為字符串。 | |
| 在指定path對(duì)應(yīng)數(shù)組(array)的末尾添加JSON數(shù)據(jù),支持添加多個(gè)JSON。 | |
| 移除并返回path對(duì)應(yīng)數(shù)組(array)中指定位置(index)的元素。 | |
| 將JSON插入到path對(duì)應(yīng)的數(shù)組(array)中,原有元素會(huì)往后移動(dòng)。 | |
| 獲取path對(duì)應(yīng)數(shù)組(array)的長度。 | |
| 修剪目標(biāo)key的path對(duì)應(yīng)的數(shù)組(array),保留start至stop范圍內(nèi)的數(shù)據(jù)。 | |
| 使用原生Redis的DEL命令可以刪除一條或多條TairDoc數(shù)據(jù)。 |
本文的命令語法定義如下:
大寫關(guān)鍵字
:命令關(guān)鍵字。斜體
:變量。[options]
:可選參數(shù),不在括號(hào)中的參數(shù)為必選。A|B
:該組參數(shù)互斥,請(qǐng)進(jìn)行二選一或多選一。...
:前面的內(nèi)容可重復(fù)。
JSON.SET
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 創(chuàng)建key并將JSON的值存儲(chǔ)在對(duì)應(yīng)的path中,若key及目標(biāo)path已經(jīng)存在,則更新對(duì)應(yīng)的JSON值。 |
選項(xiàng) |
|
返回值 |
|
示例 | 命令示例:
返回示例:
|
JSON.GET
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 獲取目標(biāo)key、path中存儲(chǔ)的JSON數(shù)據(jù)。 |
選項(xiàng) |
說明 ROOTNAME與ARRNAME參數(shù)需在指定FORMAT參數(shù)為XML時(shí)配合使用。 |
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.DEL
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 刪除目標(biāo)key中path對(duì)應(yīng)的JSON數(shù)據(jù),若未指定path,則刪除key。若指定的key不存在或path不存在,則忽略。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.TYPE
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 獲取目標(biāo)key中path對(duì)應(yīng)值的類型,結(jié)果可能包括 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.MERGE
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 將value的Json合并到指定Key的path路徑中。可對(duì)目標(biāo)路徑下的值實(shí)現(xiàn)新增、更新、刪除等操作。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
此時(shí),執(zhí)行
|
JSON.NUMINCRBY
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 對(duì)目標(biāo)key中path對(duì)應(yīng)的值增加value,path對(duì)應(yīng)的值和待增加的value必須是int或double類型。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.STRAPPEND
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 在指定path對(duì)應(yīng)值中添加json-string字符串,path對(duì)應(yīng)值的類型也需要為字符串。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.STRLEN
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 獲取目標(biāo)key中path對(duì)應(yīng)值的字符串長度,path對(duì)應(yīng)值的類型需要為字符串。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.ARRAPPEND
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(M*N),M是需要插入的元素(json)數(shù)量,N是數(shù)組元素?cái)?shù)量。 |
命令描述 | 在指定path對(duì)應(yīng)數(shù)組(array)的末尾添加JSON數(shù)據(jù),支持添加多個(gè)JSON。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.ARRPOP
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(M*N),M是key包含的子元素,N是數(shù)組元素?cái)?shù)量。 |
命令描述 | 移除并返回path對(duì)應(yīng)數(shù)組(array)中指定位置(index)的元素。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.ARRINSERT
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(M*N),M是要插入的元素(json)數(shù)量,N是數(shù)組元素?cái)?shù)量。 |
命令描述 | 將JSON插入到path對(duì)應(yīng)的數(shù)組(array)中,原有元素會(huì)往后移動(dòng)。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.ARRLEN
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 獲取path對(duì)應(yīng)數(shù)組(array)的長度。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSON.ARRTRIM
類別 | 說明 |
語法 |
|
時(shí)間復(fù)雜度 | O(N) |
命令描述 | 修剪目標(biāo)key的path對(duì)應(yīng)的數(shù)組(array),保留start至stop范圍內(nèi)的數(shù)據(jù)。 |
選項(xiàng) |
|
返回值 |
|
示例 | 提前執(zhí)行 命令示例:
返回示例:
|
JSONPath介紹
TairDoc支持JSONPath的兼容語法如下表所示:
JSONPath | 說明 |
$ | 根元素。 |
@ | 當(dāng)前元素。 |
.name | 子元素。 |
.. | 任意位置符合要求的元素。 |
* | 通配符,表示所有子元素或數(shù)組元素。 |
[ ] | 數(shù)組索引,索引從0開始,例如[0];支持選擇列表,例如[0,1],表示0和1;也支持添加元素名,例如['name']。 |
[start:end:step] | 數(shù)組切片選擇器(Array Slice Selector),表示從start開始,到end結(jié)束,按照step為步長來獲取元素,例如[0:3:1],表示從第0位到第3位。若步長為負(fù)數(shù),則從后向前獲取。 |
?... | 條件過濾選擇器。 |
() | 支持表達(dá)式,優(yōu)先級(jí)為: |
查詢示例
創(chuàng)建JSON文檔。
命令實(shí)例:
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 }'
預(yù)計(jì)返回:
OK
查詢文檔。
查詢示例如下:
Root Selector
# 查詢整個(gè)JSON對(duì)象。 JSON.GET dockey $ # 預(yù)期輸出: "[{"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.* # 預(yù)期輸出: "["red",19.95]" # 查詢store中bicycle的price信息。 JSON.GET dockey $.store.bicycle.price # 預(yù)期輸出: "[19.95]"
Index Selector
# 查詢store中第一本book的所有信息。 JSON.GET dockey $.store.book[0] # 預(yù)期輸出: "[{"category":"reference","author":"Nigel Rees","title":"Sayings of the Century","price":8.95}]" # 查詢store中所有book的title信息。 JSON.GET dockey "$.store.book[*]['title']" # 預(yù)期輸出: "["Sayings of the Century","Sword of Honour","Moby Dick","The Lord of the Rings"]"
Array Slice Selector
# 使用數(shù)組分片的方式查詢book中第1至第3本書的所有信息,步長為1。 JSON.GET dockey $.store.book[0:2:1] # 預(yù)期輸出: "[{"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 # 預(yù)期輸出: "[8.95,12.99,8.99,22.99,19.95]"
List Selector
# # 查詢store中第一本和第三本book的所有信息。 JSON.GET dockey $.store.book[0,2] # 預(yù)期輸出: "[{"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
# @表達(dá)式 # 查詢store中book中包含isbn元素的信息。 JSON.GET dockey $.store.book[?(@.isbn)] # 預(yù)期輸出: "[{"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表達(dá)式 # 查詢store中price小于10的book信息。 JSON.GET dockey '$.store.book[?(@.price < 10)]' # 預(yù)期輸出: "[{"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}]" # 組合表達(dá)式 # 查詢目標(biāo)book信息,條件為price為12.99或者price比bicycle的price貴或者category為reference。 JSON.GET dockey "$..book[?((@.price == 12.99 || @.price > $.store.bicycle.price) || @.category == 'reference')]" # 預(yù)期輸出: "[{"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語法,更多信息,請(qǐng)參見JavaScript Object Notation (JSON) Pointer。
示例如下。
提前執(zhí)行JSON.SET doc . '{"foo": "bar", "baz" : [1,2,3]}'
命令。
命令示例:
# 獲取doc中.baz的第一個(gè)值。
JSON.GET doc /baz/0
返回示例:
"1"