GitBook: [#51] Relational to graph introduction and minor tidy-up

.gitbook/assets/family-tree-table.md

@@ -0,0 +1,9 @@
+| **person_id** | **name** | **DOB** | **mother_id** | **father_id** |
+| --------- | ---- | --- | --------- | --------- |
+| `1` | `Bob`     | `01/10/1979` | `2`  | `3`  |
+| `2` | `Zoe`     | `04/02/1956` | `4`  | `5`  |
+| `3` | `Bob Snr` | `28/11/1952` | `6`  | `7`  |
+| `4` | `Ada`     | `17/04/1922` | NULL | NULL |
+| `5` | `Tom`     | `01/09/1909` | NULL | NULL |
+| `6` | `Eva`     | `17/04/1923` | NULL | NULL |
+| `7` | `Ray`     | `03/10/1913` | NULL | NULL |

index/terminusx-db/explanations/relational-vs-graph-databases/README.md

@@ -0,0 +1,2 @@
+# Relational vs Graph Databases
+

index/terminusx-db/explanations/relational-vs-graph-databases/data-and-query-basics.md

@@ -0,0 +1,101 @@
+---
+description: >-
+  A comparative introduction to organizing and querying data in relational and
+  graph databases.
+---
+
+# Data and Query Basics
+
+## Key topics
+
+[Organizing data](data-and-query-basics.md#organizing-data)
+
+[Querying data](data-and-query-basics.md#querying-data)
+
+## Organizing data
+
+Relational and graph databases organize data is distinctly different ways.
+
+### Relational databases
+
+Traditional relational databases divide data into tables, columns, and rows.
+
+### Graph databases
+
+Similar to other graph databases, TerminusDB organizes data in objects. Objects have properties, properties link to other objects. A network of interlinked objects forms a graph structure - the foundation of graph databases.
+
+Using objects rather than cells enables the creation of databases that closely model the real world.
+
+## Example using a family tree
+
+A family tree database stores data representing individuals, their parents, and grandparents.
+
+### Relational databases
+
+The table below represents a model for storing this scenario in a relational database.
+
+### Graph databases
+
+The diagram further below illustrates the equivalent graph database model. An advantage of the graph model is that it represents real-world objects more accurately, making the model intuitive and easier to understand.
+
+#### Table: Family tree in a relational database
+
+| **person\_id** | **name**  | **DOB**      | **mother\_id** | **father\_id** |
+| -------------- | --------- | ------------ | -------------- | -------------- |
+| `1`            | `Bob`     | `01/10/1979` | `2`            | `3`            |
+| `2`            | `Zoe`     | `04/02/1956` | `4`            | `5`            |
+| `3`            | `Bob Snr` | `28/11/1952` | `6`            | `7`            |
+| `4`            | `Ada`     | `17/04/1922` | NULL           | NULL           |
+| `5`            | `Tom`     | `01/09/1909` | NULL           | NULL           |
+| `6`            | `Eva`     | `17/04/1923` | NULL           | NULL           |
+| `7`            | `Ray`     | `03/10/1913` | NULL           | NULL           |
+
+#### Diagram: Family tree in a graph database
+
+![](../../../../.gitbook/assets/terminusdb-data-modeling-family-tree-min.png)
+
+## Querying data
+
+### Relational database queries
+
+Many relational databases use the Structured Query Language (SQL.) The example below uses a two-query approach to get the name of mother, then grandmother. Note the second query uses two nested sub-queries.
+
+### Graph database queries
+
+TerminusDB's purpose-built Web Object Query Language (WOQL) is an easier-to-use alternative to SQL. The example below demonstrates the same query using WOQL. WOQL uses triple patterns to get both names in one short query. There are no joins - joins are implied by using the same ID in different parts of the query. Using `v:mother_id` multiple times creates the chain:
+
+`v:person_id = mother => v:mother = mother => v:grandmother`
+
+#### Code: Family tree traversal using SQL
+
+```sql
+select  name 
+from table_name 
+where person_id = (
+        select  mother_id
+        from table_name 
+        where name = "Bob")
+
+select  name 
+from table_name 
+where person_id = (
+        select mother_id
+        from table_name 
+        where person_id = (
+                select mother_id
+                from table_name 
+                where name = "Bob"))
+```
+
+#### Code: Family tree traversal using WOQL
+
+```javascript
+WOQL.and
+(
+   WOQL.triple("v:person", "mother", "v:mother_id"),
+   WOQL.triple("v:mother_id", "name", "v:mother_name"),
+   WOQL.triple("v:mother_id", "mother", "v:grandmother_id"),
+   WOQL.triple("v:grandmother_id", "name", "v:grandmother_name"),
+)
+```
+

index/terminusx-db/explanations/relational-vs-graph-databases/data-modeling-basics.md

@@ -0,0 +1,85 @@
+---
+description: >-
+  An introduction to data modeling and modeling terminology common to relational
+  and graph databases.
+---
+
+# Data Modeling Basics
+
+## Key topics
+
+[The importance of data modeling](broken-reference)
+
+[Modeling an organization](data-modeling-basics.md#modeling-an-organization)
+
+## The importance of data modeling
+
+The correct organization of data and the correct definition of the underlying database model or schema are critical to a business. TerminusDB organizes data in an object structure to facilitate modeling a business and the real world generally.
+
+## Modeling an organization
+
+Using a small organization as an example, use the step below to model and define a schema for the `organization` and its **elements** - `team`, `project`, `task`, and `employee`.
+
+**Data modeling steps**
+
+[Step 1. Identify the elements of the organization](data-modeling-basics.md#step-1.-identify-the-elements-of-the-organization)
+
+[Step 2. Identify the properties of each element](data-modeling-basics.md#step-2.-identify-the-properties-of-each-element)
+
+[Step 3. Identify the relationships between elements](data-modeling-basics.md#step-3.-identify-the-relationships-between-elements)
+
+### Element relationship modeling
+
+For relational and graph databases, an entity or element relationship model is a good way of implementing these steps. This helps to identify the components of the schema - its **elements**, **properties**, and **relationships**.
+
+#### Diagram: An element relationship model
+
+![](../../../../.gitbook/assets/terminusdb-data-modeling-organization-min.png)
+
+### Step 1. Identify the elements of the organization
+
+{% hint style="info" %}
+**Elements** are similar to entities in relational database terminology.
+{% endhint %}
+
+#### Table: Elements of an organization
+
+| **Element**    | **Description**                      |
+| -------------- | ------------------------------------ |
+| `organization` | The main organization.               |
+| `team`         | The teams within the `organization.` |
+| `employee`     | The employee assigned to `task`.     |
+| `project`      | The projects that a `team` creates.  |
+| `task`         | The tasks of the `project`.          |
+
+### Step 2. Identify the properties of each element
+
+{% hint style="info" %}
+**Properties** are similar to attributes in relational database terminology. A property is an item of data describing the element.
+{% endhint %}
+
+#### Table: The properties of elements
+
+| **Element**    | **Properties**                                     |
+| -------------- | -------------------------------------------------- |
+| `organization` | `name`, `desc`, `start-date`                       |
+| `team`         | `name`, `desc`, `start-date`                       |
+| `employee`     | `name`, `date-of-birth`, `start-date`, `role`      |
+| `project`      | `name`, `start-date`, `end-date`, `desc`, `status` |
+| `task`         | `name`, `start-date`, `end-date`, `desc`, `status` |
+
+### Step 3. Identify the relationships between elements
+
+{% hint style="info" %}
+**Relationships** are the same in graph and relational database terminology. Relationships define the associations or interactions between elements.
+{% endhint %}
+
+#### Table: The relationship between elements
+
+| **Element**    | **Element** | **Relationship (phrasal verb)** | **Relationship description**            |
+| -------------- | ----------- | ------------------------------- | --------------------------------------- |
+| `organization` | `team`      | `consists-of`                   | An `organization` `consists of` `team`s |
+| `team`         | `project`   | `collaborates-on`               | A `team` `collaborates-on` `project`s   |
+| `project`      | `task`      | `divided-into`                  | A `project` is `divided-into` `task`s   |
+| `task`         | `employee`  | `assigned-to`                   | A `task` is `assigned-to` an `employee` |
+

index/terminusx-db/explanations/relational-vs-graph-databases/data-modeling-in-terminusdb.md

@@ -0,0 +1,143 @@
+---
+description: An introduction to building data models using the TerminusDB dashboard.
+---
+
+# Data Modeling in TerminusDB
+
+## Key topics
+
+[Visual data modeling using the dashboard](data-modeling-in-terminusdb.md#visual-data-modeling-using-the-dashboard)
+
+[Data modeling using JSON](data-modeling-in-terminusdb.md#data-modeling-using-json)
+
+## Visual data modeling using the dashboard
+
+Use the **Data Product Model** view of the [TerminusDB dashboard](https://dashboard.terminusdb.com/product\_models) to visually build simple or complex data models. The diagrams further below illustrate two possible implementations of the organization model introduced in the previous section. In addition to visually building models, the dashboard enables:
+
+* Flexible relationships between elements such as documents and sub-documents, and classes and sub-classes.
+* Enumeration objects related to document elements.
+* A comprehensive set of properties (XSD data types) for elements.
+* JSON views of product models and properties.
+
+### A simple document model
+
+The diagram below illustrates an implementation of the organization model using a simple document structure. The enumeration objects hold status values applicable to projects and tasks.
+
+{% hint style="info" %}
+**Documents** and **elements** are identical.
+{% endhint %}
+
+#### Diagram: The organization model using documents
+
+![](../../../../.gitbook/assets/terminusdb-data-modeling-organization-dashboard-min.png)
+
+### A class-based document model
+
+The diagram below illustrates a more intuitive implementation of the organization model using documents and sub-documents, or classes or sub-classes. This approach enables sub-documents to inherit the properties of the parent document - similar to inheritance in Object-Oriented Programming. See [Data modeling using JSON](data-modeling-in-terminusdb.md#modeling-using-json) for more information.
+
+#### Diagram: The organization model using classes and sub-classes
+
+![](../../../../.gitbook/assets/terminusdb-data-modeling-organization-dashboard-sub-docs-min.png)
+
+## Data modeling using JSON
+
+TerminusDB supports the creation of data models using JavaScript Object Notation (JSON.) TerminusDB also generates JSON for models created visually using the dashboard.
+
+### Class hierarchies
+
+JSON supports the definition of classes and subclasses. Classes define **types** of complex data structures. Sub-classes inherit all parent data type definitions. Examples below.
+
+**Class**
+
+```javascript
+"@type": "Class",
+"@id": "organization",
+```
+
+**Subclass**
+
+```javascript
+"@type": "Class",
+"@id": "team",
+"@inherits": "organization",
+```
+
+**Properties for team**
+
+```javascript
+"name": "xsd:string",
+"desc": "xsd:string",
+"cost_code": "xsd:integer",
+"location": "xdd:coordinate",
+"setup_dt": "xsd:dateTime"
+```
+
+**JSON for the organization model**
+
+```javascript
+[
+  {
+    "@base": "terminusdb:///data/",
+    "@schema": "terminusdb:///schema#",
+    "@type": "@context"
+  },
+  {
+    "@id": "project-status",
+    "@type": "Enum",
+    "@value": [
+      "in-progress",
+      "on-hold",
+      "completed"
+    ]
+  },
+  {
+    "@id": "project",
+    "@inherits": "organization",
+    "@key": {
+      "@type": "Random"
+    },
+    "@type": "Class"
+  },
+  {
+    "@id": "organization",
+    "@key": {
+      "@type": "Random"
+    },
+    "@type": "Class"
+  },
+  {
+    "@id": "team",
+    "@inherits": "organization",
+    "@key": {
+      "@type": "Random"
+    },
+    "@type": "Class"
+  },
+  {
+    "@id": "task",
+    "@inherits": "project",
+    "@key": {
+      "@type": "Random"
+    },
+    "@type": "Class"
+  },
+  {
+    "@id": "task-status",
+    "@type": "Enum",
+    "@value": [
+      "in-progress",
+      "on-hold",
+      "completed"
+    ]
+  },
+  {
+    "@id": "employee",
+    "@inherits": "team",
+    "@key": {
+      "@type": "Random"
+    },
+    "@type": "Class"
+  }
+]
+```
+

index/terminusx-db/explanations/relational-vs-graph-databases/terminology-cheat-sheet.md

@@ -0,0 +1,16 @@
+---
+description: A summary of relational and TerminusDB graph database terms.
+---
+
+# Terminology Cheat Sheet
+
+| **Relational database term**                                                                   | **TerminusDB/graph database term**                                                                                                                                                             |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Attribute](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#attribute)       | Property                                                                                                                                                                                       |
+| Data type                                                                                      | Data type                                                                                                                                                                                      |
+| Database                                                                                       | Database or Data Product                                                                                                                                                                       |
+| [Entity](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#entity) or Table    | Element, Document, Object, [Node](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#node), or [Vertex](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#node) |
+| Entity Relationship Model (ERM)                                                                | Element Relationship Model (ERM)                                                                                                                                                               |
+| [Relationship](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#relationship) | Relationship or [Edge](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#edge)                                                                                                 |
+| [Schema](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#schema)             | Schema                                                                                                                                                                                         |
+| Structured Query Language (SQL)                                                                | Web Object Query Language ([WOQL](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#woql))                                                                                     |