Officially out now: The TypeDB 3.0 Roadmap >>

TypeQL language guide

The TypeQL 3.0 language guide is currently under construction. More material will be published soon. Join our Discord chat server to stay updated.

This page gives an overview of the TypeQL query language. For an overview of the data model on which TypeQL queries are built see here.

Queries and functions

The main way of interacting with your TypeDB database is through queries written in TypeQL, the query language of TypeDB. Queries fall into two categories.

  1. Schema queries comprise a single stage, indicated by the corresponding keywords shown in the table below. Schema queries modify the schema of your database, and produce no outputs except for a confirmation of success.

  2. Data pipelines may comprise multiple stages, indicated by the keywords shown in the table below. Data pipelines read and write data from the database, and always output of the read or written data (though the set of outputs may be empty).

Table 1 also mentions functions: functions are data pipeline templates that take typed input arguments. This allows users to build powerful query abstractions. Functions cannot write or delete data, and thus they cannot contain write stages like insert or delete.

Table 1. Query types and keywords
Query type Stage keywords Multi-stage?

Schema queries

define

undefine

redefine

no

Data pipelines

match

insert

delete

select

sort

reduce

…​

yes

Functions

match

select

sort

reduce

…​

yes
Schema queries

Reference for Define, Undefine, and Redefine queries for schema manipulation.

Data pipelines

Reference for building data pipelines, including all read and write pipeline stages.

Functions

Reference for writing all types of functions.

Statements and patterns

The body of a stage comprises statements. For example:

  • The body of a define stage comprises statements such as user owns username.

  • The body of a match stage comprises statements such as $u has username $n or $type owns username.

Which statements can be used depends on the stage we are in.

A key distinction between stages and their statements is whether statements contain variables or not.

  • Statements without variables are called definitions.

  • Statements with variables are called (elementary) patterns.

Patterns can be combined into larger patterns by pattern operations, such as conjunction (“chaining”), disjunction (“branching”), negation (“exclusion”), etc.

Definition vs pattern statements

Definitions and patterns play distinct roles in TypeQL.

  1. Schema queries always work with (lists of) definitions.

  2. Data pipelines (and functions) always work with patterns.

As a simple example of this distinction, compare:

define
  entity user, plays friendship:friend;
  relation friendship, relates friend @card(2);

with

match
  $some-type plays $some-role;
  friendship relates $some-role;

The former query introduces types, while the latter will query for types. The general idea here is as follows.

Definition statements

Definitions in schema queries concern:

  • type definitions, introducing new types via the appropriate keyword (entity, relation + relates, attribute + value). Types are referred to by a unique type labels; multiple aliases of the latter can be introduced (coming soon).

  • trait definitions, introducing player or owner traits (via plays and owns keywords). Player traits allow type instances to be referred to as players in roles of relations. Owner traits allow type instances to be referred to as

  • subtyping definitions, declare types to be subtypes of other types (via the keyword sub). Traits of supertypes are inherited by subtypes.

Pattern statements

In contrast, in patterns we support a wide variety of syntax, including for:

  • Retrieving types based on label, traits, and inheritance.

  • Retrieving data in types, e.g. based on references between data instance such as attribute ownerships and relation linkages (via keywords such as has, links, and anonymous versions thereof)

  • Function calls (let $a, $b in <FUN-CALL>)

  • Computation with values (let $x = <EXPR>)

  • …​ and many more.

Annotations

The semantics of many statements can be further modified with the use of annotations (which applies both to definition statements and pattern statements).

References

Patterns

Reference for query pattern construction using logical operations and optionals.

Statements

Reference for all individual TypeQL statements, covering schema and data.

Annotations

Annotations modify the semantics of specific TypeQL statements.

Expressions and value types

TypeQL supports various build in operators to manipulate and combine data types, which can be used in the construction of statements (such as assignments and comparisons).

Expressions

Reference for supported operators and expressions.

Value types

Reference for different value type.

Index and glossary

For a complete list of TypeQL keywords used at various levels of query construction, consult the keyword glossary.