# TypeQL language guide

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](data-model/index.md).

## [](#queries)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](#table1) 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](#table1) 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](#table1) 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**

schema stages

(`define`, `undefine`, `redefine`)

no

**Data pipelines**

read _and_ write stages

(`match`, `select`, `sort`, `reduce`,

`insert`, `delete`, …​)

yes

**Functions**

read stages

(`match`, `select`, `sort`, `reduce`, …​)

yes

[Schema queries](schema/index.md)

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

[Data pipelines](pipelines/index.md)

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

[Functions](functions/index.md)

Reference for writing all types of functions.

## [](#statements)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**](patterns/index.md), such as **conjunction** (“chaining”), **disjunction** (“branching”), **negation** (“exclusion”), etc.

### [](#_definition_vs_pattern_statements)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:

```typeql
#!test[schema]
define
  entity user, plays friendship:friend;
  relation friendship, relates friend @card(2);
```

with

```typeql
#!test[read]
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)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).
    
*   **capability** definitions, introducing player or owner capabilities (via `plays` and `owns` keywords). Player capabilities allow type instances to be referred to as players in roles of relations. Owner capabilities allow type instances to be referred to as
    
*   **subtyping** definitions, declare types to be subtypes of other types (via the keyword `sub`). Capabilities of supertypes are inherited by subtypes.
    

### [](#_pattern_statements)Pattern statements

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

*   **Retrieving types** based on label, capabilities, 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)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)References

[Patterns](patterns/index.md)

Reference for query pattern construction using logical operations and optionals.

[Statements](statements/index.md)

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

[Annotations](annotations/index.md)

Annotations modify the semantics of specific TypeQL statements.

## [](#_expressions_and_value_types)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](expressions/index.md)

Reference for supported operators and expressions.

[Value types](values/index.md)

Reference for different value type.

## [](#_index_and_glossary)Index and glossary

For a complete list of TypeQL keywords used at various levels of query construction, consult the [keyword glossary](keywords/index.md).

[Console in clustered TypeDB](../reference/typedb-cluster/console/index.md) [Data and query model](data-model/index.md)

[Edit on GitHub](https://github.com/typedb/typedb-docs/edit/3.x-development/typeql-reference/modules/ROOT/pages/index.adoc) Edit this page on GitHub.