Update Graph.md

Basic-usage.md

@@ -37,20 +37,20 @@ Press `Create` button in the top toolbar or use `Ctrl+b` (`Cmd+b` for MacOS)
 keyboard shortcut to open a new tab for an inquiry. An inquiry consists of three
 parts: SQL query, result set (result of the query execution) and visualisation
 of the result set. A tab consists of two panels. Each of them can show one of
-the three parts of inquiry. By default the top panel shows SQL query editor and
+the three parts of inquiry. By default, the top panel shows SQL query editor and
 the bottom panel shows the result set. You can switch any panel to any other
-view with corresponding buttons in the right side toolbar.
+view with the  corresponding buttons in the right side toolbar.
 
 * ![](./img/sql.svg) – Switch the panel to an SQL query editor. In that
-  editor you can specify and run not only a `SELECT` statement for getting data
+  editor, you can specify and run not only a `SELECT` statement for getting data
   but also DDL/DML statements for modifying the database.
 * ![](./img/table.svg) – Switch the panel to the result set. Here you
   can see the result of the query execution.
 * ![](./img/visualisation.svg) – Switch the panel to visualisation. This
-  panel allows building a pivot table and charts from the result set.
+  panel allows building a pivot table, a graph or charts from the result set.
 
 > **Note:** The query editor can show you hints: SQL keywords, table and column
-> names. In a common case column names are shown in the hint if you specify the
+> names. In a common case, column names are shown in the hint if you specify the
 > table name, e.g. `SELECT table_name.`. But if there is only one table in your
 > database column names will be always available in the hint. Press `Ctrl+Space`
 > to show a hint explicitly.
@@ -59,7 +59,7 @@ view with corresponding buttons in the right side toolbar.
 
 Press ![](./img/run.svg) button in the right side toolbar of an SQL
 editor panel or use `Ctrl+r` or `Ctrl+Enter` (`Cmd+r` or `Cmd+Enter` for MacOS)
-keyboard shortcut to execute a query in the current opened tab.
+keyboard shortcut to execute a query in the current open tab.
 
 > **Note:**  Running is not available if a query for the current tab is not
 > specified.
@@ -74,14 +74,15 @@ visualisation panel.
 
 * ![](./img/chart.svg) – Switch to a chart type visualisation.
 * ![](./img/pivot.svg) – Switch to a pivot type visualisation.
-
-> **Note:**  All unsaved changes in the current visualisation will be lost when
-> you switch to the other visualisation type.
+* ![](./img/graph.svg) – Switch to a graph type visualisation.
 
 A pivot table can be represented as a regular or multi-header table or
 visualised with a chart.
 Read more details of working with pivot in [Pivot tables][2].
 
+There are some requirements for the result set to build a graph. 
+Read more in [Graph][3].
+
 All customised charts in sqliteviz are created with a `react-chart-editor`
 component (fig. 5). The same component with some additional features is used in
 Plotly Chart Studio. Explore its [documentation][1] to learn how to build charts
@@ -104,3 +105,4 @@ After that, the inquiry will be in the list on `Inquiries` page.
 
 [1]: https://plotly.com/chart-studio-help/tutorials/#basic
 [2]: ../Pivot-table
+[3]: ../Graph

Graph.md

