Graql Match Queries
Edit me

A match query will search the graph for any subgraphs that match the given pattern, returning a result for each match found. The results of the query 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.

<relative-path-to-Grakn>/bin/ start 
<relative-path-to-Grakn>/bin/ -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;


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"; 
qb.match(var("x").has("id", "1216728"));


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

match $x val contains "Bar";


Match concepts that have the resource specified. If a predicate is provided, the resource must also match that predicate.

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


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

match $x isa person; ($x, $y); 
match $x isa person; (spouse1:$x, $y); 
match $x isa person; (spouse1:$x, $y); $x has identifier $xn; $y has identifier $yn;
qb.match(var("x").isa("person"), var().rel("x").rel("y"));
qb.match(var("x").isa("person"), var().rel("spouse1", "x").rel("y"));
  var().rel("spouse1", "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";};
    var("x").isa("person").has("identifier", var("y")),

Type Properties

The following properties only apply to types.


Match types that are a subclass of the given type.

match $x sub concept; # List all concepts
match $x sub resource; # List all resources
match $x sub entity; # List all entities
match $x sub role; # List all roles
match $x sub relation; # List all relations


Match roles to a given relation.

match parentship relates $x;


Match concept types that play the given role.

match $x plays child;


Match concept types that can have the given resource.

match $x has firstname; 

The above is equivalent to:

match $x plays has-firstname-owner;


Allows you to refer to a specific types by its typename. For example:

match $x isa $type;$type label 'person';

This is equivalent to the following:

match $x isa person;


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;
qb.match(var("x").has("age", gt(70));

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;


Asks if the given string is a substring.

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

    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).*/;


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

  • distinct - Removes any duplicate results.
  • 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 resource of that type on that concept. Order is ascending by default.
  • select - Indicates which variables to include in the results.
match $x isa person, has identifier $id; select $id; limit 10; offset 5; order by $id asc;
match $x isa person, has firstname $y; select $y; order by $y asc; distinct;
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 distinct modifier after the limit, you may find that distinct removes any non-unique results, so you end up with fewer than the 10 results you expected to be returned to you. To ensure that you receive exactly 10 distinct results, you are better to use distinct before limit.

match $x isa person, has firstname $y; select $y; limit 10; distinct; order by $y asc;
# Returns 9 results
match $x isa person, has firstname $y; select $y; distinct; limit 10; order by $y asc;
# Returns 10 results


Want to leave a comment? Visit the issues on Github for this page (you’ll need a GitHub account). You are also welcome to contribute to our documentation directly via the “Edit me” button at the top of the page.

Tags: graql