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 |
---|---|---|---|---|
1 |
|
Yes |
||
1 |
|
Yes |
||
1-2 |
|
Yes |
||
|
No |
|||
1-2 |
|
No |
||
|
Yes |
|||
2 |
|
Yes |
||
|
Yes |
|||
3 |
|
Yes |
||
|
Yes |
|||
|
Yes |
Define query
A Define query is used to define types and rules in the 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.
Get query
A Get query is used to retrieve data from the TypeDB database. But it can also be used to retrieve types from the TypeDB database schema.
A Get query consists of a match
clause and an optional get
clause.
A Get query returns a stream of results (with any number of results: from zero to many).
Get queries were previously known as Match queries. The old naming can be seen in some Driver API methods for backward compatibility. |
For examples of how to perform a Get query, see the Reading data page.
Match clause
A match
clause is one of the most important. It’s used to find data and types in the TypeDB database for later use
in the consequent clause of the same query.
By default, if no other clause is provided after the match
clause it will retrieve all matched concepts (data and/or
types) as per the Get query behavior.
A match
clause is widely used in different types of queries:
-
Insert query (the
match
clause is optional)
A match
clause has the following syntax:
match <pattern>
See the match clause example
match $p isa person, has full-name $f;
A pattern used in the match
clause can address both types and data instances.
See the Patterns page for more information.
Get clause
A get
clause serves as a filter for matched concepts from a match
clause to be retrieved in a Get query.
A get
clause is optional in a Get query.
A get
clause has the following syntax:
[get <variable> [(, <variable>)...];]
[modifiers]
See the get clause example
get $p, $f;
The variable or variables mentioned in a get
clause must be bound (set) in the match
clause of the same query.
A Get query with a get
clause returns its results filtered — only variables mentioned in the get
clause are
returned. Every result has a concept or a value for any variable mentioned in the get
clause.
A Get query without the |
Modifiers
Optionally, a get
clause can have modifiers added after the list of variables.
Those modifiers can drastically change the output of the Get query:
-
sort — sorting the results by a variable;
-
group — grouping results by a variable;
-
aggregation — process the results to produce a value for an answer.
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 |
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
See the Match clause section above.
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>
See the insert clause example
insert $p has email "[email protected]";
The above example requires a preceding match
clause to bind the $p
variable. For example, to match some
person
type instances first, to insert the email ownership only for them.
Alternatively, we can use insert query without a match
clause, like that:
insert $p isa person, has email "[email protected]";
This version 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
instance.
A pattern used in an insert
clause can use the variables from the preceding match
clause.
See the Patterns 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 |
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 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 |
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.