關於 JSON

JavaScript Object Notation (JSON) 可讓您在 Memorystore for Valkey 中有效率地儲存及操控結構化資料。使用 JSON 可享有下列優點：

  • 提供快速搜尋和篩選功能
  • 對 JSON 資料執行就地更新，不必覆寫整個文件
  • 有效率地查詢、修改及管理複雜的資料結構

如果應用程式需要動態且彈性的資料儲存空間，JSON 就是理想選擇。此外，您也可以使用 JSON，在 Memorystore for Valkey 執行個體中編碼複雜的資料集，無須使用結構定義。您可以在執行個體中儲存、存取及更新資料，不必管理自訂程式碼來序列化及還原序列化資料。

JSON 文件是一種人類可讀的文字格式，用於儲存及傳輸資料。這個格式包含鍵/值組合和結構化資料類型。JSON 格式可讓您擷取及更新 JSON 文件的部分內容，不必處理整個物件。這有助於提升成效及降低成本。此外，JSON 格式符合 RFC 7159、ECMA-404 JSON 資料交換標準，以及 JSON 文字中的 UTF-8 Unicode。

可用性

如果您建立的 Memorystore for Valkey 執行個體是 8.0 以上版本，系統就會自動提供 JSON 資料類型和相關指令的 1.0 版。這個資料類型與 JSON 模組第 2 版的 API 相容。此外，根據 RFC 7159，JSON 文件的根元素可以是任何 JSON 資料類型。

JSON 屬性

JSON 具有下列屬性：

  • 文件大小上限：為避免惡意或無限制插入資料，導致潛在的記憶體不足問題，您可以設定個別 JSON 金鑰的大小限制。

    這項屬性的值預設為 0，表示 JSON 文件大小沒有限制。如要設定這項限制，請使用 CONFIG SET json.max-document-size VALUE 指令，其中 VALUE 是文件大小上限。舉例來說，如果您指定 4123456，則文件大小上限為 4,123,456 個位元組 (4 MB)。

    如要查看儲存在指定鍵中的 JSON 值所用的記憶體量，可以使用 JSON.DEBUG MEMORY KEY 或 MEMORY USAGE KEY 指令。在這些指令中，KEY 是儲存 JSON 值的鍵名稱。

  • 最大深度：JSON 物件和陣列的巢狀結構層級上限。詳情請參閱「巢狀結構深度上限」。

JSON 文件大小

由於 JSON 文件在內部是以經過最佳化的格式儲存，可快速存取及修改，因此這類文件可能會耗用大量記憶體。如要檢查 JSON 文件耗用的記憶體量，請使用 JSON.DEBUG MEMORY KEY 指令，其中 KEY 是包含文件的鍵名。

JSON 類別

如要管理 JSON 指令和資料的存取權，請使用 @json 類別。除了這個類別，下列類別也使用 JSON 指令：@read、@write、@fast、@slow 和 @admin。

下表說明是否可將 JSON 指令對應至 @read、@write、@fast、@slow、@admin 和 @json 類別。

JSON 指令 @json @read @write @fast @slow @admin
JSON.ARRAPPEND Y 否 是 是 否 N
JSON.ARRINDEX 是 是 否 是 否 N
JSON.ARRINSERT 是 否 是 是 否 N
JSON.ARRLEN 是 是 否 是 否 N
JSON.ARRPOP 是 否 是 是 否 N
JSON.ARRTRIM 是 否 是 是 否 N
JSON.CLEAR 是 否 是 是 否 N
JSON.DEBUG 是 是 否 N 是 是
JSON.DEL 是 否 是 是 否 N
JSON.FORGET 是 否 是 是 否 N
JSON.GET 是 是 否 是 否 N
JSON.MGET 是 是 否 是 否 N
JSON.MSET 是 否 是 否 是 否
JSON.NUMINCRBY 是 否 是 是 否 N
JSON.NUMMULTBY 是 否 是 是 否 N
JSON.OBJKEYS 是 是 否 是 否 N
JSON.OBJLEN 是 是 否 是 否 N
JSON.RESP 是 是 否 是 否 N
JSON.SET 是 否 是 否 是 否
JSON.STRAPPEND 是 否 是 是 否 N
JSON.STRLEN 是 是 否 是 否 N
JSON.TOGGLE 是 否 是 是 否 N
JSON.TYPE 是 是 否 是 否 N

JSON 指令

本節列出並說明可用於對 JSON 文件執行作業的 JSON 指令。

指令 說明
JSON.ARRAPPEND 在路徑的陣列中附加一或多個 JSON 值。
JSON.ARRINDEX 在陣列中搜尋第一個出現的 JSON 純量值。
JSON.ARRINSERT 在您指定的索引之前，將一或多個 JSON 值插入路徑中的陣列。
JSON.ARRLEN 在路徑中擷取 JSON 陣列的長度。
JSON.ARRPOP 從陣列中的索引移除並傳回元素。
JSON.ARRTRIM 在路徑中修剪陣列，使其只包含您指定的元素範圍 (含頭尾)。
JSON.CLEAR 清除指定路徑的陣列或 JSON 物件。
JSON.DEBUG 擷取 JSON 文件相關資訊。Memorystore for Valkey 支援下列子指令：
  • MEMORY：以位元組為單位回報值的記憶體用量。
  • DEPTH：回報 JSON 文件的最大路徑深度。
  • FIELDS：回報 JSON 元素中的欄位數量。這個元素會儲存在您指定的鍵中。
  • HELP：傳回 JSON.DEBUG 指令的實用資訊。
