DOC-3179: RI tutorial restructure (part C)

Author: dwdougherty

src/ds/json/arrays.md

@@ -1,3 +1,54 @@
-## Placeholder
+Redis has several commands that allow you to manipulate JSON arrays. Simple documents will be used to demonstrate each command.
 
-This is placeholder content.
+```redis Create a document
+JSON.SET doc $ '{"a": [10, 20, 30, 40, 50]}'
+```
+
+- `JSON.ARRLEN` - get the length of an array:
+
+```redis Get the length of $.a
+JSON.ARRLEN doc $.a
+```
+
+- `JSON.ARRAPPEND` - append one or more values to an array:
+
+```redis Append two values to $.a
+JSON.ARRAPPEND doc $.a 60 '"foo"'
+JSON.GET doc $.a
+```
+
+- `JSON.ARRPOP` - remove an element from an array:
+
+```redis Remove the last item from $.a
+JSON.ARRPOP doc $.a
+JSON.GET doc $.a
+```
+
+Note: `JSON.ARRPOP` takes two optional arguments: a path and a position. If no path is given, then `$` is assumed.
+Position is zero-based, with negative numbers representing last to first.
+For example, `-1` mean the last element and `-2` means the second to last element.
+
+- `JSON.ARRTRIM` - trim an array so that it contains only the specified inclusive range of elements.
+
+```redis Trim $.a to just the first 3 elements
+JSON.TRIM doc $.a 0 2
+JSON.GET doc
+```
+
+Now, reset doc to it's original value and trim `$.a` to just the last two values:
+
+```redis Re-create the document
+JSON.SET doc $ '{"a": [10, 20, 30, 40, 50]}'
+```
+
+```redis Trim to the last two values
+JSON.TRIM doc $.a -2 -1
+JSON.GET doc
+```
+
+As discussed earlier in this tutorial, `JSON.MERGE` can be used to replace entire arrays.
+
+```redis Replace $.a with a different set of values
+JSON.MERGE doc $.a '["a", "b", "c"]'
+JSON.GET doc
+```

src/ds/json/create.md

@@ -1,3 +1,76 @@
-## Placeholder
+## Create JSON documents
 
