Create data

Review

In the previous sections we’ve:

  1. Setup TypeDB and Studio (or Console)

  2. Created a schema

    1. Created a database called get_started.

    2. Defined the social network schema:

      Details 
      #!test[schema]
define
attribute username,
 value string;
attribute start-date,
 value datetime;
attribute status,
 value string;
attribute student-count,
 value integer;
entity user,
  owns status @card(0..),
  owns username @key,
  plays enrolment:student,
  plays friendship:friend;
entity organization,
  owns status,
  owns username,
  plays friendship:friend;
entity company,
  sub organization;
entity university,
  sub organization,
  owns student-count,
  plays enrolment:university;
relation friendship,
  relates friend @card(2..2),
  owns start-date @card(0..1);
relation enrolment,
  relates student,
  relates university;

Overview

We are now ready to write data to our database. We’ll see a few examples of how we can create data, and how TypeDB’s type system enforces our data constraints when adding and modifying data.

Pure insert queries

The most basic writes in TypeDB are pure insertions: they insert a complete bundle of data at once.

Entities and attributes

Let’s create some entities and attributes with pure insertions.

  • Studio

  • Console

To begin, set your transaction type to write using the top bar, then let us try and insert a user with the following insert query:

insert $u isa user;

The commit will fail - an example of TypeDB enforcing data constraints! (If you’re manually controlling your transaction, you’ll see the error when you click 'commit'.)

We are trying to insert a user without a username here, but we declared usernames to be a key attribute earlier when we defined user owns username @key.

The following passes TypeDB’s validation and commits just fine:

insert $u0 isa user, has username "alice";

We can also insert multiple values in a single insert query like so:

insert
$u1 isa user, has username "bob";
$u2 isa user;
$u2 has username "charlene";  # can split `isa` and `has` across different statements

This query inserts two users at the same time and also commits safely.

Finally, since we set usernames to be a @key attribute of our users, we would - rightfully - expect the following query to fail:

insert
$u0 isa user, has username "ziggy";
$u1 isa user, has username "ziggy";

This will immediately cause the transaction to fail, as the server detects an invalid database state.

To begin, let us try insert a user with the following insert query:

#!test[write, fail_at=commit]
insert $u isa user;

Submitting commit will fail - an example of TypeDB enforcing data constraints!

We are trying to insert a user without a username here, but we declared usernames to be a key attribute earlier when we defined user owns username @key.

The following passes TypeDB’s validation and `commit`s just fine:

#!test[write]
insert $u0 isa user, has username "alice";

This query inserts two users at the same time:

#!test[write]
insert
$u1 isa user, has username "bob";
$u2 isa user;
$u2 has username "charlene";  # can split `isa` and `has` across different statements

This query inserts two users at the same time. Time to commit your queries again to safely persist your changes: type commit and press kbd:[Enter].

Finally, since we set usernames to be a @key attribute of our users, we would - rightfully - expect the following query to fail:

#!test[write, fail_at=runtime]
insert
$u0 isa user, has username "ziggy";
$u1 isa user, has username "ziggy";

This will immediately cause the transaction to fail, as the server detects an invalid database state.

So far we’ve illustrated how we can insert simple entities with attributes, and how TypeDB keeps us accountable to follow the definitions in the database schema.

So far so good!

Complete relations

Now we’ve seen how to create entities and attributes - what about inserting relations? Well, relations that are created at the same time as the connected role players are as easy as entities and attributes!

  • Studio

  • Console

In order to insert a friendship, we need to refer to users that will play the role of friends in the friendship. That’s where variables come into play!

Recall that each friendship takes exactly two friends as specified in the schema; feel free to experiment though, and see what error messages TypeDB will give you when trying to insert triple friendships.

insert
$u3 isa user, has username "delta";
$u4 isa user, has username "echo";
$u5 isa user, has username "fizzbuzz";
friendship (friend: $u3, friend: $u4);
friendship (friend: $u3, friend: $u5);

This query inserts three new users with some friendships between them.

The relations are using shorthand, and could themselves be written as $f isa friendship (friend: $x, friend: $y); if you’d want to further refer to them with the variable $f; but otherwise it’s convenient to simply omit it.

Make sure your data is committed so we can use the friendships later!

In order to insert a friendship, we need to refer to users that will play the role of friends in the friendship. That’s where variables come into play!

Recall that each friendship takes exactly two friends as specified in the schema; feel free to experiment though, and see what error messages TypeDB will give you when trying to insert triple friendships.

Using a new write transaction, run:

#!test[write]
insert
$u3 isa user, has username "delta";
$u4 isa user, has username "echo";
$u5 isa user, has username "fizzbuzz";
friendship (friend: $u3, friend: $u4);
friendship (friend: $u3, friend: $u5);

This query inserts three new users with some friendships between them.

The relations are using shorthand, and could themselves be written as $f isa friendship (friend: $x, friend: $y); if you’d want to further refer to them with the variable $f; but otherwise it’s convenient to simply omit it.

Type commit to persist your changes so we can use these friendships later!

This is great, but we won’t always be creating new users and friendships from scratch. We’ll probably want to create friendships between existing users too!

That requires us to read existing data, and then execute write operations.

Read-Write queries

Reading data in TypeDB happens with a match clause. We’ll then use the insert clause to connect the found data.

Reading data

Looking up data is easy - it looks a lot like inserting data.

Let’s find some users and their information.

  • Studio

  • Console

Change the transaction type to read in the top toolbar, and execute the following query:

match $u isa user, has username $n;

