Introduction
TypeQL is the query language of TypeDB. It is designed based on TypeDB’s expressive type system and inspired by natural language. It enables users to write concise and declarative queries, which can be used to:
-
Define and modify the schema of your database, using Define and Undefine queries,
-
Write and modify the data in your database, using Insert, Delete, and Update queries,
-
Read data and the schema from your database, using Fetch and Get queries.
Layers of TypeQL
TypeQL queries can be understood layer-by-layer. We give a brief overview of these layers below.
Query clauses
At the top layer, each query comprises clauses which begin with keywords such as define, insert, or fetch, or match. These keywords indicate the purpose of the subsequent clause: for example,
-
a
defineclause will comprise a set of declarative statements describing the (to-be-defined) schema of our database, -
an
insertclause will comprise a set of declarative statements describing the (to-be-inserted) data in our database. These “sets of declarative statements” are called patterns.
Query clauses can also be augmented with modifiers which allow for various query modifications to be applied, such as sorting, pagination, aggregation, or grouping.
Patterns and operations
Patterns describe the properties and interactions of types and data. They can be used for several purposes:
-
Patterns describing types (without variables) are used in
define(orundefine) clauses in order to modify the schema of our database, -
Patterns describing data are used in
insert(ordelete) clauses in order to modify the data in our database, -
General patterns are used in
matchclauses in order to find existing data and types that satisfy the statements described by the pattern.
In TypeQL, individual patterns always terminate with a semicolon (;). They can be either simple statements, usually of the form subject keyword object (but there are exceptions!), or they can constructed by a pattern operation, including
-
conjunction (simple chaining of patterns, separated by
;), -
disjunction (using the
orkeyword), -
and negation (using the
notkeyword).
Among these, conjunction is the most important operation to construct patterns: in TypeQL, the conjunction of two patterns is simply written by chaining the patterns one after the other, without the explicit usage of any keyword.
Statements and compositions
Statements are the simplest declarative patterns in TypeQL. They often look and read like actual, natural-language sentences. For examples, $someone isa person; and $someone has name "John"; are both valid statements in TypeQL.
Statement fulfil a variety of purposes, covering all the different interactions of types and data in TypeDB’s type system. For example, the statement $someone isa person; states that the concept $someone will be of type person.
Finally, to make TypeQL’s syntax yet more convenient, we are allowed to combine statements with the same subject into composite statements. For example, the statements $someone isa person; and $someone has name "John"; can be combined into the composite statement $someone isa person, has name "John";.
Variables, concepts, and values
The final layer of TypeQL’s syntax are variables, which are prefixed with $. These represent single concepts which may refer to either types or data in our database. All data lives in types, and types can be of different kinds (namely, entity, relation, or attribute types). Each of these kinds plays a special role in structuring the data in our database, and their precise function is defined in TypeDB’s data model: the polymorphic entity-relation-attribute model.
Attributes (i.e., data instances in attribute types) are the only concepts with have an underlying values associated to them: for example, an attribute in the type name may have a string value. TypeQL allows us work with such values in familiar ways: e.g., by comparing them or applying functions to them! Note that temporary values may be stored in special variables, called “value variable”, and these are prefixed with the special symbol ?.
Principles of TypeQL
As a query language, TypeQL synthesizes typeful programming with near-natural language. Its design emphasizes the following principles.
-
Naturality and expressivity: The type system of TypeDB and the language of TypeQL are designed to closely reflect how we use and think about data. As a result of this approach, TypeQL’s pattern-based syntax allows us to capture complex thoughts in concise queries.
-
Composability and flexibility: The expressivity of TypeQL derives from the ability to compose patterns via pattern operations. TypeQL builds on simple and basic ingredients which can be freely combined and composed in a flexible manner. When something looks like it should be a valid TypeQL, it most likely is a valid TypeQL pattern!
-
Safety and typedness: TypeQL syntax is fully type-checked, and this catches many subtle errors before they can happen.
The theory
TypeQL is based on the contemporary mathematical field of type theory. If you want to learn more about the mathematics underpinning TypeQL, see our papers section!
Contribution
TypeQL is an open source language project. You can learn more about (and contribute to) TypeQL by visiting our Github repo.
Good to know
TypeQL example resources
You can find a range of useful query examples in the Crash Course and (many more in) TypeDB Academy.