Quickstart guide

Overview

In this Quickstart guide we will learn how to do the following basic TypeDB operations with TypeDB Studio:

  • Connect to a TypeDB server,

  • Create a new database,

  • Prepare a TypeQL file (.tql),

  • Define a schema of a database,

  • Load data into a database,

  • Retrieve schema types and/or data from a database.

For this guide, we will use the sample schema and dataset designed for an Identity and Access Management solution that will be described later.

We highly recommend completing this guide.

Its goal is to prepare an environment for TypeDB exploration and development. The resulting database (schema and data) will be needed for example queries throughout the documentation.

Prerequisites

This Quickstart guide takes advantage of TypeDB Studio. It is an integrated development environment (IDE) for TypeDB. It was specifically designed to connect to TypeDB servers (Core and Enterprise), and use TypeQL.

To proceed, please install both TypeDB and TypeDB Studio:

Use the same version numbers for TypeDB and TypeDB Studio to ensure compatibility.

If TypeDB Studio doesn’t have a version similar to the TypeDB release — use the Version compatibility table to determine a compatible version.

Alternatively, we can use any other TypeDB Client to achieve the same results. But we recommend trying TypeDB Studio first.

Initialize database

Start TypeDB

Run the following command in a terminal:

typedb server

After displaying the TypeDB ASCII logo and the bootup completion time, TypeDB is ready for connections.

TypeDB server bootup message

Connect to TypeDB

Launch TypeDB Studio, and connect to TypeDB:

  1. Click the Connect to TypeDB button (right side of the toolbar).

  2. Enter localhost:1729 in the Address field.

  3. Click the Connect button (the dialog will close after a successful connection).

Connection Manager: Connected

Choose a project directory

TypeDB Studio project directory is set to allow us to organize and save related queries for future reuse.

The files and folders in the current project directory are shown in the Project panel on the left side of the window.

Project Interface empty

To select a project directory:

  1. Click the Open Project button in the Project panel (upper left).

  2. Choose a directory for the project files.

  3. Click the Open button.

The Project panel will now display the contents of the selected directory and a hidden subdirectory for unsaved files.

Project Interface With Open Folder

Create a database

  1. Click the database icon to open the Manage Databases dialog (left side of the toolbar).

    Database Manager button

  2. Enter iam in the text field, and click the Create button next to it.

  3. Click the Close button in the bottom right.

    Database Manager With Phone Calls Database

  4. Select iam from the database dropdown (next to the database icon).

Prepare a TypeQL file

A TypeDB schema contains entity, relation, and attribute type definitions that make up the data model, as well as rules which may be applied to it — all of which are expressed in TypeQL, TypeDB’s query language.

To prepare the schema definition file:

  1. Click the + icon in the top left corner of the Text editor panel (directly right from the Project panel).

  2. Copy the iam-schema.tql file listing below inside the new tab.

    See the full listing of the iam-schema.tql file 
    define

access sub relation,
    relates action,
    relates object,
    plays change-request:change,
    plays permission:access;

change-request sub relation,
    relates change,
    relates requestee,
    relates requester;

membership sub relation,
    relates member,
    relates parent;

collection-membership sub membership,
    relates collection as parent;

group-membership sub membership,
    relates group as parent;

set-membership sub membership,
    relates set as parent;

ownership sub relation,
    relates owned,
    relates owner;

group-ownership sub ownership,
    owns ownership-type,
    relates group as owned;

object-ownership sub ownership,
    owns ownership-type,
    relates object as owned;

permission sub relation,
    owns review-date,
    owns validity,
    relates access,
    relates subject;

segregation-policy sub relation,
    owns name,
    relates action,
    plays segregation-violation:policy;

violation sub relation,
    abstract;

segregation-violation sub violation,
    relates object,
    relates policy,
    relates subject;

action sub entity,
    abstract,
    owns name,
    owns object-type,
    plays access:action,
    plays membership:member,
    plays segregation-policy:action;

operation sub action;

operation-set sub action,
    plays set-membership:set;

object sub entity,
    abstract,
    owns object-type,
    plays access:object,
    plays membership:member,
    plays object-ownership:object,
    plays segregation-violation:object;

resource sub object,
    abstract;

file sub resource,
    owns path,
    owns size-kb;