This query returns the substitutions (answers) for each variable that exist in the database and conforms to the requested constraints: any user instance that has a username!

We get back the following sets of values:

--------
$n | isa username "alice"
$x | isa user, iid 0x1e00000000000000000003
--------
$n | isa username "bob"
$x | isa user, iid 0x1e00000000000000000004
--------
$n | isa username "charlene"
$x | isa user, iid 0x1e00000000000000000005
--------
$n | isa username "delta"
$x | isa user, iid 0x1e00000000000000000006
--------
$n | isa username "echo"
$x | isa user, iid 0x1e00000000000000000007
--------
$n | isa username "fizzbuzz"
$x | isa user, iid 0x1e00000000000000000008
--------

IIDs are "instance IDs". These are auto-generated unique IDs for each entity and relation. Though fixed in each database, they are not necessarily deterministic across databases - your IIDs might be different!

We can make this more specific and interesting, for instance looking up the friends that exist of a particular user:

match
$user isa user, has username "echo";
$other-friend isa user, has username $other-username;
friendship ($user, $other-friend);

Which returns:

---------------------
$other-friend   | isa user, iid 0x1e00000000000000000006
$other-username | isa username "delta"
$user           | isa user, iid 0x1e00000000000000000007
---------------------

Open a read transaction using transaction read get-started, and execute the following query:

#!test[read, count=6]
match $u isa user, has username $n;

This query returns the substitutions (answers) for each variable that exist in the database and conforms to the requested constraints: any user instance that has a username!

We get back the following answers:

--------
$n | isa username "alice"
$x | isa user, iid 0x1e00000000000000000003
--------
$n | isa username "bob"
$x | isa user, iid 0x1e00000000000000000004
--------
$n | isa username "charlene"
$x | isa user, iid 0x1e00000000000000000005
--------
$n | isa username "delta"
$x | isa user, iid 0x1e00000000000000000006
--------
$n | isa username "echo"
$x | isa user, iid 0x1e00000000000000000007
--------
$n | isa username "fizzbuzz"
$x | isa user, iid 0x1e00000000000000000008
--------

IIDs are "instance IDs". These are auto-generated unique IDs for each entity and relation. Though fixed in each database, they are not necessarily deterministic across databases - your IIDs might be different!

We can make this more specific and interesting, for instance looking up the friends that exist of a particular user:

#!test[read, count=1]
match
$user isa user, has username "echo";
$other-friend isa user, has username $other-username;
friendship ($user, $other-friend);

Which returns:

---------------------
$other-friend   | isa user, iid 0x1e00000000000000000006
$other-username | isa username "delta"
$user           | isa user, iid 0x1e00000000000000000007
---------------------

We can close the transaction since we won’t be using it anymore. Closing transactions is good practice since they consume resources on the server.

As you can see, reading data using match clauses is easy: simply describe what the data should conform to, and TypeDB will find all answers to your query from the database.

The order of statements in a match clause doesn’t matter! This is one property that makes TypeQL extremely composable and debuggable: if your query isn’t doing what you expect, just remove parts until it’s simple enough to verify - then build it back up bit by bit!

Connecting existing data

Now that we know how to look data up - how do we use that to perform a query that creates a relation between existing data?

The key is that we can chain an insert clause after a match clause. The insert clause will receive the same set of variables and answers you would see printed out if you executed just the match clause!

Using this principle, let’s:

  1. retrieve some users with a match clause.

  2. write a new friendship relation between those users with an insert clause.

Remember, you’ll need a write transaction now since we’re modifying data!

  • Studio

  • Console

match
$x isa user, has username "alice";
$y isa user, has username "bob";
insert
friendship (friend: $x, friend: $y), has start-date 2015-01-01T00:00:00;

Chained query clauses always execute in-order, so the direction you read in is how operations will be performed: First we find two specific users by username, then insert a new friendship between them referring to those users using variables.

Feel free to insert more data, e.g., create a university and enrol some of your users in it using our enrolment relations!

Let’s commit to save our new data!

#!test[write, count=1]
match
$x isa user, has username "alice";
$y isa user, has username "bob";
insert
friendship (friend: $x, friend: $y), has start-date 2015-01-01T00:00:00;

Chained query clauses always execute in-order, so the direction you read in is how operations will be performed: First we find two specific users by username, then insert a new friendship between them referring to those users using variables.

Feel free to insert more data, e.g., create a university and enrol some of your users in it using our enrolment relations!

Let’s commit to save our new data!

Pure inserts are generally used to create new entities and attributes - all other operations require a match clause to find existing data to work with. This applies to clauses like delete and update as well.

You can read more about other clause types in the applicable Concepts page.

Here’s the full set of queries you’ve used to successfully write data into TypeDB:

insert $u0 isa user, has username "alice";

insert
$u1 isa user, has username "bob";
$u2 isa user;
$u2 has username "charlene";  # can split `isa` and `has` across different statements

insert
$u3 isa user, has username "delta";
$u4 isa user, has username "echo";
$u5 isa user, has username "fizzbuzz";
friendship (friend: $u3, friend: $u4);
friendship (friend: $u3, friend: $u5);

match
$x isa user, has username "alice";
$y isa user, has username "bob";
insert
friendship (friend: $x, friend: $y), has start-date 2015-01-01T00:00:00;

Fantastic - we’ve covered the basics of TypeQL! You’ve seen how to manage databases and transactions, define schemas, and read and write data into TypeDB!

The next section will illustrate the power of TypeQL’s clause chaining and show you how to modularize queries using functions.