Skip to content

Commit 071ad6f

Browse files
GavinMendelGleasongitbook-bot
GavinMendelGleason
authored and
gitbook-bot
committed
GitBook: [#51] Relational to graph introduction and minor tidy-up
1 parent c7e692a commit 071ad6f

28 files changed

+3707
-2855
lines changed

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

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

‎.gitbook/assets/terminusdb-data-modeling-family-tree (1).png

243 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-family-tree-min.png

58.1 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-family-tree.png

211 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-organization (1).png

193 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-organization-dashboard-min.png

61.9 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-organization-dashboard-sub-docs-min.png

45.3 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-organization-dashboard-sub-docs.png

164 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-organization-dashboard.png

224 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-organization-min.png

54.2 KB
Loading

‎.gitbook/assets/terminusdb-data-modeling-organization.png

199 KB
Loading

‎.gitbook/assets/terminusdb-woql-concepts.png

39.3 KB
Loading

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

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Relational vs Graph Databases
2+

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

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
description: >-
3+
A comparative introduction to organizing and querying data in relational and
4+
graph databases.
5+
---
6+
7+
# Data and Query Basics
8+
9+
## Key topics
10+
11+
[Organizing data](data-and-query-basics.md#organizing-data)
12+
13+
[Querying data](data-and-query-basics.md#querying-data)
14+
15+
## Organizing data
16+
17+
Relational and graph databases organize data is distinctly different ways.
18+
19+
### Relational databases
20+
21+
Traditional relational databases divide data into tables, columns, and rows.
22+
23+
### Graph databases
24+
25+
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.
26+
27+
Using objects rather than cells enables the creation of databases that closely model the real world.
28+
29+
## Example using a family tree
30+
31+
A family tree database stores data representing individuals, their parents, and grandparents.
32+
33+
### Relational databases
34+
35+
The table below represents a model for storing this scenario in a relational database.
36+
37+
### Graph databases
38+
39+
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.
40+
41+
#### Table: Family tree in a relational database
42+
43+
| **person\_id** | **name** | **DOB** | **mother\_id** | **father\_id** |
44+
| -------------- | --------- | ------------ | -------------- | -------------- |
45+
| `1` | `Bob` | `01/10/1979` | `2` | `3` |
46+
| `2` | `Zoe` | `04/02/1956` | `4` | `5` |
47+
| `3` | `Bob Snr` | `28/11/1952` | `6` | `7` |
48+
| `4` | `Ada` | `17/04/1922` | NULL | NULL |
49+
| `5` | `Tom` | `01/09/1909` | NULL | NULL |
50+
| `6` | `Eva` | `17/04/1923` | NULL | NULL |
51+
| `7` | `Ray` | `03/10/1913` | NULL | NULL |
52+
53+
#### Diagram: Family tree in a graph database
54+
55+
![](../../../../.gitbook/assets/terminusdb-data-modeling-family-tree-min.png)
56+
57+
## Querying data
58+
59+
### Relational database queries
60+
61+
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.
62+
63+
### Graph database queries
64+
65+
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:
66+
67+
`v:person_id = mother => v:mother = mother => v:grandmother`
68+
69+
#### Code: Family tree traversal using SQL
70+
71+
```sql
72+
select name
73+
from table_name
74+
where person_id = (
75+
select mother_id
76+
from table_name
77+
where name = "Bob")
78+
79+
select name
80+
from table_name
81+
where person_id = (
82+
select mother_id
83+
from table_name
84+
where person_id = (
85+
select mother_id
86+
from table_name
87+
where name = "Bob"))
88+
```
89+
90+
#### Code: Family tree traversal using WOQL
91+
92+
```javascript
93+
WOQL.and
94+
(
95+
WOQL.triple("v:person", "mother", "v:mother_id"),
96+
WOQL.triple("v:mother_id", "name", "v:mother_name"),
97+
WOQL.triple("v:mother_id", "mother", "v:grandmother_id"),
98+
WOQL.triple("v:grandmother_id", "name", "v:grandmother_name"),
99+
)
100+
```
101+

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

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
description: >-
3+
An introduction to data modeling and modeling terminology common to relational
4+
and graph databases.
5+
---
6+
7+
# Data Modeling Basics
8+
9+
## Key topics
10+
11+
[The importance of data modeling](broken-reference)
12+
13+
[Modeling an organization](data-modeling-basics.md#modeling-an-organization)
14+
15+
## The importance of data modeling
16+
17+
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.
18+
19+
## Modeling an organization
20+
21+
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`.
22+
23+
**Data modeling steps**
24+
25+
[Step 1. Identify the elements of the organization](data-modeling-basics.md#step-1.-identify-the-elements-of-the-organization)
26+
27+
[Step 2. Identify the properties of each element](data-modeling-basics.md#step-2.-identify-the-properties-of-each-element)
28+
29+
[Step 3. Identify the relationships between elements](data-modeling-basics.md#step-3.-identify-the-relationships-between-elements)
30+
31+
### Element relationship modeling
32+
33+
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**.
34+
35+
#### Diagram: An element relationship model
36+
37+
![](../../../../.gitbook/assets/terminusdb-data-modeling-organization-min.png)
38+
39+
### Step 1. Identify the elements of the organization
40+
41+
{% hint style="info" %}
42+
**Elements** are similar to entities in relational database terminology.
43+
{% endhint %}
44+
45+
#### Table: Elements of an organization
46+
47+
| **Element** | **Description** |
48+
| -------------- | ------------------------------------ |
49+
| `organization` | The main organization. |
50+
| `team` | The teams within the `organization.` |
51+
| `employee` | The employee assigned to `task`. |
52+
| `project` | The projects that a `team` creates. |
53+
| `task` | The tasks of the `project`. |
54+
55+
### Step 2. Identify the properties of each element
56+
57+
{% hint style="info" %}
58+
**Properties** are similar to attributes in relational database terminology. A property is an item of data describing the element.
59+
{% endhint %}
60+
61+
#### Table: The properties of elements
62+
63+
| **Element** | **Properties** |
64+
| -------------- | -------------------------------------------------- |
65+
| `organization` | `name`, `desc`, `start-date` |
66+
| `team` | `name`, `desc`, `start-date` |
67+
| `employee` | `name`, `date-of-birth`, `start-date`, `role` |
68+
| `project` | `name`, `start-date`, `end-date`, `desc`, `status` |
69+
| `task` | `name`, `start-date`, `end-date`, `desc`, `status` |
70+
71+
### Step 3. Identify the relationships between elements
72+
73+
{% hint style="info" %}
74+
**Relationships** are the same in graph and relational database terminology. Relationships define the associations or interactions between elements.
75+
{% endhint %}
76+
77+
#### Table: The relationship between elements
78+
79+
| **Element** | **Element** | **Relationship (phrasal verb)** | **Relationship description** |
80+
| -------------- | ----------- | ------------------------------- | --------------------------------------- |
81+
| `organization` | `team` | `consists-of` | An `organization` `consists of` `team`s |
82+
| `team` | `project` | `collaborates-on` | A `team` `collaborates-on` `project`s |
83+
| `project` | `task` | `divided-into` | A `project` is `divided-into` `task`s |
84+
| `task` | `employee` | `assigned-to` | A `task` is `assigned-to` an `employee` |
85+

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

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
description: An introduction to building data models using the TerminusDB dashboard.
3+
---
4+
5+
# Data Modeling in TerminusDB
6+
7+
## Key topics
8+
9+
[Visual data modeling using the dashboard](data-modeling-in-terminusdb.md#visual-data-modeling-using-the-dashboard)
10+
11+
[Data modeling using JSON](data-modeling-in-terminusdb.md#data-modeling-using-json)
12+
13+
## Visual data modeling using the dashboard
14+
15+
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:
16+
17+
* Flexible relationships between elements such as documents and sub-documents, and classes and sub-classes.
18+
* Enumeration objects related to document elements.
19+
* A comprehensive set of properties (XSD data types) for elements.
20+
* JSON views of product models and properties.
21+
22+
### A simple document model
23+
24+
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.
25+
26+
{% hint style="info" %}
27+
**Documents** and **elements** are identical.
28+
{% endhint %}
29+
30+
#### Diagram: The organization model using documents
31+
32+
![](../../../../.gitbook/assets/terminusdb-data-modeling-organization-dashboard-min.png)
33+
34+
### A class-based document model
35+
36+
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.
37+
38+
#### Diagram: The organization model using classes and sub-classes
39+
40+
![](../../../../.gitbook/assets/terminusdb-data-modeling-organization-dashboard-sub-docs-min.png)
41+
42+
## Data modeling using JSON
43+
44+
TerminusDB supports the creation of data models using JavaScript Object Notation (JSON.) TerminusDB also generates JSON for models created visually using the dashboard.
45+
46+
### Class hierarchies
47+
48+
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.
49+
50+
**Class**
51+
52+
```javascript
53+
"@type": "Class",
54+
"@id": "organization",
55+
```
56+
57+
**Subclass**
58+
59+
```javascript
60+
"@type": "Class",
61+
"@id": "team",
62+
"@inherits": "organization",
63+
```
64+
65+
**Properties for team**
66+
67+
```javascript
68+
"name": "xsd:string",
69+
"desc": "xsd:string",
70+
"cost_code": "xsd:integer",
71+
"location": "xdd:coordinate",
72+
"setup_dt": "xsd:dateTime"
73+
```
74+
75+
**JSON for the organization model**
76+
77+
```javascript
78+
[
79+
{
80+
"@base": "terminusdb:///data/",
81+
"@schema": "terminusdb:///schema#",
82+
"@type": "@context"
83+
},
84+
{
85+
"@id": "project-status",
86+
"@type": "Enum",
87+
"@value": [
88+
"in-progress",
89+
"on-hold",
90+
"completed"
91+
]
92+
},
93+
{
94+
"@id": "project",
95+
"@inherits": "organization",
96+
"@key": {
97+
"@type": "Random"
98+
},
99+
"@type": "Class"
100+
},
101+
{
102+
"@id": "organization",
103+
"@key": {
104+
"@type": "Random"
105+
},
106+
"@type": "Class"
107+
},
108+
{
109+
"@id": "team",
110+
"@inherits": "organization",
111+
"@key": {
112+
"@type": "Random"
113+
},
114+
"@type": "Class"
115+
},
116+
{
117+
"@id": "task",
118+
"@inherits": "project",
119+
"@key": {
120+
"@type": "Random"
121+
},
122+
"@type": "Class"
123+
},
124+
{
125+
"@id": "task-status",
126+
"@type": "Enum",
127+
"@value": [
128+
"in-progress",
129+
"on-hold",
130+
"completed"
131+
]
132+
},
133+
{
134+
"@id": "employee",
135+
"@inherits": "team",
136+
"@key": {
137+
"@type": "Random"
138+
},
139+
"@type": "Class"
140+
}
141+
]
142+
```
143+

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

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
description: A summary of relational and TerminusDB graph database terms.
3+
---
4+
5+
# Terminology Cheat Sheet
6+
7+
| **Relational database term** | **TerminusDB/graph database term** |
8+
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9+
| [Attribute](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#attribute) | Property |
10+
| Data type | Data type |
11+
| Database | Database or Data Product |
12+
| [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) |
13+
| Entity Relationship Model (ERM) | Element Relationship Model (ERM) |
14+
| [Relationship](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#relationship) | Relationship or [Edge](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#edge) |
15+
| [Schema](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#schema) | Schema |
16+
| Structured Query Language (SQL) | Web Object Query Language ([WOQL](https://terminusdb.com/docs/index/terminusx-db/resources/glossary#woql)) |

0 commit comments

Comments
 (0)