An introduction to Graql

Graql enables users to write queries against a Grakn knowledge graph leveraging the inherent semantics of the data. Concepts can be retrieved by specifying the patterns of types and relationships that identify them. Graql is declarative and therefore it handles the optimisation of the knowledge graph queries needed to retrieve information.

You can execute Graql in the Graql Console or using Java Graql.


Queries are requests made to the knowledge graph. They may modify the schema, such as define, or the data, such as insert or be read-only, such as get.

A query is comprised of an action (such as get or delete) with arguments, and preceded by a match. Examples of queries are define, undefine, get, insert and delete.


Several queries return answers. An answer is a map from variables to concepts. In general, answers will contain all variables mentioned in the variable patterns of the query.


A variable is an identifier prefixed with a dollar $. Valid identifiers must comprise of one or more alphanumeric characters, dashes and underscores.

Variable pattern

<variable> <property>, ... ;

A variable pattern is a variable (the subject of the pattern) followed by zero or more properties (optionally separated by commas ,) and ending in a semicolon ;.


A property is part of a variable pattern. The property describes something about the subject of the variable pattern.

As well as the subject, properties sometimes take other arguments, which can include things such as variables, values and labels depending on the kind of property.

When a property takes a variable argument representing a schema concept, it is possible to substitute a label. For example,

match $x isa $A; $A label person; get;

should be written more succinctly as

match $x isa person; get;

There are several different properties. Which ones are supported and what they do depends on the context. For example, match supports most properties, whereas insert only supports a small subset.


An attribute’s value is constrained by the datatype of its type:

  • long - a 64-bit signed integer
  • double - a double-precision floating point number, including a decimal point.
  • string - enclosed in double " " or single ' ' quotes
  • boolean - true or false
  • date - a date or a date-time, in ISO 8601 format

Query types

There are seven types of queries, which are begun with the following keywords:

  • get - for getting concepts from the knowledge graph
  • aggregate - for transforming data in the knowledge graph
  • define - for defining schema concepts
  • undefine - for removing schema concepts
  • insert - for inserting data
  • delete - for deleting data
  • compute - for computing useful information about your knowledge graph

Reserved keywords

The following list Graql’s reserved keywords:

Querying and query modifiers

aggregate, asc
compute, contains
delete, desc, distinct
id, in, insert
label, limit
offset, order


boolean, double, long, string, date
true, false

Schema definition

is-abstract, isa,

Rules definition

when, then


Used with compute and aggregate:

max, mean, median, min
std, sum

Graql templates

else, elseif
if, in
noescp, not, null
true, false

Cheatsheet reference

If you are already familiar with Graql, you may find our cheatsheet reference a helpful page to bookmark or print out!

Tags: graql