TypeDB Fundamentals Lecture Series: from Nov 16 to Jan 9

Queries

All queries to a TypeDB database are written in TypeQL.

TypeQL is a declarative query language. For more information, see the TypeQL section.

A top-level TypeQL construct is a query.

TypeQL query consists of clauses (one, two, or three).

A clause always starts with a keyword that defines the type of clause.

Query type № of clauses Clause(s) Keyword Mandatory

Define

1

Define

define

Yes

Undefine

1

Undefine

undefine

Yes

Insert

1-2

Match

match

No

Insert

insert

Yes

Delete

2

Match

match

Yes

Delete

delete

Yes

Update

3

Match

match

Yes

Delete

delete

Yes

Insert

insert

Yes

Fetch

2

Match

match

Yes

Fetch

fetch

Yes

Get

2

Match

match

Yes

Get

get

Yes

Define query

A Define query is used to define types and rules in a database schema.

A Define query consists of a single define clause.

For more information on the Define query, see the Define types and Define rules pages.

For examples of how to perform a Define query, see the Defining schema page.

Define clause

A define clause adds the concepts and the constraints, described by its pattern, to the schema of the current database.

A define clause is used only in the Define query.

A define clause has the following syntax:

define <pattern>

A pattern used in the define clause is limited to defining types and rules: the DDL part of the TypeQL.

Undefine query

An undefine clause removes the concepts, the constraints, and the rules described by its pattern, from the schema of the current database.

An Undefine query consists of a single undefine clause.

For more information on the Undefine query, see the Modify existing schema page.

For examples of how to perform an Undefine query, see the Defining schema page.

Undefine clause

An undefine clause is used only in the Undefine query.

An undefine clause has the following syntax:

undefine <pattern>

A pattern used in the undefine clause is limited to the DDL part of the TypeQL.

Insert query

An Insert query is used to add data to the TypeDB database.

An Insert query consists of an optional match clause and an insert clause.

The optional match clause uses a pattern to find existing data which is needed as a context to insert new data. If no context is required (no existing data to link with the inserted data) — there is no need for a match clause in this query.

The insert clause uses a pattern to specify the data to be inserted and may include references to the existing data found by the optional match clause.

For example, to insert a new relation instance, we need to match every instance that will play a role in it to be able to address them in the insert clause.

An Insert query returns a stream of inserted concepts (with any number of results: from zero to many).

The insert clause will be executed exactly once for every matched pattern found by the match clause. If the match clause is omitted the insert query will be executed exactly once.

If there are no matches for a match clause in an insert query, then there will be no inserts.

The insert clause can have a pattern with multiple statements to insert in one query. But it can’t insert types (use define to insert new types) and can’t have the following:

  • Conjunction

  • Disjunction

  • Negation

  • is keyword

For more information on the Insert query, see the Insert query page in the TypeQL documentation.

For examples of how to perform an Insert query, see the Insert query section of the Writing data page.

Match clause

A match clause is one of the most important. It’s used to find data and types that match a particular pattern in a TypeDB database. The matched data is later used in the consequent clause of the same query.

Matching data with a match clause is mandatory in all data query types, except the Insert query:

A match clause has the following syntax:

match <pattern>

For more information on patterns, see the Pattern matching essentials page.

Example
match
$p isa person, has full-name $f;

A pattern used in a match clause can address both types and data instances. See the Patterns page for more information.

Insert clause

An insert clause is used to add new data to a database.

If the inserted data is somehow connected to the data existing in the database, we need to use the match clause before the insert clause in the same Insert query.

An insert clause has the following syntax:

insert <pattern>
Insert clause example
insert $p isa person, has email "email@vaticle.com";

The above insert query doesn’t require a match clause, because it binds the only variable it has to a person type. It creates a new instance of the person type in a database, before inserting an ownership of the email for the person.

A pattern used in an insert clause can use the variables from the preceding match clause. See the Insert query page for more information.

Delete query

A Delete query is used to remove data from the TypeDB database.

A Delete query consists of a match clause and a delete clause.

A match clause uses a pattern to find existing data/references which may be removed. To delete existing data, we need to find it first.

A delete clause uses a pattern to specify precisely the data to be removed.

For example, to remove ownership of an attribute without deleting the attribute itself. Or, to remove the player of a role from a relation without deleting either the player or the relation/role.

The deletion pattern is executed exactly once for every result matched by the match clause.

If there are no matches for a match clause in a delete query, then there will be no deletes.

The delete clause can have a pattern with multiple statements to delete in one query. But it can’t delete types (use undefine to delete types) and can’t have the following:

  • Conjunction

  • Disjunction

  • Negation

  • is keyword

For more information on the Delete query, see the Delete page in the TypeQL documentation.

For examples of how to perform a Delete query, see the Delete query section of the Writing data page.

Match clause

See the Match clause section above.

Delete clause

A delete clause is used to delete data from a database.

A delete clause has the following syntax:

delete <pattern>
See the delete clause example 
delete $p has email $e;

A pattern used in a delete clause must use the variables from the preceding match clause. See the Patterns page for more information.

Update query

An Update query removes data from the TypeDB database and then inserts new data instead.

An Update query consists of a match clause, a delete clause, and an insert clause.

A match clause uses patterns to find existing data/references to be changed. To delete existing data, we need to find it first.

A delete clause is used to precisely select what to delete with a pattern. The deletion pattern is executed exactly once for every result matched by the match clause.

An insert clause is used to insert new data after the deletion of the old one. The insertion pattern is executed exactly once for every result matched by the match clause.

If there are no matches for a match clause in an update (match-delete-insert) query, then there will be no deletes and no inserts.

The delete clause can have a pattern with multiple statements to delete in one query. But it can’t delete types (use undefine to delete types) and can’t have the following:

  • Conjunction

  • Disjunction

  • Negation

  • is keyword

The insert clause can have a pattern with multiple statements to insert in one query. But it can’t insert types (use define to insert new types) and can’t have the following:

  • Conjunction

  • Disjunction

  • Negation

  • is keyword

Unlike other databases, TypeDB does not update data in place. Data is updated by replacing references to it. When we remove a player from a role in a relation, the player itself is not removed from the database, but rather the information of it playing the role.

In addition, attributes are immutable. Rather than changing the value of an owned attribute, the ownership of it is replaced with the ownership of a new/different attribute.

For more information on the Update query, see the Update query page.

See the update query example 
match
  $p isa person, has full-name $n;
  $n contains "inappropriate word";
delete
  $p has $n;
insert
  $p has full-name "deleted";

For every instance of person entity type with owned attribute of full-name type, which value contains inappropriate word string, we delete the ownership of the attribute and insert an ownership of a new one with the value of deleted to the same entity.

For more examples of how to perform an Update query, see the Update query section of the Writing data page.

Match clause

See the Match clause section above.

Delete clause

See the Delete clause section above.

Insert clause

See the Insert clause section above.

Learn more

To find out more about the queries, see the define query, undefine query, Insert query, Delete query, and Update query pages.

For more information about practical aspects of using TypeDB, see the TypeDB Documentation.

Provide Feedback