Introduction
This guide is here to take you from no knowledge of Studio or TypeDB to a place where you can freely run queries against some pre-provided data from entirely within Studio. By following each step, you will have the full picture on how to go from zero to full data visualisation using Studio and TypeDB.
What You Need
- A TypeDB Server instance running locally on the default port (1729).
- An OS-appropriate version of Studio.
Running TypeDB Server
Downloading, installing and running a TypeDB server differs slightly platform to platform, so we’ve created a guide to get you started here: Install and Run TypeDB Server.
Connecting to TypeDB Server
Once you launch Studio, head to the top right-hand corner and click ‘Connect to TypeDB’.
Now Studio is connected to your TypeDB instance.
Creating a Database
Now Studio and TypeDB Server are connected, but you haven’t set up any databases. To do so, go to the databases icon in the top left-hand corner.
Select the database you just created by clicking the dropdown menu titled ‘Select Databases’ immediately right of the databases icon.
Creating a Project Folder
We’ve created a database, so now would be a good time to set up a project folder. Studio will store queries you save here, so you don’t need to rewrite all your queries each time you open Studio.
Writing a Schema
You may have noticed that now you have connected to TypeDB and opened a project folder, Studio has sprung to life. Now we need to write a ‘schema’ to our database. You can learn more about what a schema is and how to write one here. In short, a schema is a description of the structure of your data and how various entities relate to each other.
For now, we’ve got a pre-made schema for you to use. We’ve also got data and queries for this later, so keep following along if you want to get the full experience from this guide.
define
repo-id sub attribute,
value long;
repo-name sub attribute,
value string;
repo-description sub attribute,
value string;
commit-hash sub attribute,
value string;
commit-message sub attribute,
value string;
commit-date sub attribute,
value string;
user-name sub attribute,
value string;
file-name sub attribute,
value string;
repo-file sub relation,
relates file,
relates repo;
repo-creator sub relation,
relates repo,
relates owner;
commit-author sub relation,
relates author,
relates commit;
commit-file sub relation,
relates file,
relates commit;
commit-repo sub relation,
relates commit,
relates repo;
file-collaborator sub relation,
relates file,
relates collaborator;
repo sub entity,
plays commit-repo:repo,
plays repo-creator:repo,
plays repo-file:repo,
owns repo-id,
owns repo-name,
owns repo-description;
commit sub entity,
plays commit-author:commit,
plays commit-file:commit,
plays commit-repo:commit,
owns commit-hash,
owns commit-date;
user sub entity,
plays commit-author:author,
plays repo-creator:owner,
plays file-collaborator:collaborator,
owns user-name;
file sub entity,
plays repo-file:file,
plays commit-file:file,
plays file-collaborator:file,
owns file-name;
rule file-collaborator-rule:
when
{
(file: $f, commit: $c) isa commit-file;
(commit: $c, author: $a) isa commit-author;
}
then
{
(file: $f, collaborator: $a) isa file-collaborator;
};
If you’re familiar with GitHub, parts of this schema should make sense to you. If not, the basics are:
- A
repo
(also known as a repository) is a place where files, generally code, are stored. It has an id, a name, a description, an author and contains a number of files and commits. - A
commit
is a change to the contained files and that has a hash (a piece of text derived from those changes and a few other details) and a date as well as a relation to the repo it was made in, the files it touched and its author. - A
file
is a file. It has a name and a relation to the repo it was made in, the commits it was touched by and the users that have collaborated on it.
Now, lets write this schema to our newly created database.
You’ll notice the types view has updated to reflect our schema write once committed.
Inserting Data
Here’s some data concerning vaticle/typedb-behaviour.
insert $user isa user, has user-name "dmitrii-ubskii";
insert $user isa user, has user-name "lolski";
insert $user isa user, has user-name "vaticle";
insert $user isa user, has user-name "jmsfltchr";
insert $user isa user, has user-name "krishnangovindraj";
insert $user isa user, has user-name "haikalpribadi";
match $user isa user, has user-name "vaticle"; insert $repo isa repo, has repo-id 208812506, has repo-name "typedb-behaviour", has repo-description "TypeDB Behaviour Test Specification"; $repo-creator(repo: $repo, owner: $user) isa repo-creator;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "concept/type/relationtype.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "concept/type/entitytype.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "typeql/language/undefine.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "typeql/language/define.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "dependencies/vaticle/repositories.bzl"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "typeql/language/rule-validation.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "typeql/reasoner/relation-inference.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "typeql/reasoner/schema-queries.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "concept/type/attributetype.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "typeql/reasoner/negation.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $repo isa repo, has repo-name "typedb-behaviour"; insert $file isa file, has file-name "typeql/reasoner/variable-roles.feature"; $repo-file(repo: $repo, file: $file) isa repo-file;
match $author isa user, has user-name "krishnangovindraj"; $repo isa repo, has repo-name "typedb-behaviour"; insert $commit isa commit, has commit-hash "8c92af7cd6dd6fc84dc7238cd7ddf0748d5531b1", has commit-date "Wed Jun 08 17:13:09 BST 2022"; $commit-author(commit: $commit, author: $author) isa commit-author; $commit-repo(commit: $commit, repo: $repo) isa commit-repo;
match $file isa file, has file-name "typeql/reasoner/negation.feature"; $commit isa commit, has commit-hash "8c92af7cd6dd6fc84dc7238cd7ddf0748d5531b1";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $author isa user, has user-name "lolski"; $repo isa repo, has repo-name "typedb-behaviour"; insert $commit isa commit, has commit-hash "e3efb4813cd4baa7b80d976045fd1c81ffdf81ca", has commit-date "Fri Jun 03 16:12:45 BST 2022"; $commit-author(commit: $commit, author: $author) isa commit-author; $commit-repo(commit: $commit, repo: $repo) isa commit-repo;
match $file isa file, has file-name "dependencies/vaticle/repositories.bzl"; $commit isa commit, has commit-hash "e3efb4813cd4baa7b80d976045fd1c81ffdf81ca";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $author isa user, has user-name "jmsfltchr"; $repo isa repo, has repo-name "typedb-behaviour"; insert $commit isa commit, has commit-hash "2a712c4470ccaaaa9f8d7aa5f70b114385c0a47a", has commit-date "Wed May 25 12:03:18 BST 2022"; $commit-author(commit: $commit, author: $author) isa commit-author; $commit-repo(commit: $commit, repo: $repo) isa commit-repo;
match $file isa file, has file-name "typeql/language/rule-validation.feature"; $commit isa commit, has commit-hash "2a712c4470ccaaaa9f8d7aa5f70b114385c0a47a";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $file isa file, has file-name "typeql/reasoner/negation.feature"; $commit isa commit, has commit-hash "2a712c4470ccaaaa9f8d7aa5f70b114385c0a47a";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $file isa file, has file-name "typeql/reasoner/relation-inference.feature"; $commit isa commit, has commit-hash "2a712c4470ccaaaa9f8d7aa5f70b114385c0a47a";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $file isa file, has file-name "typeql/reasoner/schema-queries.feature"; $commit isa commit, has commit-hash "2a712c4470ccaaaa9f8d7aa5f70b114385c0a47a";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $file isa file, has file-name "typeql/reasoner/variable-roles.feature"; $commit isa commit, has commit-hash "2a712c4470ccaaaa9f8d7aa5f70b114385c0a47a";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $author isa user, has user-name "dmitrii-ubskii"; $repo isa repo, has repo-name "typedb-behaviour"; insert $commit isa commit, has commit-hash "6e462bcbef73c75405264777069a22bca696a644", has commit-date "Tue May 24 13:03:09 BST 2022"; $commit-author(commit: $commit, author: $author) isa commit-author; $commit-repo(commit: $commit, repo: $repo) isa commit-repo;
match $file isa file, has file-name "concept/type/attributetype.feature"; $commit isa commit, has commit-hash "6e462bcbef73c75405264777069a22bca696a644";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $file isa file, has file-name "concept/type/entitytype.feature"; $commit isa commit, has commit-hash "6e462bcbef73c75405264777069a22bca696a644";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $file isa file, has file-name "concept/type/relationtype.feature"; $commit isa commit, has commit-hash "6e462bcbef73c75405264777069a22bca696a644";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $author isa user, has user-name "haikalpribadi"; $repo isa repo, has repo-name "typedb-behaviour"; insert $commit isa commit, has commit-hash "184bc8a64aa69e383bf496c70b11f02201d33616", has commit-date "Fri May 13 20:24:46 BST 2022"; $commit-author(commit: $commit, author: $author) isa commit-author; $commit-repo(commit: $commit, repo: $repo) isa commit-repo;
match $file isa file, has file-name "typeql/language/define.feature"; $commit isa commit, has commit-hash "184bc8a64aa69e383bf496c70b11f02201d33616";insert $commit-file(commit: $commit, file: $file) isa commit-file;
match $file isa file, has file-name "typeql/language/undefine.feature"; $commit isa commit, has commit-hash "184bc8a64aa69e383bf496c70b11f02201d33616";insert $commit-file(commit: $commit, file: $file) isa commit-file;
Query the Data
Everything is in place and we can start writing queries for our data. Open one final file and set your session and transaction types to data
and read
respectively.
To the right of the transaction type, we have transaction settings, such as snapshot
and infer
. Because our query makes use of the file-collaborator-rule
defined in the schema, you’ll need to enable the infer
option, which allows rules to be triggered when querying.
Get a quick visualisation of the data with the following query:
match $x isa thing;
This query gets every attribute, entity and relation.
Use the following example query to find users who have worked on
negation.feature
:
match $file isa file, has file-name "typeql/reasoner/negation.feature";
$file-collaborator(file: $file, collaborator: $c) isa file-collaborator;
$c has user-name $user-name;