Edit on Github

TypeQL Query Language

TypeQL is the query language for the TypeDB knowledge graph. Whether it’s through the TypeDB Console or one of the TypeDB Clients, TypeDB accepts instructions and provides answers only in its own language - TypeQL.

TypeQL is declarative. When writing TypeQL queries, we simply describe what information we would like to retrieve, rather than how should it be obtained. Once we specify the target information to retrieve, the TypeQL query processor will take care of finding an optimal way to retrieve it.

TypeQL is intuitive. TypeQL was designed to provide a high-level query language interface with clear and human-readable syntax. By defining high-level application-specific schema, we effectively define our own vocabulary to talk about the domain of interest. By introduction of an explicit data model tightly reflected in the structure of the query language, formulating queries comes naturally as it is reminiscent of building ordinary sentences about our domain. The more tightly the schema represents our domain of interest, the more intuitive writing and reading TypeQL queries become.

TypeQL serves as both the Data Manipulation Language (DML) as well as the Data Definition Language (DDL) TypeQL is a language that provides you with a complete set of tools to perform all data-oriented tasks. This includes defining the schema, retrieving information as well as creating and manipulating data.

The structure of a TypeQL query

The image below illustrates the structure of various TypeQL queries.

Query structure

As shown in the image above, TypeQL queries are categorized into two main types:

  • Data Definition:
    • Define: adds definition of a concept type to the schema.
    • Undefine: removes definition of a concept type from the schema.
  • Data Manipulation:
    • Get: returns the data instances or concept types that match the preceding pattern(s), optionally limited by, sorted by or offset by the given modifiers.
    • Delete: removes the data instances assigned to the given variable that match the preceding pattern(s), optionally limited by, sorted by or offset by the given modifiers.
    • Insert: inserts a data instance according to the given statement(s), optionally, preceded by a match clause.
    • Group: always as a part of a get query, returns the results grouped by the given variable, optionally mapped to the count of each group.
    • Aggregate Values: always as a part of a get query, returns the statistical value of numeric attributes based on the given aggregate function.

The TypeQL repository contains the full grammar for TypeQL.

TypeQL Answers

Some TypeQL queries such as match and aggregate are expected to return an answer. Depending on the type of query, the structure of the answer may be different (more on Answer types in the Client API section). As a part of the Concept API, we can call various methods on the concepts contained in an answer to retrieve more explicit and implicit knowledge about them and their surroundings.