Update Graph.md

Graph.md

@@ -1,54 +1,124 @@
 # Graph
 
-## Pivot table UI
+Sqliteviz allows building a graph. To build a graph, 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 a graph mode by clicking ![](./img/graph.svg).
 
-Sqliteviz allows building pivot tables and visualizing them. To build a graph
+## Requirements for result set
-run a query to get data. Then open visualisation panel by clicking ![](./img/visualisation.svg)
-in any of the two side toolbars and choose a pivot mode by clicking ![](./img/graph.svg).
 
-A pivot visualisation has the following settings:
+To build a graph, a result set must follow the following requirements:
 
-- Columns – choose one or more column names from the result set. The values in
+- the first column must contain JSONs (the rest columns in the result set will be ignored)
-  the chosen columns will be column names of the pivot table.
+- each JSON has a common key indicating if the record represents a node (value 0) or an edge (value 1)
-- Rows – choose one or more column names from the result set. The values in the
+- each JSON representing a node has a common key with a node id
-  chosen columns will be row names of the pivot table.
+- each JSON representing an edge has a common key with the edge source and a common key with the edge target
-- Order of columns and rows.
-- Aggregator and its arguments – a function which will be used for pivot cell
-  calculation. An aggregator can have from zero to two arguments. An aggregator
-  argument is one of the columns of the result set.
-- View – pivot table visualisation. It can be a table, a heatmap, a chart,
-  etc. See some examples of different views of the same pivot table below.
 
-![Fig. 1: Table](./img/Screenshot_pivot_table.png)
+Each JSON can have more fields used for graph styling (read more in [Graph styling](#graph-styling)).
 
-![Fig. 2: Heatmap](./img/Screenshot_pivot_heatmap.png)
+## Graph structure
 
-![Fig. 3: Horizontal Stacked Bar Chart](./img/Screenshot_pivot_barchart.png)
+Start building a graph by setting a mapping from your records to nodes and edge properties.
+Go to `Structure` > `Graph` and set the following fields:
 
-There are several built-in chart views for a pivot. But you can build your own
+- Object type – a field containing 0 for node records and 1 for edge records.
-with `Custom chart` view (fig. 4).
+- Node Id – a field containing the node identifier
+- Edge source - a field keeping a node identifier where the edge starts.
+- Edge target - a field keeping a node identifier where the edge ends.
 
-![Fig. 4: Custom Chart](./img/Screenshot_pivot_custom_chart.png)
+This is already enough to build a graph with default styling and circular layout.
 
-> **Note:**  You can switch to other pivot views and back to `Custom chart` –
+![Fig. 1: Graph structure settings](./img/Screenshot_graph_structure.png)  
-> all your custom chart settings will be remembered. But if you switch the
-> visualisation mode from pivot to any other mode, unsaved changes will be lost.
 
-You can save any visualisation as an image by clicking ![](./img/camera.svg).
+## Graph styling
 
-## Pivot table SQL
+### General
 
-Pivot table (in the form of a result set) can be built on the SQL-level and,
+Set a background color of the graph in `Style` > `General` panel.
-technically speaking, can be visualised as any other result set. Practically
-though there are a couple of challenges with that:
 
-1. Visualising a dataset of long/tall shape is much more convenient in Plotly
+### Nodes
-   (chart editor) rather than one of wide/fat shape.
-2. SQLite doesn't have a special constructs like `PIVOT` or `CROSSTAB` in
-   its SQL dialect.
 
+There are the following settings in `Style` > `Nodes` panel:
+
+- Label - a field containing a node label. Note that if the graph has too many nodes,
+  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 size.
+  
+  `Variable` allows you to choose a field where the node size will be taken.
+  
+  `Calculated` allows to choose a method that will be 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 scale, the minimum size and the sizing mode - area or diameter.
+  In the diameter mode the difference between node sizes will be 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 will be 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 JSON representing a node, the value available by the selected field will be used as a color.
+  The color value can be set in different ways:
+
+  **As Hex, 8-digit (RGBA) Hex**
+  ```
+  "#000"
+  "000"
+  "#369C"
+  "369C"
+  "#f0f0f6"
+  "f0f0f6"
+  "#f0f0f688"
+  "f0f0f688"
+  ```
+  **RGB, RGBA**
+  ```
+  "rgb (255, 0, 0)"
+  "rgb 255 0 0"
+  "rgba (255, 0, 0, .5)"
+  { "r": 255, "g": 0, "b": 0 }
+  ```
+
+  **HSL, HSLA**
+  ```
+  "hsl(0, 100%, 50%)"
+  "hsla(0, 100%, 50%, .5)"
+  "hsl(0, 100%, 50%)"
+  "hsl 0 1.0 0.5"
+  { "h": 0, "s": 1, "l": .5 }
+  ```
+
+  **HSV, HSVA**
+  ```
+  "hsv(0, 100%, 100%)"
+  "hsva(0, 100%, 100%, .5)"
+  "hsv (0 100% 100%)"
+  "hsv 0 1 1"
+  { "h": 0, "s": 100, "v": 100 }
+  ```
+
+  **Named colors**
+  Case insenstive names are accepted, using the list of [colors in the CSS spec][3].
+  ```
+  "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 instead will be mapped to a certain color, so nodes with the same value will have the same color.
+  You can choose a palette used in color mapping.
+  
+  `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.
+
+  
 [How to build a pivot table in SQL(ite)][1] explores two options with static
 (or beforehand-known) and dynamic columns.
 
 [1]: ../How-to-build-a-pivot-table-in-SQ-Lite
+[2]: https://github.com/bgrins/TinyColor?tab=readme-ov-file#accepted-string-input
+[3]: https://www.w3.org/TR/css-color-4/#named-colors