Officially out now: The TypeDB 3.0 Roadmap

Quickstart

This Quickstart guide shows how to set up a TypeDB database and run queries using TypeDB Studio.

TypeDB & TypeQL are in the process of being rewritten in Rust. There will be significant refinement to the language, and minor breaks in backwards compatibility. Learn more about the changes from our 3.0 Roadmap. The biggest change to TypeDB 3.0 will be our storage data structure and architecture that significantly boosts performance. We’re aiming to release 3.0 in the summer this year, along with preliminary benchmarks of TypeDB.

Run TypeDB

To start TypeDB, select the TypeDB edition below and follow the instructions.

  • Cloud

  • Core

Log in to TypeDB Cloud and create a new deployment on the Deployments page.

For self-hosted TypeDB Cloud installation and setup, see the Self-hosted deployment page.

Ensure TypeDB Core is installed.

To start a locally installed TypeDB Core server:

typedb server

To create a new Docker container with TypeDB Core server:

docker volume create typedb-data
docker create --name typedb -v typedb-data:/opt/typedb-all-linux-x86_64/server/data -p 1729:1729 --platform linux/amd64 vaticle/typedb:latest

Connect to TypeDB

In this quickstart guide, we will use TypeDB Studio, the standalone GUI-based client for TypeDB. Ensure Studio is installed, then launch the application.

  • Cloud

  • Core

TypeDB Studio connect window
  1. Click Connect to TypeDB on the right side of the top toolbar.

  2. Switch the Server field drop-down to TypeDB Cloud.

  3. Click Manage Cloud Addresses button.

  4. Add address and port for at least one server from your TypeDB Cloud deployment, then close the Address Management window.

  5. Fill in the Username and Password fields with valid user credentials.

    For newly created deployments, the default username and password are admin and password. After connecting for the first time, you will be required to change the password before queries can be run.

  6. Turn on the Enable TLS option and leave the CA Certificate field empty. For self-hosted deployments, encryption parameters may vary.

  7. Click Connect.

TypeDB Studio connect window
  1. Click Connect to TypeDB on the right side of the top toolbar.

  2. Make sure the TypeDB Core option is selected in the Server field.

  3. Enter the address and port of the server to connect to (e.g. localhost:1729).

  4. Click Connect.

Create a project

TypeDB Studio stores queries you create as TypeQL files in a local project directory. To select a project directory, click either Open Project in the Project panel, or the studio projects Open Project Directory button in the top toolbar.

Create a new database

Let’s begin by creating a database:

  1. Click the studio dbs Manage Databases button in the top toolbar.

  2. Enter a name for a new database, for example typedb-quickstart, and click Create.

  3. Select the new database from the Select Database dropdown (database none) in the top toolbar.

Define a schema

A new database needs a schema before we can load any data:

  1. Ensure the session type toggle (session schema) is set to schema and the transaction type toggle (transaction write) is set to write.

  2. Open a studio new New Tab in the Text Editor and paste in the following Define query.

    define
      person sub entity, owns name;
      user sub person,
        owns username @key,
        owns email @unique,
        plays permission:subject;
      file sub entity,
        owns path @key,
        owns size-kb,
        plays permission:object;
      action sub entity,
        owns name @key,
        plays permission:action;
      permission sub relation,
        owns updated,
        relates object,
        relates subject,
        relates action;
      id sub attribute, abstract, value string;
      email sub id, value string;
      name sub id, value string;
      path sub id, value string;
      username sub id, value string;
      size-kb sub attribute, value long;
      updated sub attribute, value datetime;
  3. Click the studio run Run Query button.

  4. When the query has completed, click studio check Commit Transaction.

With the schema defined, we can now insert data into the database.

Load data

Let’s insert sample data for our newly defined schema:

  1. Ensure the session toggle is set to data and the transaction toggle is set to write.

  2. Open a new tab and paste in the following Insert query.

    insert
      $charlie isa person, has name "Charlie";
      $bob isa user,
        has name "Bob",
        has username "bob_93",
        has email "bob@typedb.com";
      $alex isa user,
        has name "Alex",
        has username "al-capucino";
      $readme isa file, has path "README.md";
      $guide isa file,
        has path "docs/quickstart-guide.adoc",
        has size-kb 3458761;
      $full isa action, has name "full";
      $write isa action, has name "write";
      $read isa action, has name "read";
      $perm-1 (subject: $bob, object: $readme, action: $full) isa permission,
        has updated 2023-10-27T12:04:36;
      $perm-2 (subject: $bob, object: $guide, action: $read) isa permission,
        has updated 2023-10-27T12:04:36;
      $perm-3 (subject: $alex, object: $guide, action: $write) isa permission;
  3. Click the studio run Run Query button.

  4. When the query has completed, click studio check Commit Transaction.

The data should now be persisted in the database, and is ready to be queried.

Read data

Let’s send a Fetch query to retrieve all types of action permitted for a particular user on a particular file. Using a data session and read transaction, studio run run the following query.

match
  $bob isa user, has name "Bob";
  $readme isa file, has path "docs/quickstart-guide.adoc";
  (subject: $bob, object: $readme, action: $action) isa permission;
fetch
  $action: name;

This query matches permissions of users with the name "Bob" for files with the path "docs/quickstart-guide.adoc". This is represented by a permission relation in which the user plays the subject role and the file plays the object role. For any matched permissions, it fetches the name of permitted action.

Update data

To update data in a database, we match the existing data, delete it, and then insert new data to replace it. Let’s update Bob’s permissions for the quickstart guide documentation. Using a data session and write transaction, studio run run the following query, then studio check commit the transaction.

match
  $guide isa file, has path "docs/quickstart-guide.adoc";
  $bob isa user, has name "Bob";
  $read isa action, has name "read";
  $perm (object: $guide, subject: $bob, action: $read) isa permission,
    has updated $date;
  $write isa action, has name "write";
delete
  $perm (action: $read);
  $perm has $date;
insert
  $perm (action: $write);
  $perm has updated 2024-05-15T11:04:36;

This query matches permission relation by its roleplayers, removes the "read" action from playing action role, and replaces it with the "write" action. It also replaces the updated attribute to record the update to Bob’s permissions.

After committing the transaction, the updated information is persisted in the database and becomes available for querying. If we then re-run the above Fetch query, we should see the results have updated to reflect the change.

What’s next?

Continue to discover TypeDB’s powerful features with the Crash Course, or explore other sections of the documentation.

Continue this quickstart guide and learn the basics of TypeDB.

A comprehensive learning course for TypeDB comprising several individual lessons.

A collection of practice-oriented how-to guides for TypeDB.

Information on language-specific TypeDB drivers with native API.

Provide Feedback