record sub resource,
    owns number;

resource-collection sub object,
    abstract,
    plays collection-membership:collection;

database sub resource-collection,
    owns name;

directory sub resource-collection,
    owns path,
    owns size-kb;

subject sub entity,
    abstract,
    owns credential,
    plays change-request:requestee,
    plays change-request:requester,
    plays membership:member,
    plays ownership:owner,
    plays permission:subject,
    plays segregation-violation:subject;

user sub subject,
    abstract;

person sub user,
    owns email,
    owns full-name;

user-group sub subject,
    abstract,
    plays group-membership:group,
    plays group-ownership:group;

business-unit sub user-group,
    owns name;

user-account sub user-group,
    owns email;

user-role sub user-group,
    owns name;

credential sub attribute, value string;
full-name sub attribute, value string;
id sub attribute, abstract, value string;
email sub id, value string;
name sub id, value string;
number sub id, value string;
path sub id, value string;
object-type sub attribute, value string;
ownership-type sub attribute, value string;
review-date sub attribute, value datetime;
size-kb sub attribute, value long;
validity sub attribute, value boolean;

rule add-view-permission: when {
    $modify isa action, has name "modify_file";
    $view isa action, has name "view_file";
    $ac_modify (object: $obj, action: $modify) isa access;
    $ac_view (object: $obj, action: $view) isa access;
    (subject: $subj, access: $ac_modify) isa permission;
} then {
    (subject: $subj, access: $ac_view) isa permission;
};

  3. Click the save icon on the left side of the toolbar.

  4. Enter iam-schema.tql in the Save As field.

  5. Click the Save button.

Find the iam-schema.tql file listing expandable above or download the file: iam-schema.tql.

Upload the schema

To execute the TypeQL statements in the opened file and send them as queries:

  1. Ensure the Session type (schema / data) switch (next to the database dropdown) is set to the schema.

  2. Ensure the Transaction type (write / read) switch is set to the write.

    Select transaction type

  3. Click the Run Query button (with a "play" symbol, in the middle of the toolbar) to start the transaction.

  4. Click the Commit Transaction button (with a "checkmark" symbol, left of the Run Query button) to commit the changes.

The transaction has been committed, and the iam database now has a schema.

The Types panel will now display the entity, relation, and attribute types within a type hierarchy of the IAM schema.

Type browser with IAM schema

Data can now be inserted.

First important queries

Read the schema

TypeQL can be used to query schema types.

To execute a simple schema query:

  1. Ensure the Session type (schema / data) switch is set to the schema (next to the database dropdown).

  2. Ensure the Transaction type (write / read) switch is set to the read.

  3. Click the + icon right from the Project panel next to the iam-schema.tql tab in the Text editor panel.

  4. Copy the TypeQL statement below.

  5. Click the Run Query button (with a "play" symbol)

match $t sub thing;

The above query returns all types in the schema of the current database. By default, the results in TypeDB Studio are visualized as a graph.

The thing internal type will be deprecated in one of the upcoming versions and deleted in TypeDB version 3.0.

Consider using entity, attribute, or relation built-in types instead.

To produce the same result as the above example, use the following query:

match $s sub $t; {$t type entity;} or {$t type relation;} or {$t type attribute;};
IAM schema graph

Insert data

We will insert data the same way we created the schema, by creating a .tql file in our project and executing it.

To create the file:

  1. Click the + icon right from the Project panel in the top of the Text editor panel, to create a new tab.

  2. Copy the iam-data.tql file listing below inside the new tab.

    See the full listing of the iam-data.tql file 
    # Subjects
insert $p isa person, has full-name "Masako Holley", has email "[email protected]";  # No access
insert $p isa person, has full-name "Pearle Goodman", has email "[email protected]";  # Sales manager
insert $p isa person, has full-name "Kevin Morrison", has email "[email protected]";  # Full access

# Objects
insert $f isa file, has path "iopvu.java", has size-kb 55;
insert $f isa file, has path "zlckt.ts", has size-kb 143;
insert $f isa file, has path "psukg.java", has size-kb 171;
insert $f isa file, has path "axidw.java", has size-kb 212;
insert $f isa file, has path "lzfkn.java", has size-kb 70;
insert $f isa file, has path "budget_2022-05-01.xlsx", has size-kb 758;
insert $f isa file, has path "zewhb.java";
insert $f isa file, has path "budget_2021-08-01.xlsx", has size-kb 1705;
insert $f isa file, has path "LICENSE";
insert $f isa file, has path "README.md";

