Quickstart

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

TypeDB & TypeQL are in the process of being ported over and rewritten in Rust. There will be changes that won’t be backwards compatible, as we refine the language further to extend its expressivity, as well as changes to the byte storage data structure to further boost performance significantly. We’re aiming to complete this by February/March 2024, released as TypeDB 3.0, 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.

TypeDB Core needs to be installed first.

To start a local TypeDB Core server:

typedb server

To run TypeDB Core in a new Docker container:

docker run --name typedb -d -v typedb-data:/opt/ -p 1729:1729 --platform linux/amd64 vaticle/typedb:latest

Connect with TypeDB Studio

TypeDB Studio is a standalone TypeDB Client with GUI that needs to be installed and launched separately from a TypeDB server.

Find the TypeDB Studio binary and run it. Click Connect to TypeDB on the right side of the top toolbar.

  • 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. Close the Address management window.

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

  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.

On your first login you will be asked to change the password for the admin account. A TypeDB Cloud deployment will refuse queries until the password is changed from its default value.

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.

Select a project folder

Select a project directory to store project files by clicking either:

  • Open Project in the Project panel; or

  • Folder icon (project) in the top toolbar.

Create a new database

Create a database to play with:

  1. Click the database icon (database) in the top toolbar.

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

  3. Select the new database from the dropdown to the right of the database icon.

Define a schema

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

  1. Ensure the Session toggle (schema / data) is set to schema and the Transaction toggle (write / read) is set to write.

  2. Open a new tab and copy-paste the following Define query:

    define
    
    id sub attribute, value long;
    email sub attribute, value string;
    full-name sub attribute, value string;
    
    user sub entity,
        owns id @key,
        owns email,
        abstract;
    
    person sub user, owns full-name;
  3. Click Run Query (run).

  4. When the query has completed, click Commit Transaction (commit).

Now that the schema has been defined, data can be inserted into the database.

Load data

Now let’s insert some sample data into the newly created database to be able to query in future steps:

  1. Ensure the Session toggle is set to data and the Transaction toggle is set to write.

  2. Open a new tab and copy-paste the following Insert queries:

    insert $p isa person, has id 1, has full-name "Masako Holley", has email "masako.holley@vaticle.com";
    insert $p isa person, has id 2, has full-name "Pearle Goodman", has email "pearle.goodman@vaticle.com";
    insert $p isa person, has id 3, has full-name "Kevin Morrison", has email "kevin.morrison@vaticle.com";
  3. Execute all queries in the file by clicking Run Query (run).

  4. When the queries have completed, click Commit Transaction (commit).

Assuming there were no errors in the process, the data is persisted in the database.

Finish

Congratulations on completing the TypeDB quickstart guide! Now you can try sending your first queries to the database. We have prepared some simple query examples for you to try.

To learn about TypeDB’s advanced and unique features such as polymorphic queries, type inference, type inheritance, rule-based reasoning, and n-ary relations, we recommend you check the Learn more section.

Query examples

Try sending the following queries:

For more TypeQL query examples, check the TypeDB in 25 queries page or the TypeQL documentation section.

List names and emails

To retrieve full names and emails of all instances of the person type you can do:

match
$p isa person;
fetch $p: full-name, email;

For every person in a database, the above Fetch query returns a JSON object similar to the following example:

Result example
{
    "p": {
        "email": [ { "value": "kevin.morrison@vaticle.com", "value_type": "string", "type": { "label": "email", "root": "attribute" } } ],
        "full-name": [ { "value": "Kevin Morrison", "value_type": "string", "type": { "label": "full-name", "root": "attribute" } } ],
        "type": { "label": "person", "root": "entity" }
    }
}

Get all instances of a type and their attributes

To get all instances of a person type with all attributes owned:

match
$p isa person, has $a;
get $p, $a;

The above Get query returns concepts from a database as a ConceptMap that can be used programmatically with a Driver API to process the result. The following image is a graph visualization produced by TypeDB Studio.

Quickstart Get query example

Fetch all emails of Kevin

To fetch all emails owned by every person with a full name that contains substring Kevin:

match
$p isa person, has full-name $fn;
$fn contains "Kevin";
fetch $p as person: email as "E-mail address";

The above query returns a single JSON object (we have only one such person in the example database) that looks as the following:

Result example
{
    "person": {
        "E-mail address": [ { "value": "kevin.morrison@vaticle.com", "value_type": "string", "type": { "label": "email", "root": "attribute" } } ],
        "type": { "label": "person", "root": "entity" }
    }
}

Insert a new email for Kevin

To insert a new email (kevin@gmail.com) for every person with a full name that contains "Kevin":

match
$p isa person, has full-name $fn;
$fn contains "Kevin";
insert $p has email "kevin@gmail.com";

Now Kevin has more than one email.

Update the email for Kevin

To update the email from kevin@gmail.com to kevin2@gmail.com for every person with a full name that contains "Kevin":

match
$p isa person,
    has full-name $fn,
    has email $e;
$fn contains "Kevin";
$e = "kevin@gmail.com";
delete
$p has $e;
insert
$p has email "kevin2@gmail.com";

The query above does the following:

  • Matches the person and its email (kevin@gmail.com).

  • Deletes the ownership by the person of the email.

  • Inserts a new email (kevin2@gmail.com) owned by the person.

Delete ownership over the email for Kevin

To delete the ownership of the email kevin2@gmail.com for every person with a full name that contains "Kevin":

match
$p isa person,
    has full-name $fn,
    has email $e;
$fn contains "Kevin";
$e = "kevin2@gmail.com";
delete
$p has $e;

Repeat with TypeDB Console

TypeDB Console is usually distributed with TypeDB. You can find it with the TypeDB or install it separately.

Run TypeDB Console

  • Cloud

  • Core

TypeDB Cloud connection
typedb console --cloud=<server-address> --username=<username> --password --tls-enabled=true

You will be prompted for a password.

On your first login, change the password for the admin account. A TypeDB Cloud deployment will refuse queries until the password is changed from its default value.

TypeDB Core connection
typedb console

By default, TypeDB Console connects to your local TypeDB Core installation with the localhost:1729 address. Use the --core argument to specify a different address if needed.

Upon connection, TypeDB Console shows a welcome message and a prompt for a CLI input.

Create a new database

database create typedb-2

Define a schema

  1. Open a transaction:

    transaction typedb-2 schema write
  2. Run query:

    define
    
    id sub attribute, value long;
    email sub attribute, value string;
    full-name sub attribute, value string;
    
    user sub entity,
        owns id @key,
        owns email,
        abstract;
    
    person sub user, owns full-name;

    Press Enter twice to send the query.

  3. Commit:

    commit

Load data

  1. Open a transaction:

    transaction typedb-2 data write
  2. Run queries:

    insert $p isa person, has id 1, has full-name "Masako Holley", has email "masako.holley@vaticle.com";
    insert $p isa person, has id 2, has full-name "Pearle Goodman", has email "pearle.goodman@vaticle.com";
    insert $p isa person, has id 3, has full-name "Kevin Morrison", has email "kevin.morrison@vaticle.com";

    Press Enter twice to send the query.

  3. Commit:

    commit

Try queries

Repeat the Query examples from TypeDB Studio in TypeDB Console.

Learn more

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

  1. Explore more interesting queries with the TypeDB in 25 queries page.

  2. Learn more about TypeQL schemas, patterns, and queries in our TypeDB Learning course.

  3. Go straight to practice with our TypeDB manual:

  4. Learn how to create an application with TypeDB, using any of the TypeDB Drivers:

Provide Feedback