-This is placeholder content.
+Here's a query that creates a JSON document describing a single bike.
+
+```redis Create a JSON document
+JSON.SET bicycle:1 $ '{
+    "model": "Jigger",
+    "brand": "Velorim",
+    "price": 270,
+    "type": "Kids bikes",
+    "specs": {
+        "material": "aluminium",
+        "weight": "10"
+      },
+    "description": "Small and powerful, the Jigger is the best ride for the smallest of tikes! This is the tiniest kids\u2019 pedal bike on the market available without a coaster brake, the Jigger is the vehicle of choice for the rare tenacious little rider raring to go. We say rare because this smokin\u2019 little bike is not ideal for a nervous first-time rider, but it\u2019s a true giddy up for a true speedster. The Jigger is a 12 inch lightweight kids bicycle and it will meet your little one\u2019s need for speed. It\u2019s a single speed bike that makes learning to pump pedals simple and intuitive. It even has  a handle in the bottom of the saddle so you can easily help your child during training!  The Jigger is among the most lightweight children\u2019s bikes on the planet. It is designed so that 2-3 year-olds fit comfortably in a molded ride position that allows for efficient riding, balanced handling and agility. The Jigger\u2019s frame design and gears work together so your buddingbiker can stand up out of the seat, stop rapidly, rip over trails and pump tracks. The Jigger\u2019s is amazing on dirt or pavement. Your tike will speed down the bike path in no time. The Jigger will ship with a coaster brake. A freewheel kit is provided at no cost.",
+    "addons": [
+        "reflectors",
+        "grip tassles"
+    ],
+    "helmet_included": false
+    }'
+```
+
+Now retrieve the newly created JSON document.
+
+```redis Retrieve bicycle:1
+JSON.GET bicycle:1
+```
+
+In the above example, the path, which is root (`$`), is implied. You could also write this command as:
+
+```
+JSON.GET bicycle:1 $
+```
+
+You can also retrieve parts of documents using JSONPath expressions. JSONPath will be discussed in more detail later in this tutorial, but here are a few examples:
+
+```redis Get the price of bicycle:1
+JSON.GET bicycle:1 $.price
+```
+
+```redis Get the weight of bicycle:1
+JSON.GET bicycle:1 $.specs.weight
+```
+
+```redis Get the first addon of bicycle:1
+JSON.GET bicycle:1 $.addons[0]
+```
+
+You can create multiple documents in a single command using `JSON.MSET`:
+
+```redis Add two more documents using JSON.MGET
+JSON.MSET "bicycle:2" $ "{\"model\": \"Hillcraft\", \"brand\": \"Bicyk\", \"price\": 1200, \"type\": \"Kids Mountain Bikes\", \"specs\": {\"material\": \"carbon\", \"weight\": \"11\"}, \"description\": \"Kids want to ride with as little weight as possible. Especially on an incline! They may be at the age when a 27.5\\\" wheel bike is just too clumsy coming off a 24\\\" bike. The Hillcraft 26 is just the solution they need! Imagine 120mm travel. Boost front/rear.  You have NOTHING to tweak because it is easy to assemble right out of the box. The Hillcraft 26 is an efficient trail trekking machine. Up or down does not matter - dominate the trails going both down and up with this amazing bike. The name Monarch comes from Monarch trail in Colorado where we love to ride.  It\u2019s a highly technical, steep and rocky trail but the rip on the waydown is so fulfilling.  Don\u2019t ride the trail on a hardtail! It is so much more fun on the full suspension Hillcraft!  Hit your local trail with the Hillcraft Monarch 26 to get to where you want to go.\", \"addons\": [\"reflectors\", \"safety lights\"],\"helmet_included\": false}" "bicycle:3" $ "{\"model\": \"Chook air 5\", \"brand\": \"Nord\", \"price\": 815, \"type\": \"Kids Mountain Bikes\", \"specs\": {\"material\": \"alloy\", \"weight\": \"9.1\"}, \"description\": \"The Chook Air 5  gives kids aged six years and older a durable and uberlight mountain bike for their first experience on tracks and easy cruising through forests and fields. The lower  top tube makes it easy to mount and dismount in any situation, giving your kids greater safety on the trails. The Chook Air 5 is the perfect intro to mountain biking.\", \"addons\": [\"reflectors\", \"safety lights\"],\"helmet_included\": false}"
+```
+
+You can retrieve multiple documents or parts of documents in a single command using `JSON.MGET`:
+
+```redis Get bicycle:1 and bicycle:2
+JSON.MGET bicycle:1 bicycle:2 $
+```
+
+```redis Get the price of all three bicycle documents
+JSON.MGET bicycle:1 bicycle:2 bicycle:3 $.price
+```
+
+There are two other commands you can use to get information from documents:
+
+```redis Get the length of bicycle:1's description
+JSON.STRLEN bicycle:1 $.description
+```
+
+```redis Get the type of bicycle:1's helmet_included attribute
+JSON.TYPE bicycle:1 $.helmet_included
+```
+
+The `JSON.MERGE` can also be used to create new documents. `JSON.MERGE` will be covered in more detail later in this tutorial.

src/ds/json/introduction.md

@@ -1,3 +1,9 @@
-## Placeholder
+The JSON capability of Redis Stack provides JavaScript Object Notation (JSON) support for Redis, which allows Redis to function as a document database.
+It lets you store, update, and retrieve JSON values in a Redis database, similar to any other Redis data type. Redis JSON also works seamlessly with Search and Query to let you index and query JSON documents.
 