JSON.DEL
JSON.FORGET		 刪除指定路徑的 JSON 值。
JSON.GET 以 JSON 序列化形式傳回您在路徑中指定的值。
JSON.MGET 從多個文件鍵傳回指定路徑的值。
JSON.MSET 在路徑中為多個鍵設定多個 JSON 值。
JSON.NUMINCRBY 將路徑中儲存的數值，依您指定的數字遞增。
JSON.NUMMULTBY 將路徑中儲存的數值乘以您指定的數字。
JSON.OBJKEYS 從您指定的路徑，擷取 JSON 物件中的鍵名。
JSON.OBJLEN 在您指定的路徑中，擷取 JSON 物件中的鍵數。
JSON.RESP 以 Redis 序列化通訊協定 (RESP) 形式傳回鍵的 JSON 值。
JSON.SET 在您指定的路徑設定 JSON 值。
JSON.STRAPPEND 在您指定的路徑，將字串附加至 JSON 字串。
JSON.STRLEN 在您指定的路徑中，擷取 JSON 字串值的長度。
JSON.TOGGLE 在 true 和 false 之間切換布林值。這個值會儲存在您指定的路徑。
JSON.TYPE 在您指定的路徑中，擷取 JSON 值的型別。

Memorystore for Valkey 如何與 JSON 互動

本節說明 Memorystore for Valkey 如何與 JSON 資料類型互動。

多個條件運算式

如有用於篩選的多個條件運算式，Memorystore for Valkey 會依下列順序評估：

  1. 括號內的運算
  2. 邏輯 AND 運算式 (&&)
  3. 邏輯 OR (||) 運算式

巢狀結構深度上限

如果 JSON 物件或陣列的元素是另一個 JSON 物件或陣列，內層物件或陣列就會巢狀內嵌在外層物件或陣列中。巢狀結構深度上限為 128。因此，$.a.b.c.d... 等值最多只能達到 128 個層級。

如果您嘗試建立巢狀深度超過 128 的 JSON 文件，Memorystore for Valkey 會拒絕該文件，並顯示錯誤訊息。不過，您可以使用 CONFIG SET json.max-path-limit VALUE 指令調整這項限制，其中 VALUE 是您想要的深度限制。

JSON 數字

在 JSON 中，浮點數和整數都稱為數字，因為兩者具有相同的資料類型。當 Memorystore for Valkey 收到 JSON 數字時，會將該數字轉換為下列其中一種內部二進位表示法：

  • 64 位元 IEEE 雙精度浮點數
  • 64 位元帶正負號整數

JSON 不會保留原始字串及其所有格式。當 Memorystore for Valkey 輸出 JSON 回應中的數字時，會將數字從內部二進位表示法轉換為可列印的字串，並使用一般格式規則。

使用 JSON.NUMINCRBY 和 JSON.NUMMULTBY 指令搭配 JSON 數字時，適用下列條件：

  • 如果兩個數字都是整數，且結果超出 int64 的範圍，結果會自動變成 64 位元 IEEE 雙精準度浮點數。
  • 如果至少有一個數字是浮點數，結果就會是 64 位元 IEEE 雙精準度浮點數。
  • 如果結果超出 64 位元 IEEE 雙精準度浮點數的範圍，您會收到 OVERFLOW 錯誤訊息。

直接陣列

Memorystore for Valkey 會直接篩選陣列物件。舉例來說，如果您有 &lbrack;0、1、2、3&rbrack; 等資料，以及 $[?(@<3)] 等路徑查詢，則 Memorystore for Valkey 會傳回 &lbrack;0,1,2&rbrack;。
如果是 {"my_valkey_key":[0,1,2,3]} 等資料和
$.my_valkey_key[?(@<3)] 等路徑查詢，Memorystore for Valkey 也會傳回 &lbrack;0,1,2&rbrack;。

陣列索引

您可以使用正數和負數索引，存取 Memorystore for Valkey 陣列中的元素。這類索引適用下列條件：

  • 正向索引：數字從陣列的開頭開始。舉例來說，如果陣列的正向索引為 3，則 0 會查詢第一個元素、1 會查詢第二個元素，而 2 會查詢第三個元素。
  • 負數索引：數字從陣列的結尾開始。如果陣列的負索引為 3，則 -1 會查詢第三個元素，-2 會查詢第二個元素，-3 則會查詢第一個元素。

Memorystore for Valkey 不會將索引向上或向下捨入。如果陣列長度為 3，且您呼叫大於 3 的正向索引或小於 -3 的負向索引，則 Memorystore for Valkey 不會傳回結果。

JSON 路徑的語法

JSON 路徑不得使用無效語法。即使語法無效的 JSON 路徑子集包含有效路徑，這項條件也適用。