Merge pull request #32 from RedisInsight/main

new 2.42 tutorials

Author: ViktarStarastsenka

.github/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           repo_token: "${{ secrets.GITHUB_TOKEN }}"
           prerelease: false
-          automatic_release_tag: 2.x.x
+          automatic_release_tag: 2.42
           files: |
             data.zip
             build.json

src/_scripts/manual.txt

@@ -0,0 +1,47 @@
+Lists, sets, and sorted sets are great for many use cases, but the hash data type is on a higher level. Redis hashes are maps (sequences of field-value pairs) and are used to represent objects in Redis. Consider the following example that shows how to create a hash key using the `HSET` command.
+
+Redis hashes are record types that are structured as name-value pairs. Consider the following example that shows how to create a hash key using the `HSET` command.
+
+```redis:[run_confirmation=true] Create a hash
+HSET bike:1 model Deimos brand Ergonom type "Enduro bikes" price 4972
+```
+
+`HSET` returns the number of added name-value pairs.
+
+To retrieve the stored data, use the `HGETALL` command.
+
+```redis HGETALL usage
+HGETALL bike:1 // returns all the name-value pairs associated with the key
+```
+
+If you only want the values of a subset of the fields, use the `HGET` command.
+
+```redis HGET usage
+HGET bike:1 price
+```
+
+You can update fields in a hash using `HSET` by specifying a subset of its name-value pairs.
+
+```redis:[run_confirmation=true] Update an existing hash
+HSET bike:1 model "Kraken" price 3000
+```
+
+Use the `HDEL` command to delete one or more fields from a hash. Once all fields are removed, the hash key itself will be deleted.
+
+```redis:[run_confirmation=true] Delete hash fields and keys
+HDEL bike:1 model
+HGETALL bike:1
+HDEL bike:1 brand type price
+HGETALL bike:1
+EXISTS bike:1
+```
+
+Integer values in hash keys can be incremented or decremented in the same way as simple string keys using the `HINCRBY` command.
+The increment value must be a positive or negative integer.
+
+```redis Hash INCRBY usage
+HINCRBY bike:1 price 100
+HINCRBY bike:1 price -100
+```
+
+See [here](https://redis.io/docs/data-types/hashes?utm_source=redisinsight&utm_medium=main&utm_campaign=tutorials) for the hash type reference page, and [here](https://redis.io/commands/?group=hash?utm_source=redisinsight&utm_medium=main&utm_campaign=tutorials) for the entire set of Redis hash commands.

src/ds/hashes.md

@@ -0,0 +1,189 @@
+[JSONPath](https://goessner.net/articles/JsonPath/) expressions help you access specific elements within a JSON document, which is similar to how XPATH works for XML documents.
+JSONPath support was added to Redis Stack in version 2.0.
+Before that, [a legacy form of pathing](https://redis.io/docs/data-types/json/path/#legacy-path-syntax) was supported.
+Only JSONPath will be discussed in this tutorial.
+
+You've already seen several examples of JSONPath in previous parts of this tutorial. The next sections will describe JSONPath in more complete detail.
+Some simple JSON documents will be used to demonstrate JSONPath's features.
+
+```redis:[run_confirmation=true] Load documents
+JSON.SET lit1 $ 5
+JSON.SET lit2 $ '"abc"'
+JSON.SET lit3 $ true
+JSON.SET lit4 $ null
+JSON.SET obj1 $ '{"a":1, "b":2}'
+JSON.SET obj2 $ '{"a":[1,2,3,"a","b","c",false,true,["a",1],{"a":1},{"b":null}], "b":5}'
+JSON.SET arr1 $ [1,2,3]
+JSON.SET arrmap $ '[{"a":1}, {"b":2}]'
+```
+
+**Note**:
+>A JSONPath query can resolve to multiple absolute path matches. When more than one matching path is identified, the JSON commands apply the operation to every possible path.
+
+## JSONPath syntax
+
+| Syntax element | Description |
+|----------------|-------------|
+| `$` | The root (outermost JSON element), starts the path. |
+| `.` | Selects a child element. |
+| `..` | Recursively descends through the JSON document. |
+| `*` | If current node is an array, `*` resolves to all array elements. If current node is an object, `*` resolves to all the object's members |
+| `[]` | Subscript operator, accesses an array element. |
+| `[,]` | Union, selects multiple elements. |
+| `[start:end:step]` | Array slice where `start`, `end`, and `step` are indexes. |
+| `[?(...)]` | Filters a JSON object or array. Supports comparison operators (`==`, `!=`, `<`, `<=`, `>`, `>=`, `=~`), logical operators (`&&`, `\|\|`), and parentheses for grouping (`(`, `)`). |
+| `@` | The current element, used in filter or script expressions. |
+
+## Basic usage
+
+`$` represents the root of a document. When `$` is combined with `.` and/or `[]`, a child element is selected. Here are a few examples.
+
+```redis $ by itself
+JSON.GET obj1 $ // returns the entire obj1 document
+```
+
+```redis Select an element with $.
+JSON.GET obj2 $.a // returns the array pointed to by a
+```
+
+```redis Select an element with $[...]
+JSON.GET arr1 $[1] // returns the second element of the arr1 array
+```
+
+```redis Select $.a using $.[] notation
+JSON.GET obj2 '$.["a"]' // note the use of single quotes in this expression; they're needed to be able to use double quotes in the expression
+```
+
+It is possible to use `$` as part of a field name.
+
+```redis:[run_confirmation=true] Using $ as part of a field name
+JSON.SET d $ '{"$":5, "$$":6}'
+JSON.GET d $.$ // returns "[5]"
+```
+
+The use of quotes is optional when double quotes are not in use inside of an expression.
+Each of the following JSONPath expressions return the same value, `"[5]"`.
+
+```redis Quote usage
+JSON.GET obj2 $.b
+JSON.GET obj2 $.'b'
+JSON.GET obj2 $'.b'
+```
+
+**Note**:
+>If the current node is not an object or has no member named after the operand, an empty array is returned.
+
+```redis Invalid path
+JSON.GET obj1 $.c // "[]" is returned
+```
+
+```redis Combining . and []
+JSON.GET arrmap $[0].a
+```
+
+## Bracket (union) expressions
+
+The following syntaxes are supported:
+
+- `'$["value1", "value2", ...]'`
+- `$[idx1, idx2, idx3, ...]`
+
+Each represents a union operation, allowing you to select multiple elements.
+
+For objects, return values are as follows:
+
+- If the current node is an object, an array containing the values of the object’s fields, based on their names, is returned.
+- If the current node is an object and has no members named in the bracket expression, it is skipped.
+This could result in an empty array being returned.
+- If the current node is not an object, an empty array is returned.
+
+Here are some examples:
+
+```redis Bracket union examples with objects
+JSON.GET obj1 '$["a"]'
+JSON.GET obj1 '$["b","b"]'
+JSON.GET obj1 '$["a","c","b","d"]'
+JSON.GET obj1 '$["c","d"]'
+JSON.GET arr1 '$["a","b"]'
+```
+
+For arrays:
+
+- idx must be an integer
+- if idx < 0, it is replaced with min(0, idx + array-length)
+- if idx ≥ array-length (after normalization) - it is skipped
+
+Return values are as follows:
+
+- If the current node is an array, an array containing elements based on one or more 0-based indexes is returned.
+- If the current node is not an array, it is skipped, possibly resulting in an empty array being returned.
+
+idx must be an integer
+if idx < 0, it is replaced with min(0, idx + array-length)
+if idx ≥ array-length (after normalization) - it is skipped
+
+```redis Bracket union examples with arrays
+JSON.GET obj2 $.a[0]
+JSON.GET obj2 $.a[-1]
+JSON.GET obj2 $.a[100]
+JSON.GET obj2 $.a[-100]
+JSON.GET obj2 $.a[8][1]
+JSON.GET obj2 $.a[0,0,1,1]
+JSON.GET obj2 $.b[0]
+JSON.GET obj2 $.*[0]
+```
+
+Redis Stack also supports slice syntax for arrays: `[start:`end`:`step`]`, where `start`, `end`, and `step` are indexes.
+If the current node is an array, an array containing elements extracted from an array are returned, based on a `start` index, an `end` index, and a `step` index.
+Array indexes are zero-based; the first element is index 0. Start Index is inclusive; End index is not inclusive.
+The following rules apply:
+
+| Predicate | Rule |
+| --------- | ---- |
+| If `start` is specified | it must be an integer |
+| if `start` is omitted | it is replaced with 0 |
+| if `start` < 0 | it is replaced with min(0, `start` + array-length) |
+| if `start` > array-length | an empty array is returned |
+| if `end` is specified | it must be an integer |
+| If `end` is omitted | it is replaced with array-length |
+| If `end` ≥ array-length | it is replaced with array-length |
+| if `end` < 0 | it is replaced with min(0, `end` + array-length) |
+| If `end` ≤ `start` (after normalization) | an empty array is returned |
+| If `step` is specified | it must be a positive integer |
+| If `step` is omitted | it is replaced with 1 |
+| If the current node in not an array | an empty array is returned |
+
+```redis Array slice examples
+JSON.GET arr1 $[:]
+JSON.GET arr1 $[::]
+JSON.GET arr1 $[::2]
+JSON.GET arr1 $[0:1]
+JSON.GET arr1 $[0:2]
+JSON.GET lit3 $.*[:]
+```
+
+## Wildcard expressions
+
+The `*` character is a wildcard that expands depending on the type of the current node:
+
+- If the current node is an array, an array containing the values of all the array’s elements is returned.
+
+```redis Using * when the current node is an array
+JSON.GET arr1 $.*  // each of the following commands return identical results
+JSON.GET arr1 $[*]
+JSON.GET arr1 $.[*]
+```
+
+- If the current node is an object, an array containing the values of all the object’s members is returned.
+
+```redis Using * when the current node is an object
+JSON.GET obj1 $.* // each of the following commands return identical results
+JSON.GET obj1 $[*]
+JSON.GET obj1 $.[*]
+```
+
+- If current node is a literal, an empty array is returned.
+
+```redis Using * when the current node is a literal
+JSON.GET lit1 $.*
+```

src/ds/json/adv-jsonpath.md

@@ -0,0 +1,54 @@
+Redis has several commands that allow you to manipulate JSON arrays. Simple documents will be used to demonstrate each command.
+
+```redis:[run_confirmation=true] 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:[run_confirmation=true] Append two values to $.a
+JSON.ARRAPPEND doc $.a 60 '"foo"'
+JSON.GET doc $.a
+```
+
+- `JSON.ARRPOP` - remove an element from an array:
+
+```redis:[run_confirmation=true] 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:[run_confirmation=true] Trim $.a to just the first 3 elements
+JSON.ARRTRIM 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:[run_confirmation=true] Re-create the document
+JSON.SET doc $ '{"a": [10, 20, 30, 40, 50]}'
+```
+
+```redis:[run_confirmation=true] Trim to the last two values
+JSON.ARRTRIM doc $.a -2 -1
+JSON.GET doc
+```
+
+As discussed earlier in this tutorial, `JSON.MERGE` can be used to replace entire arrays.
+
+```redis:[run_confirmation=true] Replace $.a with a different set of values
+JSON.MERGE doc $.a '["a", "b", "c"]'
+JSON.GET doc
+```

src/ds/json/arrays.md

@@ -0,0 +1,76 @@
+## Create JSON documents
+
+Here's a query that creates a JSON document describing a single bike.
+
+```redis:[run_confirmation=true] Create a JSON document
+JSON.SET bicycle:1 $ '{
+    "model": "Jigger",
+    "brand": "Velorim",
+    "price": 270,
+    "type": "Kids bikes",
+    "specs": {
+        "material": "aluminium",
+        "weight": "10"
+      },
+    "description": "The Jigger is the best ride for the smallest of tikes!",
+    "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:[run_confirmation=true] 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\": \"A light mountain bike for kids.\", \"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\": \"A lighter, more durable mountain bike for six years and older.\", \"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.