-This is placeholder content.
+Primary features include:
+
+- Full support for the JSON standard.
+- [JSONPath](https://goessner.net/articles/JsonPath/) syntax for selecting/updating elements inside documents.
+- Documents are stored as binary data in a tree structure, allowing fast access to sub-elements.
+- Typed atomic operations for all JSON value types.

src/ds/json/learn-more.md

@@ -1,3 +1 @@
-## Placeholder
-
-This is placeholder content.
+You can read more about the JSON data type [here](https://redis.io/docs/data-types/json/). See [here](https://redis.io/commands/?group=json) for the complete list of JSON commands.

src/ds/json/modify.md

@@ -1,3 +1,108 @@
-## Placeholder
+Modifying JSON documents is straightforward using a combination of JSONPath expressions and Redis's JSON command set.
 
-This is placeholder content.
+Here are some examples.
+
+## Extend documents
+
+```redis Add a new key:value pair to an existing document
+JSON.SET bicycle:1 $.newkey '"value"'
+```
+
+You could also use `JSON.MSET` to create or update multiple documents at the same time. First, delete `$.newkey` from `bicycle:1` using `JSON.DEL`.
+
+```redis Delete $.newkey from bicycle:1
+JSON.DEL bicycle:1 $.newkey
+```
+
+Next, add `$.newkey` to all three bicycles:
+
+```redis Add $.newkey too all three bicycles using JSON.MSET
+JSON.MSET bicycle:1 $.newkey '"value1"' bicycle:2 $.newkey '"value2"' bicycle:3 $.newkey '"value3"'
+JSON.MGET bicycle:1 bicycle:2 bicycle:3 $.newkey
+```
+
+## Manipulate numeric values
+
+There are two commands that allow you to perform arithmetic operations on components of documents:
+
+- `JSON.NUMINCRBY` - adds a value to a numeric field.
+
+```redis Decrease the price of bicycle:1
+JSON.GET bicycle:1 $.price
+JSON.NUMINCRBY bicycle:1 $.price -10
+JSON.GET bicycle:1 $.price
+```
+
+- `JSON.NUMMULTBY` - multiply a numeric field by a value.
+
+```redis Discount bicycle:1 by 10%
+JSON.NUMMULTBY bicycle:1 $.price 0.9
+```
+## Manipulate string and boolean values
+
+Appending information to JSON strings is straightforward.
+
+```redis Append a string bicycle:1's model
+JSON.STRAPPEND bicycle:1 $.model '"naut"'
+JSON.GET bicycle:1 $.model
+```
+
+The `JSON.TOGGLE` command can be used to toggle boolean values.
+
+```redis Toggle the value of bicycle:1's helmet_included value
+JSON.GET bicycle:1 $.helmet_included
+JSON.TOGGLE bicycle:1 $.helmet_included
+JSON.GET bicycle:1 $.helmet_included
+```
+
+## Deeper document manipulation
+
+As you saw earlier, the `JSON.MERGE` command can be used to create new documents. Additionally, it can also be used for the following use cases:
+
+- Create a non-existant path-value:
+
+```redis Add a new field-value pair to bicycle:1
+JSON.MERGE bicycle:1 $.newkey2 '"value 2 1"'
+JSON.GET bicycle:1
+```
+
+- Replace an existing value:
+
+```redis Change bicycle:1's model back to Jigger
+JSON.MERGE bicycle:1 $.model '"Jigger"'
+JSON.GET bicycle:1 $.model
+```
+
+- Delete an existing value:
+
+```redis Delete newkey2 from bicycle:1
+JSON.MERGE bicycle:1 $ '{"newkey2": null}'
+JSON.GET bicycle:1
+```
+
+- Replace an array:
+
+```redis Replace bicycle:1's addons
+JSON.MERGE bicycle:1 $.addons '["reflectors", "rainbow seat"]'
+JSON.GET bicycle:1 $.addons
+```
+
+- Make changes to multiple paths (no example).
+
+## Delete information
+
+You can delete field-value pairs using the `JSON.DEL` or `JSON.FORGET` commands:
+
+```redis Delete newkey from bicycle:1
+JSON.DEL bicycle:1 $.newkey
+JSON.GET bicycle:1
+```
+
+The `JSON.CLEAR` command will empty all arrays and set all numeric values to zero.
+
+```redis Clear out bicycle:1
+JSON.CLEAR bicycle:1
+JSON.GET bicycle:1
+```
+
+As with all Redis keys, you can use the `DEL` command to delete keys entirely.

src/ds/json/objects.md

@@ -1,3 +1,25 @@
-## Placeholder
+Redis provides two commands that operate specifically on JSON objects. A simple document will be used to demonstrate each of the two commands.
 
-This is placeholder content.
+```redis Create document
+JSON.SET doc $ '{"a":1,"b":2,"o":{"c":3,"d":4}}'
+```
+
+- `JSON.OBJKEYS` - retrieve the fields of a JSON object.
+
+```redis Get doc's fields
+JSON.OBJKEYS doc
+```
+
+```redis Get the fields for $.o
+JSON.OBJKEYS doc $.o
+```
+
+- `JSON.OBJLEN` - get the number of fields of a JSON object.
+
+```redis Get the number of fields in the doc object
+JSON.OBJLEN doc
+```
+
+```redis Get the number of fields in the $.o object
+JSON.OBJLEN doc $.o
+```