# Operations
insert $o isa operation, has name "modify_file";
insert $o isa operation, has name "view_file";

# Potential access types
match $ob isa file, has path "iopvu.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "zlckt.ts"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "psukg.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "axidw.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "lzfkn.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "budget_2022-05-01.xlsx"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "zewhb.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "budget_2021-08-01.xlsx"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "LICENSE"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "README.md"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;

match $ob isa file, has path "iopvu.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "zlckt.ts"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "psukg.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "axidw.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "lzfkn.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "budget_2022-05-01.xlsx"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "zewhb.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "budget_2021-08-01.xlsx"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "LICENSE"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "README.md"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;

# Permissions
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "iopvu.java";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "zlckt.ts";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "psukg.java";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "axidw.java";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "lzfkn.java";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "budget_2022-05-01.xlsx";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "zewhb.java";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "budget_2021-08-01.xlsx";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "LICENSE";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "README.md";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "budget_2022-05-01.xlsx";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "zewhb.java";
      $a isa action, has name "view_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "budget_2021-08-01.xlsx";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "LICENSE";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "README.md";
      $a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;

  3. Click the save icon (left side of the toolbar).

  4. Enter iam-data.tql in the Save As field.

  5. Click the Save button.

Find the iam-data.tql file listing expandable above or download the file: iam-data.tql.

To insert this data to a TypeDB database we need to define the correct schema first.

To execute the TypeQL statements copied from the code block above:

  1. Ensure the Session type (schema / data) switch (next to the database dropdown) is set to the data.

  2. Ensure the Transaction type (write / read) switch is set to the write.

  3. Click the Run Query button (with a "play" symbol).

  4. Click the Commit Transaction button (with a "checkmark" symbol).

The transaction has been committed, and the data can now be queried.

Read data

To retrieve data from a database:

  1. Click the + icon right from the Project panel next to the iam-data.tql tab in the Text editor panel.

  2. Ensure the Session type (schema / data) switch (next to the database dropdown) is set to the data.

  3. Ensure the Transaction type (write / read) switch is set to the read.

  4. Replace the TypeQL statement in the Text editor panel with the one below.

  5. Click the Run Query button (with a "play" symbol).

match $f isa file, has path $fp;

The above query returns all file entities with their path attributes. By default, TypeDB Studio displays the results as shown in the image below.

IAM data example

Summary

The Quickstart guide above provides a fast and easy way to set up the minimum IAM database environment: a TypeDB database with IAM schema and a small dataset. It can be used for examples in this documentation or for independent exploration of TypeDB features.

Here are the files used in the guide above:

  • iam-schema.tql — TypeQL script for the IAM schema definition.

  • iam-data.tql — TypeQL script to load a sample dataset into a database with the IAM schema.

We can do the same process of creating a database, and loading schema and data through any other TypeDB Client.

Here is an example with the TypeDB Console:

TypeDB Console commands
# create database
typedb console --command="database create test-iam-db"

# load schema into the new database from a file
typedb console --command="transaction test-iam-db schema write" --command="source iam-schema.tql" --command="commit"

# load data into the new database from a file
typedb console --command="transaction test-iam-db data write" --command="source iam-data.tql" --command="commit"

# check the data loaded (single quotes for bash syntax compatibility with the variables like $t)
typedb console --command="transaction test-iam-db data read" --command='match $t isa thing; get $t;'

Learn more

After completing this guide we can recommend the following order of topics to continue exploring TypeDB:

  1. Explore the Fundamentals section for essential information of how TypeDB works:

  2. Find out more about how to connect to TypeDB, and use databases, sessions, and transactions.

  3. Learn how to define a schema of a database.

  4. Discover how to write or read data from a TypeDB database.

  5. Check out how to interpret a TypeDB responses to a query.

  6. Explore all TypeDB Clients to find the most suitable one.

  7. (Optional) Learn more about the IAM sample schema that will be used in the majority of examples throughout this documentation.

  8. (Optional) Explore the Sample application written in Java, Python, or Node.js.