Graql Match Clause

A match describes a pattern to find in the knowledge graph. The results of the match can be modified with various modifiers. To follow along, or experiment further, with the examples given below, please load the basic-genealogy.gql file, which can be found in the examples directory of the Grakn installation zip, or on Github.

./grakn server start
./graql console -f <relative-path-to-Grakn>/examples/basic-genealogy.gql



Match instances that have the given type. In the example, find all person entities.

match $x isa person; get;


Match entities that are direct instances of the given type. In the example, find all person entities.

match $x isa! person; get;


Match concepts that have a system id that matches the predicate.

# Insert one of the system id values that were displayed from the previous query. For example:
match $x id "1216728"; get;

qb.match(var("x").has("id", "1216728")).get();


Match all attributes that have a value matching the given predicate.

match $x val contains "Bar"; get;



Match things that have the attribute specified. If a predicate is provided, the attribute must also match that predicate.

match $x has identifier $y; get;
match $x has identifier contains "Bar"; get;

qb.match(var("x").has("identifier", var("x"))).get();
qb.match(var("x").has("identifier", contains("Bar"))).get();

You can also specify a variable to represent the relationship connecting the thing and the attribute:

match $x has identifier "Bar" via $r; get;

qb.match(var("x").has(Label.of("identifier"), var().val("Bar"), var("r"))).get();


Match things that have a relationship with the given variable. If a role is provided, the role player must be playing that role.

match $x isa person; ($x, $y); get;
match $x isa person; (spouse:$x, $y); get;
match $x isa person; (spouse:$x, $y); $x has identifier $xn; $y has identifier $yn; get;

qb.match(var("x").isa("person"), var().rel("x").rel("y")).get();
qb.match(var("x").isa("person"), var().rel("spouse", "x").rel("y")).get();
  var().rel("spouse", "x").rel("x"),
  var("x").has("identifier", var("xn")),
  var("y").has("identifier", var("yn"))

Variable Patterns

Patterns can be combined into a disjunction (‘or’) and grouped together with curly braces. Patterns are separated by semicolons, and each pattern is independent of the others. The variable pattern can optionally be bound to a variable or an ID.

match $x isa person, has identifier $y; {$y val contains "Elizabeth";} or {$y val contains "Mary";}; get;

    var("x").isa("person").has("identifier", var("y")),


A predicate is a boolean function applied to values. If a concept doesn’t have a value, all predicates are considered false.


There are several standard comparators, =, !=, >, >=, < and <=. For longs and doubles, these sort by value. Strings are ordered lexicographically.

match $x has age > 70; get;

qb.match(var("x").has("age", gt(70))).get();

If a concept doesn’t have a value, all predicates are considered false. The query below matches everything where the predicate >10 is true. So, it will find all concepts with value greater than 10. However, if a concept does not have a value at all, the predicate is considered false, so it won???t appear in the results.

match $x val >10; get;


Asks if the given string is a substring.

match $x has identifier $id; $id val contains "Niesz"; get;

    var("x").has("identifier", var("id")),


Checks if the value matches a regular expression. This match is across the entire string, so if you want to match something within a string, you must surround the expression with .*.

match $x val /.*(Mary|Barbara).*/; get;



There are a number of modifiers that can be applied to a query:

  • limit - Limits the number of results returned from the query.
  • offset - Offsets the results returned from the query by the given number of results.
  • order - Orders the results by the given variable’s degree. If a type is provided, order by the attribute of that type on that concept. Order is ascending by default.

match $x isa person, has identifier $id; limit 10; offset 5; order by $id asc; get;
match $x isa person, has firstname $y; order by $y asc; get;

qb.match(var("x").isa("person").has("identifier", var("id")))
    .orderBy("id", Order.asc)

Note that the order in which you specify modifiers can be important. If you make a query and limit the results returned, say to 10 as in the example, then specify the order by modifier after the limit, you will find that you get an ordering of 10 arbitrary results (so an ordering of a sample of the results). If instead, you do order by, then limit you will get a global ordering.

match $x isa person, has firstname $y; limit 10; order by $y asc; get;
# Returns 10 arbitrary people, ordered by firstname
match $x isa person, has firstname $y; order by $y asc; limit 10; get;
# Returns the 10 people who come first alphabetically by firstname
Tags: graql