@@ -0,0 +1,212 @@
+# Graph
+
+Sqliteviz supports graph (network) visualisation. To build a graph, first run a query to get data.
+Then open the visualisation panel by clicking ![](./img/visualisation.svg)
+in any of the two-side toolbars and choose the graph mode by clicking ![](./img/graph.svg).
+
+## Requirements for result set
+
+To build a graph, a result set must follow the following requirements:
+
+- the first column must contain JSON documents (subsequent columns in the result set are ignored)
+- each JSON document has a key indicating whether the document represents a node/vertex (value `0`)
+  or an edge (value `1`)
+- each JSON document representing a node has a key with the node/vertex id
+- each JSON document representing an edge has a key with the edge source node/vertex and a key with
+  the edge target node/vertex
+
+That is what is the minimum required for a graph, but the JSON documents can have more fields used
+in graph styling (read [Graph styling](#graph-styling)).
+
+See also an example in [How to get a result set suitable for graph visualisation][1].
+
+## Graph structure
+
+Start building a graph by setting a mapping from your documents to node and edge properties.
+Go to `Structure` > `Graph` and set the following fields:
+
+- Object type – a field containing `0` for node documents and `1` for edge documents.
+- Node Id – a field containing the node identifier
+- Edge source – a field keeping a node identifier where the edge begins.
+- Edge target – a field keeping a node identifier where the edge ends.
+
+This is already enough to build a graph with default styling and circular layout.
+
+![Fig. 1: Graph structure settings](./img/Screenshot_graph_structure.png)
+
+## Graph styling
+
+### General
+
+Set a background color of the graph in `Style` > `General` panel.
+
+### Nodes
+
+There are the following settings in `Style` > `Nodes` panel:
+
+- Label - a field containing the node label. Note that if the graph has too many nodes or the node
+  size is too small, some labels can be visible only at a certain zoom level.
+- Label Color - a color of node labels
+- Size - set a node size. There are 3 modes of node sizing: constant, variable and calculated.
+
+  - `Constant` means that all nodes have the same given size.
+  - `Variable` allows you to choose a field where the node size is taken from.
+  - `Calculated` allows you to choose a method that is used to calculate the node size.
+
+    Currently, 3 methods are available: total node degree, degree by in-edges and
+    degree by out-edges.
+
+  For variable and calculated sizing it's also possible to set the scale, the minimum
+  size and the sizing mode - area or diameter. In the diameter mode the difference
+  between node sizes is more noticeable.
+
+- Color - set a node color. There are 3 modes of node color: constant, variable and calculated.
+
+  - `Constant` means that all nodes have the same color.
+  - `Variable` allows you to choose a field by which the color is determined.
+    With this option you can also choose if the color value should be taken directly or mapped to a
+    color palette.
+    
+    `Direct` mode means that in the JSON document representing the node, the value in the selected
+    field is used as a color. The color value in the JSON document can be set in different
+    ways:
+
+    1. As Hex, 8-digit (RGBA) Hex:
+
+       ```
+       #000
+       000
+       #369C
+       369C
+       #f0f0f6
+       f0f0f6
+       #f0f0f688
+       f0f0f688
+       ```
+
+    2. RGB, RGBA:
+
+       ```
+       // As a string:
+       rgb(255, 0, 0)
+       rgb 255 0 0
+       rgba(255, 0, 0, .5)
+
+       // As a nested structure:
+       { "r": 255, "g": 0, "b": 0 }
+       ```
+
+    3. HSL, HSLA:
+
+       ```
+       // As a string:
+       hsl(0, 100%, 50%)
+       hsla(0, 100%, 50%, .5)
+       hsl(0, 100%, 50%)
+       hsl 0 1.0 0.5
+
+       // As a nested structure:
+       { "h": 0, "s": 1, "l": .5 }
+       ```
+
+    4. HSV, HSVA:
+
+       ```
+       // As a string:
+       hsv(0, 100%, 100%)
+       hsva(0, 100%, 100%, .5)
+       hsv(0 100% 100%)
+       hsv 0 1 1
+
+       // As a nested structure:
+       { "h": 0, "s": 100, "v": 100 }
+       ```
+
+    5. Named colors:
+
+       Case insensitive names are accepted, using the list of [colors in the CSS
+       spec][2].
+
+       ```
+       RED
+       blanchedalmond
+       darkblue
+       ```
+
+    When `Map to` option is selected, the value by the selected field can be anything because it
+    won't be used directly as a color. In this case each distinct value will be mapped to a certain
+    color, so nodes with the same value will have the same color. Click on a color palette to open a
+    palette selector.
+
+  `Calculated` color mode allows to choose a method that will be used to determine a color.
+  Currently, 3 methods are available: total node degree, degree by in-edges and degree by
+  out-edges. You can also choose a color palette that will be used in a mapping of calculated
+  values into an actual color.
+
+- Color As - defines how color mapping should work - continuously or categorically.
+
+  Continuous mode is more suitable when the mapped values have a meaningful order. It looks more
+  informative with sequential palettes. In that case the lowest value corresponds to the first
+  color in the palette and the highest value - to the last color. The color of each intermediate
+  value reflects the position of that value in the range.
+
+  Categorical mode just uses the next color in the palette for each new distinct value.
+
+- Colorscale Direction - use the selected palette as is or reverse it.
+
+### Edges
+
+There are the following settings in `Style` > `Edges` panel:
+
+- Direction - show an edges with or without arrows
+- Label - a field containing an edge label. Note that if the graph has too many edges,
+  some labels can be visible only at a certain zoom level.
+- Label Color - a color of edge labels
+- Size - set an edge thickness. There are 2 modes of edge sizing: constant and variable.
+
+  - `Constant` means that all edges have the same thickness.
+  - `Variable` allows you to choose a field where the edge size is taken from.
+
+    For variable sizing it's also possible to set the scale and the minimum size.
+
+- Color - set an edge color. There are 2 modes of edge color: constant and variable. They work
+  similar to the node color modes.
+
+- Color As - defines how color mapping should work - continuously or categorically, similar to the
+  node color setting.
+
+- Colorscale Direction - use the selected palette as is or reverse it.
+
+### Layout
+
+#### Circular
+
+In this layout all nodes are just placed along a circle.
+
+#### Random
+
+This layout places nodes randomly for each seed value. The seed value allows you to restore the
+random layout you liked when you open the inquiry and run the query next time.
+
+![Fig. 2: Random layout](./img/Screenshot_graph_random.png)
+
+#### Circle pack
+
+Arranges nodes as a bubble chart according to specified attributes. You can choose multiple
+hierarchy attributes to group nodes.
+
+![Fig. 3: Circle pack layout](./img/Screenshot_graph_circle_pack.png)
+
+#### ForceAtlas2
+
+A continuous graph layout algorithm. Read more details about the algorithm and its settings in the
+[article][3]. The algorithm works iteratively. When you choose ForceAtlas2 layout or run the query,
+it is automatically run 50 iterations of the algorithm. You can change the amount of steps run
+automatically in `Initial Iterations`. You can also run and stop the algorithm manually by
+clicking `Start`/`Stop` button.
+
+![Fig. 3: ForceAtlas2 layout](./img/Screenshot_graph_force_atlas2.png)
+
+[1]: ./How-to-get-result-set-suitable-for-graph-visualisation
+[2]: https://www.w3.org/TR/css-color-4/#named-colors
+[3]: https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0098679

Home.md

@@ -6,10 +6,11 @@ Welcome to the sqliteviz wiki!
 3. [Multiple file import][9]
 4. [Manage inquiries][2]
 5. [Export current database][4]
-6. [Pivot table][3]
-7. [Predefined inquiries][5]
-8. [Sharing][11]
-9. [Diagnostic information][6]
+6. [Graph][13]
+7. [Pivot table][3]
+8. [Predefined inquiries][5]
+9. [Sharing][11]
+10. [Diagnostic information][6]
 
 ## Examples and tutorials
 1. [How to rename tables and columns after CSV import][8]
@@ -32,3 +33,4 @@ Welcome to the sqliteviz wiki!
 [10]: How-to-build-a-pivot-table-in-SQLite
 [11]: Sharing
 [12]: How-to-rename-tables-and-columns-after-csv-import
+[13]: Graph

How-to-get-result-set-suitable-for-graph-visualisation.md

@@ -0,0 +1,120 @@
+# How to get a result set suitable for graph visualisation
+
+There are some [requirements for result sets][1] if you want to make a graph.
+Here is an example of building a query that returns a result set appropriate for graph 
+visualisation.
+
+Let's say, you have 2 tables:
+
+1. `house`:
+
+   | name       | points |
+   | ---------- | ------ |
+   | Gryffindor | 100    |
+   | Hufflepuff | 90     |
+   | Ravenclaw  | 95     |
+   | Slytherin  | 80     |
+
+2. `student`:
+
+   | id | name           | house      |
+   | -- | -------------- | ---------- |
+   | 1  | Harry Potter   | Gryffindor |
+   | 2  | Ron Weasley    | Gryffindor |
+   | 3  | Draco Malfoy'  | Slytherin  |
+   | 4  | Luna Lovegood  | Ravenclaw  |
+   | 5  | Cedric Diggory | Hufflepuff |
+
+Each student belongs to a certain house. 
+Let's say you want to build a graph with houses and students as nodes, where each house is linked 
+with its students.
+
+We are going to use [json_object][2] function to form JSON documents. The result set should contain 
+both nodes and edges and we have to provide a field indicating if the document represents a node 
+(0) or and edge (1). Let's provide it as `object_type`:
+
+```sql
+SELECT json_object('object_type', 0)
+FROM house
+UNION ALL
+SELECT json_object('object_type', 0)
+FROM student
+UNION ALL
+SELECT json_object('object_type', 1)
+FROM student
+```
+
+Note that we included `student` table twice. That is because the table contains not only students 
+but also their relationship to houses. So the records from the first union of `student` are used 
+as nodes and from the second one - as edges.
+
+Then we need to provide an ID for each node. Let's put it in `node_id` field. The `node_id` value 
+for students is taken from `id` column and for houses - from `name`: 
+
+```sql
+SELECT json_object('object_type', 0, 'node_id', name)
+FROM house
+UNION ALL
+SELECT json_object('object_type', 0, 'node_id', id)
+FROM student
+UNION ALL
+SELECT json_object('object_type', 1)
+FROM student
+```
+
+Each edge document must provide a node id where the edge begins and where it ends. Let's put it in
+`source` and `target`:
+
+```sql
+SELECT json_object('object_type', 0, 'node_id', name)
+FROM house
+UNION ALL
+SELECT json_object('object_type', 0, 'node_id', id)
+FROM student
+UNION ALL
+SELECT json_object('object_type', 1, 'source', house, 'target', id)
+FROM student
+```
+
+Basically, that is enough to build a graph. But it is not very meaningful without labels.
+Also, it would be nice to distinguish house nodes from student nodes by color.
+Let's put additional fields `label` and `type` that can be used in graph styling.
+
+```sql
+SELECT json_object('object_type', 0, 'node_id', name, 'label', name, 'type', 'house') AS graph_object
+FROM house
+UNION ALL
+SELECT json_object('object_type', 0, 'node_id', id, 'label', name, 'type', 'student')
+FROM student
+UNION ALL
+SELECT json_object('object_type', 1, 'source', house, 'target', id)
+FROM student
+```
+
+Run the query, the result set will look like this:
+
+| graph_object                                                                   |
+| ------------------------------------------------------------------------------ |
+| {"object_type":0,"node_id":"Gryffindor","label":"Gryffindor","type":"house"}   |
+| {"object_type":0,"node_id":"Hufflepuff","label":"Hufflepuff","type":"house"}   |
+| {"object_type":0,"node_id":"Ravenclaw","label":"Ravenclaw","type":"house"}     |
+| {"object_type":0,"node_id":"Slytherin","label":"Slytherin","type":"house"}     |
+| {"object_type":0,"node_id":1,"label":"Harry Potter","type":"student"}          |
+| {"object_type":0,"node_id":2,"label":"Ron Weasley","type":"student"}           |
+| {"object_type":0,"node_id":3,"label":"Draco Malfoy","type":"student"}          |
+| {"object_type":0,"node_id":4,"label":"Luna Lovegood","type":"student"}         |
+| {"object_type":0,"node_id":5,"label":"Cedric Diggory","type":"student"}        |
+| {"object_type":1,"node_source":"Gryffindor","target":1}                        |
+| {"object_type":1,"node_source":"Gryffindor","target":2}                        |
+| {"object_type":1,"node_source":"Slytherin","target":3}                         |
+| {"object_type":1,"node_source":"Ravenclaw","target":4}                         |
+| {"object_type":1,"node_source":"Hufflepuff","target":5}                        |
+
+Now in the graph editor, we can set mapping of the result set documents into node and edge 
+properties, set graph styles and get the following visualisation:
+
+![Fig. 1: Graph visualisation example](./img/Screenshot_potter_example.png)
+
+
+[1]: ./graph#requirements-for-result-set
+[2]: https://sqlite.org/json1.html#jobj

img/graph.svg

@@ -0,0 +1,8 @@
+<svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M5 4C5 5.10457 4.10457 6 3 6C1.89543 6 1 5.10457 1 4C1 2.89543 1.89543 2 3 2C4.10457 2 5 2.89543 5 4Z" fill="#A2B1C6"/>
+<path d="M17 7.5C17 8.88071 15.8807 10 14.5 10C13.1193 10 12 8.88071 12 7.5C12 6.11929 13.1193 5 14.5 5C15.8807 5 17 6.11929 17 7.5Z" fill="#A2B1C6"/>
+<path d="M8 13.5C8 14.8807 6.88071 16 5.5 16C4.11929 16 3 14.8807 3 13.5C3 12.1193 4.11929 11 5.5 11C6.88071 11 8 12.1193 8 13.5Z" fill="#A2B1C6"/>
+<path d="M2.93128 5.31436L3.90527 5.08778L5.48693 11.8867L4.51294 12.1133L2.93128 5.31436Z" fill="#A2B1C6"/>
+<path d="M12.9447 7.79159L13.5548 8.58392L7.30516 13.3962L6.69507 12.6038L12.9447 7.79159Z" fill="#A2B1C6"/>
+<path d="M14.1316 6.51712L3.13166 3.51723L2.86844 4.48202L13.8684 7.48191L14.1316 6.51712Z" fill="#A2B1C6"/>
+</svg>

index.md

@@ -4,10 +4,11 @@ Sqliteviz is a single-page offline-first PWA for fully client-side visualisation
 
 With sqliteviz you can:
 
-- run SQL queries against a SQLite database and create Plotly charts and pivot tables based on the result sets
+- run SQL queries against a SQLite database and create Plotly charts, graphs and pivot tables based on the result sets
 - import a CSV, JSON or NDJSON file into a SQLite database and visualize imported data
 - export result set to CSV file
 - manage inquiries and run them against different databases
 - import/export inquiries from/to a JSON file
 - export a modified SQLite database
 - use it offline from your OS application menu like any other desktop app
+

sidebar.json

@@ -8,6 +8,7 @@
 				"/docs/multiple-csv-file-import/",
 				"/docs/manage-inquiries/",
 				"/docs/export-current-database/",
+				"/docs/graph/",
 				"/docs/pivot-table/",
 				"/docs/predefined-inquiries/",
 				"/docs/sharing/",