Skip to content

Commit 6c7b9a0

Browse files
juskekjuskek
committed
Init tutorial
0 parents  commit 6c7b9a0

File tree

6 files changed

+257
-0
lines changed

6 files changed

+257
-0
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# MacOS
2+
**/.DS_Store

‎README.md

+191
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Type DB Tutorial
2+
3+
This repository was created as a learning guide for me to pick up TypeDB as a beginner in databases and graphs. More complex examples can be [here](https://github.com/vaticle/typedb-examples).
4+
5+
- [Type DB Tutorial](#type-db-tutorial)
6+
- [1.1. Intro](#11-intro)
7+
- [1.2. TypeDB Building Blocks](#12-typedb-building-blocks)
8+
- [1.2.1. Schema](#121-schema)
9+
- [1.2.2. Types](#122-types)
10+
- [1.2.3. Rules](#123-rules)
11+
- [1.3. Getting Started](#13-getting-started)
12+
- [1.3.1. Creating a database and linking it to TypeDB Studio](#131-creating-a-database-and-linking-it-to-typedb-studio)
13+
- [1.4. Adding Data](#14-adding-data)
14+
- [1.4.1. Defining a Schema](#141-defining-a-schema)
15+
- [1.4.2. Inserting Data](#142-inserting-data)
16+
- [1.4.3. Loading Schema and Data](#143-loading-schema-and-data)
17+
- [1.4.4. Reading Data](#144-reading-data)
18+
19+
20+
## 1.1. Intro
21+
22+
There are three components in the TypeDB ecosystem:
23+
* TypeDB:
24+
25+
The main component of the ecosystem, which is a strongly typed graph database with TypeQL as its querying language.
26+
27+
* TypeDB Cluster
28+
29+
Allows you to deploy TypeDB as a cluster for high availability and scalability, but operates on the same principle as TypeDB.
30+
31+
* TypeDB Studio
32+
33+
Provides UI to interact with a TypeDB database.
34+
35+
36+
In this tutorial, we will be focusing on TypeDB and TypeDB Studio, and learning how to build a knowledge graph with them.
37+
38+
## 1.2. TypeDB Building Blocks
39+
40+
### 1.2.1. Schema
41+
42+
The schema is a representation of the domain, i.e., the logical grouping of data and the acceptable values.
43+
44+
The schema is built using **types** and **rules**.
45+
46+
### 1.2.2. Types
47+
48+
Types are a category of things having common characteristics.
49+
50+
There are three main types:
51+
52+
1. `entity`
53+
54+
Represents objects in the domain, e.g. person, company.
55+
56+
Can be extended, e.g. `person sub entity`.
57+
58+
2. `relation`
59+
60+
Represents connections in the domain, e.g. employment.
61+
62+
Can be extended, e.g. `employment sub relation`.
63+
64+
Has intrinsic role type to define how types are related, e.g.
65+
```
66+
define
67+
employment sub relation, relates employee, relates employer;
68+
person sub entity, plays employment:employee;
69+
company sub entity, plays employment:employer;
70+
```
71+
72+
Apart from connecting entities, relations can also connect attributes and other relations.
73+
74+
Relations can also be nested, e.g. a relation being a role player in another relation.
75+
76+
77+
3. `attribute`
78+
79+
Represents values in the domain, e.g. name.
80+
81+
Can be extended, e.g. `name sub attribute`.
82+
83+
Can be owned by entities, relations or other attributes.
84+
85+
Attribute instances are:
86+
* Globally unique by type and value
87+
* Immutable
88+
89+
90+
### 1.2.3. Rules
91+
92+
Rules allow you to define logic statements which can bring more insight. The logic statements are constructed in a when-then manner, e.g. when 2 persons are employed by the same company, then mutual employment.
93+
94+
## 1.3. Getting Started
95+
96+
1. [Install TypeDB](https://docs.vaticle.com/docs/running-typedb/install-and-run#system-requirements)
97+
2. [Install TypeDB Studio](https://github.com/vaticle/typedb-studio/tree/master)
98+
99+
Make sure to check [version compatibility between TypeDB and TypeDB Studio](https://docs.vaticle.com/docs/studio/overview#version-compatibility)
100+
3. Run TypeDB server from terminal: `typedb server`, and take note of the port no the server is running on, e.g. `listening to address: 0.0.0.0:1729`
101+
4. Open TypeDB Studio application
102+
5. Under 'Types', click 'Connect to TypeDB' and enter the address, e.g. `localhost:1729`
103+
104+
### 1.3.1. Creating a database and linking it to TypeDB Studio
105+
106+
1. Click the database icon in the top toolbar, and create a database named `knowledge_graph_tutorial`
107+
2. In the dropdown menu next to the database icon, select the newly created database.
108+
3. In the project sidebar, select this repo as the project root directory.
109+
110+
## 1.4. Adding Data
111+
112+
There are two main steps needed to add data to the database: defining a schema, and loading the data.
113+
114+
### 1.4.1. Defining a Schema
115+
116+
The first thing to do when defining a schema, is to look at the data we want to store. For example, we can start with some arbitrary facts about people.
117+
118+
```
119+
John is a male.
120+
John likes fried chicken.
121+
John likes Jo.
122+
123+
Jo is a female.
124+
Jo likes fried chicken.
125+
Jo likes John.
126+
```
127+
128+
To define the schema, we need to organise instances of the data into entities, attributes and relationships, e.g.
129+
130+
- Entities:
131+
- Person, e.g. John, Jo
132+
- Food, e.g. Fried Chicken
133+
- Attributes:
134+
- Gender, e.g. male, female
135+
- Relationships
136+
- liking, e.g. John (liker) likes fried chicken (likee)
137+
138+
139+
The schema can then be defined:
140+
141+
```
142+
define
143+
person sub entity,
144+
owns name,
145+
owns gender;
146+
147+
...
148+
149+
name sub attribute,
150+
value string;
151+
```
152+
153+
You can find the full schema definition queries in `schema.tql`.
154+
155+
### 1.4.2. Inserting Data
156+
With the schema defined, we can start inserting data. We can start by inserting entites, which starts with the `insert` keyword, followed by a variable declaration that is to be inserted, `$foo` and the corresponding attributes for that entity. E.g.,
157+
158+
```
159+
insert $p isa person, has name "Jeremy" , has gender "male";
160+
```
161+
162+
You can find a full list of these queries in `insert_data.tql`
163+
164+
### 1.4.3. Loading Schema and Data
165+
Now that we have the schema definition and insert queries, we can load them into TypeDB.
166+
167+
To load the schema, we need to open a write transaction. This can be done via the terminal, but we will use TypeDB studio for this.
168+
169+
1. Press 'schema' and 'write' on the top toolbar
170+
2. Open `schema.tql`
171+
3. Press run, then commit.
172+
173+
You should see the schema defined in the Types sidebar on the left. With the schema loaded, we can now load the data.
174+
175+
1. Press 'data' and 'write' on the top toolbar.
176+
2. Open `insert_data.tql`
177+
3. Press run, then commit.
178+
179+
### 1.4.4. Reading Data
180+
181+
Set the transaction mode to 'data' and 'read' on the top toolbar, then open `read_data.tql`
182+
183+
Uncomment the relevant sections and press run to show the following information:
184+
185+
* Show all entities, attributes and relationships
186+
* Show people who like fried chicken
187+
* Show people who like other people
188+
189+
190+
191+

‎queries/delete_data.tql

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
match $x isa thing;
2+
delete $x isa thing;

‎queries/insert_data.tql

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
insert $p isa person, has name "John" , has gender "male";
2+
insert $p isa person, has name "Jo" , has gender "female";
3+
insert $p isa person, has name "Jill" , has gender "female";
4+
5+
insert $f isa food, has name "Fried Chicken";
6+
7+
# Insert relationships
8+
match $liker isa person, has name "John";
9+
$likee isa food, has name "Fried Chicken";
10+
insert $liking(liker: $liker, likee: $likee) isa liking;
11+
12+
match $liker isa person, has name "Jo";
13+
$likee isa food, has name "Fried Chicken";
14+
insert $liking(liker: $liker, likee: $likee) isa liking;
15+
16+
match $liker isa person, has name "John";
17+
$likee isa person, has name "Jo";
18+
insert $liking(liker: $liker, likee: $likee) isa liking;
19+
20+
match $liker isa person, has name "Jo";
21+
$likee isa person, has name "John";
22+
insert $liking(liker: $liker, likee: $likee) isa liking;
23+

‎queries/read_data.tql

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Show all things
2+
#match $x isa thing;
3+
4+
# Show people who like fried chicken
5+
#match
6+
# $food isa food, has name "Fried Chicken"; # show food var which is fried chicken
7+
# $liking (liker: $liker, likee: $food) isa liking; # show relations where fried chicken is likee
8+
# $x isa name; # show names
9+
10+
# Show people who like people
11+
#match
12+
# $x isa person, has $name1, has $gender1; # get person 1
13+
# $y isa person, has $name2, has $gender2; # get person 2
14+
# $liking (liker: $x, likee: $y) isa liking; # match relations if person 1 likes person 2
15+
16+
17+

‎queries/schema.tql

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
define
2+
person sub entity,
3+
owns name,
4+
owns gender,
5+
plays liking:liker,
6+
plays liking:likee;
7+
8+
food sub entity,
9+
owns name,
10+
plays liking:likee;
11+
12+
liking sub relation,
13+
relates liker,
14+
relates likee;
15+
16+
name sub attribute,
17+
value string;
18+
19+
gender sub attribute,
20+
value string;
21+
22+

0 commit comments

Comments
 (0)