Skip to content

Commit 02a26ba

Browse files
ViktarStarastsenkaViktarStarastsenka
authored
Merge pull request #6 from RedisInsight/main
Adding a fix for VSS
2 parents 355015a + f59fc07 commit 02a26ba

File tree

5 files changed

+254
-10
lines changed

5 files changed

+254
-10
lines changed

‎README.md

+236-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,236 @@
1-
# Tutorials
1+
## Introduction
2+
![Tutorials UI](docs/tutorials.png)
3+
4+
The Tutorials are documents that contain helpful use cases, comments and interesting experience about Redis features and capabilities.
5+
6+
The content of the Tutorials can be updated autonomously without a need to update the entire application.
7+
8+
This document provides an overview of the Tutorials structure, its elements and contains instructions, recommendations, and best practices for updating the content of Tutorials.
9+
10+
11+
12+
## Navigation
13+
14+
1. [Structure](#Structure)
15+
2. [Pages](#Pages)
16+
3. [Autoupdate Flow](#Autoupdate)
17+
4. [Development Flow](#Development)
18+
19+
## Structure
20+
Tutorials allows you to render recursive objects, such as a file directory.
21+
22+
On the root level of [sources](https://github.com/RedisInsight/Tutorials/tree/main/src) folder, we have `tutorials.json` and all necessary static files (markdowns, images, etc.)
23+
24+
The content of this area is generated based on Nodes specified inside `tutorials.json`.
25+
This JSON file is described as a simple [Object](https://javascript.info/object) (Hash map), where key is a **string** and value is a **Node** (`Record<string, Node>`). Each Node requires a `label`,`type` and a unique `id` (all available properties are described in the table below).
26+
27+
| Prop | Type | Description |
28+
| -------------------- | --------------------------------------- | ----------- |
29+
| id (**required**) | string | |
30+
| type (**required**) | "group", "internal-link", "code-button" | |
31+
| label (**required**) | string | Label that will be displayed on UI for Node |
32+
| children | Record<string, Node> | Use only for "group" type |
33+
| args | Record<string, any> | A special set of parameters required by a certain type of node (each type has its own) |
34+
35+
A Node can be represented by various UI components and is specified by `type` prop. Supported types are listed below.
36+
37+
| Type | Description | Args |
38+
|----------------- |------------------------------------------------------------------------------------- |-------------- |
39+
| **"internal-link"** | A link that opens a page inside the Tutorials <br> (e.g. link to Redis Stack tutorial). | - "path" (required, string) - relative file path |
40+
| **"code-button"** | A button that inserts content into the Code Editor. | - "path" (required, string) - relative file path |
41+
| **"group"** | Grouping several nodes into one directory/folder. <br> Allows you to create nested lists | - "initialIsOpen" (boolean) - The group will start in the open state (default value - false) <br> - "withBorder" (boolean) - Display border at the bottom (default value - false) |
42+
43+
> _**!Note.** All **"internal-link"** nodes located in the same **"group"** will be connected to each other. And using pagination (created dynamically) you can go directly from one page to another. Therefore, it is best to combine elements into groups related to the same topic._
44+
45+
### Example with "Tutorials" group and two sections inside it
46+
```json
47+
{
48+
"tutorials": {
49+
"type": "group",
50+
"id": "tutorials",
51+
"label": "TUTORIALS",
52+
"args": {
53+
"withBorder": true,
54+
"initialIsOpen": true
55+
},
56+
"children": {
57+
"redis_stack": {
58+
"type": "group",
59+
"id": "redis_stack",
60+
"label": "Redis Stack",
61+
"args": {
62+
"initialIsOpen": false
63+
},
64+
"children": {
65+
"working_with_json": {
66+
"type": "internal-link",
67+
"id": "working_with_json",
68+
"label": "Working with JSON",
69+
"args": {
70+
"path": "/redis_stack/working_with_json.md"
71+
}
72+
},
73+
"vss": {
74+
"type": "internal-link",
75+
"id": "vector_similarity_search",
76+
"label": "Vector Similarity Search",
77+
"args": {
78+
"path": "/redis_stack/vector_similarity_search.md"
79+
}
80+
}
81+
}
82+
}
83+
}
84+
}
85+
}
86+
```
87+
## Pages
88+
By using **“internal-link”** node we can open other pages inside of Tutorials. To display more pages, add relevant files to the [src](https://github.com/RedisInsight/Tutorials/tree/main/src) folder.
89+
90+
These tutorials may contain the following elements:
91+
* Plain text
92+
* [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax/)
93+
* [Extended Markdown Syntax](https://www.markdownguide.org/extended-syntax/)
94+
* [HTML tags](https://www.markdownguide.org/basic-syntax/#html)
95+
* Images
96+
* Custom Syntax
97+
98+
### Images
99+
Basic Markdown syntax provides the ability to render images. ([Image Markdown Syntax](https://www.markdownguide.org/basic-syntax/#images-1))
100+
101+
You can use the absolute path
102+
```
103+
![RedisInsight Browser screenshot](https://github.com/RedisInsight/RedisInsight/blob/main/.github/redisinsight_browser.png)
104+
```
105+
or relative path to image inside the [statics](https://github.com/RedisInsight/Tutorials)
106+
```
107+
![RedisInsight Browser screenshot](/_images/browser.png)
108+
```
109+
110+
#### Redis Code block
111+
![Redis Code block](docs/tutorials-redis-code-block.png)
112+
A button that inserts Redis code into the Code Editor. The syntax is almost the same as for [Fenced Code Block](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), the only difference is that you must specify `redis` as language and the label next to it (`Create` in the example below).
113+
````
114+
```redis Create
115+
// Let's add three documents as Hashes.
116+
// Each document represents a building permit.
117+
118+
HSET permit:1 "description" "To reconstruct a single detached house with a front covered veranda." "construction_value" 42000 "building_type" "single detached house" "address_city" "Lisbon" "work_type" "demolition,reconstruction" "permit_timestamp" "1602156878" "address_street" "R. Da Palma" "location" "38.717746, -9.135839"
119+
120+
HSET permit:2 "description" "To construct a loft" "construction_value" 53000 "building_type" "apartment" "address_city" "Porto" "work_type" "construction" "permit_timestamp" "1556546400" "address_street" "Rua da Boavista" "location" "41.155854, -8.616721"
121+
122+
HSET permit:3 "description" "New house build" "construction_value" 260000 "building_type" "house" "address_city" "Lagos" "work_type" "construction;design" "permit_timestamp" "1612947600" "address_street" "R. Antonio Gedeao" "location" "37.114864, -8.668521"
123+
124+
```
125+
````
126+
## Autoupdate
127+
Our application supports the ability to quickly update the static files of the Enablement area so that we can provide users with up-to-date information.
128+
129+
EA tutorials auto-update flow:
130+
1. Push commit with updates to the main branch
131+
2. Wait until changes are merged into the latest branch
132+
3. Reopen the Redisinsight with a working internet connection. In the background, new files will be downloaded to the user's local home directory:
133+
* **Mac**: In the `/Users/<your-username>/.redisinsight-v2/tutorials` directory.
134+
* **Windows**: In the `C:\Users\<your-username>\.redisinsight-v2/tutorials` directory.
135+
* **Linux**: In the `/home/<your-username>/.redisinsight-v2/tutorials` directory.
136+
4. Open Enablement area on UI
137+
138+
## Development
139+
Let's imagine that we need to add a new group (Streams) with 2 pages (Basics, Getting data).
140+
141+
Step by step implementation would be as follows:
142+
1. First of all, it's best to create new pages locally and make sure that everything looks like it was planned.
143+
2. Clone Tutorials repository (if you haven't done it before) and go into `<folder to tutorials repo>/src`
144+
3. Create a new branch from the `main`
145+
4. Add new `streams` folder with `basics.md` and `getting-data.md`. As a result, the folder structure will look something like this.
146+
```
147+
Tutorials
148+
> Redis Stack
149+
> Working with JSON
150+
> streams
151+
basics.md
152+
getting-data.md
153+
tutorials.json
154+
```
155+
5. Add new nodes inside `tutorials.json`
156+
```json
157+
{
158+
"tutorials": {
159+
"type": "group",
160+
"id": "tutorials",
161+
"label": "TUTORIALS",
162+
"children": {
163+
"redis_stack": {"id": "redis_stack"...},
164+
"streams": {
165+
"type": "group",
166+
"id": "streams",
167+
"label": "Streams",
168+
"children": {
169+
"basics": {
170+
"type": "internal-link",
171+
"id": "basics",
172+
"label": "Basics",
173+
"args": {
174+
"path": "/streams/basics.md"
175+
}
176+
},
177+
"get-data": {
178+
"type": "internal-link",
179+
"id": "getting-data",
180+
"label": "Get Data",
181+
"args": {
182+
"path": "/streams/getting-data.md"
183+
}
184+
}
185+
}
186+
}
187+
}
188+
}
189+
}
190+
191+
```
192+
> _**!Note.** Markdown file name should have the same value as Node `id` to properly create pagination. _
193+
6. Fill markdowns with content.
194+
195+
`basics.md`
196+
````
197+
For the goal of understanding what Redis Streams are and how to use them, we will ignore all the advanced features, and instead focus on the data structure itself, in terms of commands used to manipulate and access it.
198+
This is, basically, the part that is common to most of the other Redis data types, like Lists, Sets, Sorted Sets and so forth.
199+
However, note that lists also have an optional more complex blocking API, exported by commands like BLPOP and similar.
200+
So streams are not much different than lists in this regard, it's just that the additional API is more complex and more powerful.
201+
202+
Because Streams are an append-only data structure, the fundamental write command, called **XADD**, appends a new entry into the specified stream.
203+
A stream entry is not just a string but is instead composed of one or multiple field-value pairs.
204+
This way, each entry of a stream is already structured, like an append-only file written in CSV format where multiple separated fields are present in each line.
205+
206+
```redis Create
207+
XADD mystream * sensor-id 1234 temperature 19.8
208+
```
209+
210+
````
211+
212+
`getting-data.md`
213+
````
214+
Querying by range: **XRANGE** and **XREVRANGE*
215+
To query the stream by the range we are only required to specify two IDs, _start_ and _end_.
216+
The range returned will include the elements having start or end as ID, so the range is inclusive. The two special IDs - and + respectively mean the smallest and the greatest ID possible.
217+
218+
```redis XRANGE
219+
XRANGE mystream - +
220+
```
221+
222+
```redis XREVRANGE
223+
XREVRANGE mystream + - COUNT 1
224+
```
225+
226+
227+
````
228+
7. Open **RedisInsight** application with `TUTORIALS` environment variable `TUTORIALS_DEV_PATH='<path to Tutorials repo>/src' ./<path to RedisInsight binary>`
229+
230+
Example on Linux: `TUTORIALS='/home/user/projects/Tutorials/src' ./home/user/programms/RedisInsight.AppImage`
231+
8. Make sure that everything looks fine.
232+
233+
234+
9. After that, just commit and push, and then create Pull Request to the main branch. (Release flow described in the [Autoupdate Flow](#Autoupdate) section).
235+
236+

‎_images/redisinsight_browser.png

674 KB
Loading

‎docs/tutorials-redis-code-block.png

311 KB
Loading

‎docs/tutorials.png

178 KB
Loading

0 commit comments

Comments
 (0)