TypeDB Fundamentals Lecture Series: from Nov 16 to Jan 9

Quickstart

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

Run TypeDB

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

  • Cloud

  • Enterprise

  • Core

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

To deploy and run your on-premise cluster of TypeDB Enterprise, see the Enterprise 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

  • Enterprise

  • Core

TypeDB Studio connect window
  1. Switch the Server field drop-down to TypeDB Enterprise.

  2. Click Manage Enterprise Addresses button and add all servers (address and port) from your TypeDB Cloud deployment. Close the Address management window.

  3. Fill in the Username (default: admin) and Password (default: password) fields.

  4. Turn on the Enable TLS option and leave the CA Certificate field empty.

  5. Click Connect.

Don’t forget to change the default username and password. You can use TypeDB Console to do that.

TypeDB Studio connect window
  1. Switch the Server field drop-down to TypeDB Enterprise.

  2. Click Manage Enterprise Addresses button and add all servers (address and port) from your TypeDB Cloud deployment. Close the Address management window.

  3. Fill in the Username (default: admin) and Password (default: password) fields.

  4. Turn on the Enable TLS option and select the CA certificate for your on-premise cluster.

  5. Click Connect.

Don’t forget to change the default username and password. You can use TypeDB Console to do that.

TypeDB Studio connect window

Enter TypeDB Core server address (e.g., localhost:1729) and 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

typedb console

Connect to TypeDB

By default, TypeDB Console connects to the localhost:1729 address. Upon connection, it shows 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. Browse the Fundamentals section for essential information of how TypeDB works: Type system, Queries, Patterns, and Inference;

  3. Discover how to connect to TypeDB, manage transactions, and define a schema of a database;

  4. Find out more about writing and reading data from a TypeDB database and how to interpret a response to a query;

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

Provide Feedback