From f1a84ed84e064e8366aa6cabe57a508fb9f6751d Mon Sep 17 00:00:00 2001 From: Simon Prickett Date: Mon, 7 Aug 2023 15:43:58 +0100 Subject: [PATCH] Added JSON.MERGE content. --- ...04_1_4_0_updating_data_with_redisjson.html | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/courseware/html/section_1/ru204_1_4_0_updating_data_with_redisjson.html b/courseware/html/section_1/ru204_1_4_0_updating_data_with_redisjson.html index 1637fcfc..88b0b752 100644 --- a/courseware/html/section_1/ru204_1_4_0_updating_data_with_redisjson.html +++ b/courseware/html/section_1/ru204_1_4_0_updating_data_with_redisjson.html @@ -78,4 +78,58 @@

Removing properties from a JSON document

JSON.DEL ru204:book:18161 $.genres

Redis returns the number of properties successfully removed; in this case one:

1

+

Performing Merge and Patch operations

+
+

Oftentimes, we'll want to make multiple changes to a JSON document at once, atomically, by merging a new JSON value into a JSON document. RFC7396 - JSON Merge Patch defines the rules for how such operations should behave.

This RFC is implemented by the RedisJSON JSON.MERGE command.

+

The JSON.MERGE command allows us to make the following different types of change to a JSON document stored in Redis. All of these can be performed with a single invocation of the command.

+

The types of change are:

+ +

Let's look at examples of each.

+

Here, we're removing the author property from book 274 whilst also changing the contents of editions, updating the number of pages and adding a new has_ebook_version property. First let's look at these values in the original document:

+

JSON.GET ru204:book:274 $.author $.editions $.pages $.has_ebook_version

+

Redis returns:

+

"{\"$.editions\":[[\"english\",\"spanish\"]],\"$.pages\":[311],\"$.author\":[\"S.E. Grove\"],\"$.has_ebook_version\":[]}"

+

Now we can modify the document with JSON.MERGE:

+

JSON.MERGE ru204:book:274 $ '{"pages": 350, "editions": [ "english", "spanish", "french"], "author": null, "has_ebook_version": true}' +

+

Redis returns OK. Let's see what the updated document contains:

+

JSON.GET ru204:book:274 $.author $.editions $.pages $.has_ebook_version

+

Redis returns:

+

"{\"$.pages\":[350],\"$.has_ebook_version\":[true],\"$.author\":[],\"$.editions\":[[\"english\",\"spanish\",\"french\"]]}"

+

Next, undo some of those changes with a second JSON.MERGE invocation. This time, we'll set author back to the original value and remove the has_ebook_version property:

+

JSON.MERGE ru204:book:274 $ '{"author": "S.E. Grove", "has_ebook_version": null }'

+

Again, Redis returns OK (this is the return value of all successful JSON.MERGE invocations).

+

Finally, check that the has_ebook_version property no longer exists (we could use JSON.GET but instead let's use JSON.TYPE):

+

JSON.TYPE ru204:book:274 $.has_ebook_version

+

Redis returns (empty array) indicating that there is no value at this key.

+

When storing new JSON documents in Redis, JSON.MERGE behaves in the same way as JSON.SET. New documents can only be created at the root ($) path.

+

Here's an example demonstrating this. First, we check that book 9999 doesn't already exist:

+

EXISTS ru204:book:9999

+

Redis returns 0 indicating that this key does not exist. If we try to create a new document there by setting values at a path other than the root, Redis will return an error:

+

JSON.MERGE ru204:book:9999 $.metrics '{"rating_votes": 22}'

+

Result:

+

(error) ERR new objects must be created at the root

+

This example creates a new key ru204:book:9999 containing a new JSON document:

+

JSON.MERGE ru204:book:9999 $ '{"author": "Redis", "id": "9999"}'

+

Note - setting null values:

+

The JSON.MERGE command uses null values to indicate that a property should be removed from the document. If you want to explicitly store null as a property's value. When you want to do that, use JSON.SET or JSON.MSET instead.

+

As an example, let's set book 9999's author to null and check what is stored in Redis:

+

JSON.SET ru204:book:9999 $.author "null"

+

JSON.GET ru204:book:9999 $

+

"[{\"author\":null,\"id\":\"9999\"}]"

+

Note that the property author exists and has null as its value.

+

Compare this with the same update using JSON.MERGE: +

JSON.MERGE ru204:book:9999 $ '{"author": null}'

+

+

Note that this time the author property has been deleted:

+

JSON.GET ru204:book:9999 $

+

"[{\"id\":\"9999\"}]"

+

Finally, clean up by deleting book 9999 from Redis:

+

DEL ru204:book:9999

+

The JSON.MERGE command was added in version 2.6.0 of RedisJSON. If your Redis Stack instance doesn't have this command, you'll need to upgrade it.

While it is important to understand how to use the Redis CLI to use the RedisJSON commands to create and maintain documents within Redis, most developers will want to perform these operations from their application code directly. In the next section, we will explore how to manage JSON documents in Redis using popular Redis client libraries for commonly used programming languages.