How to construct and execute Graql queries programmatically in Java.
Edit me

As well as the Graql shell, users can also construct and execute Graql queries programmatically in Java. The Java Graql API expresses the concepts and functionality of the Graql language in the syntax of Java. It is useful if you want to make queries using Java, without having to construct a string containing the appropriate Graql expression.

To use the API, add the following to your pom.xml:


and add the following to your imports.

import ai.grakn.graql.QueryBuilder;


Graql contains several useful static methods such as var and eq, so it’s recommended that you use a static import:

import static ai.grakn.graql.Graql.*;

A QueryBuilder is constructed from a GraknTx:

GraknTx tx = Grakn.session(Grakn.IN_MEMORY, "MyGraph").open(GraknTxType.WRITE);
QueryBuilder qb = tx.graql();

The user can also choose to not provide a knowledge base with Graql.withoutTx(). This can be useful if you need to provide the knowledge base later (using withTx), or you only want to construct queries without executing them.

The QueryBuilder class provides methods for building matches and insert queries. Additionally, it is possible to build aggregate, match..insert and delete queries from match queries.


Matches are constructed using the match method. This will produce a Match instance, which includes additional methods that apply modifiers such as limit and distinct:

Match match = qb.match(var("x").isa("person").has("firstname", "Bob")).limit(50);

If you’re only interested in one variable name, it also includes a get method for requesting a single variable:

match.get("x").forEach(x -> System.out.println(x.asResource().getValue()));

Get Queries

Get queries are constructed using the get method on a match.

GetQuery query = qb.match(var("x").isa("person").has("firstname", "Bob")).limit(50).get();

GetQuery is Iterable and has a stream method. Each result is a Map<Var, Concept>, where the keys are the variables in the query.

A GetQuery will only execute when it is iterated over.

for (Map<String, Concept> result : query) {

Aggregate Queries

if (qb.match(var().isa("person").has("firstname", "Bob")).aggregate(ask()).execute()) {
  System.out.println("There is someone called Bob!");

Insert Queries

InsertQuery addAlice = qb.insert(var().isa("person").has("firstname", "Alice"));


// Marry Alice to everyone!
  var("alice").has("firstname", "Alice")
    .rel("spouse", "someone")
    .rel("spouse", "alice")

Delete Queries

qb.match(var("x").has("firstname", "Alice")).delete("x").execute();

Query Parser

The QueryBuilder also allows the user to parse Graql query strings into Java Graql objects:

for (Answer a : qb.<GetQuery>parse("match $x isa person; get;")) {

if (qb.<AggregateQuery<Boolean>>parse("match has name 'Bob' isa person; aggregate ask;").execute()) {
  System.out.println("There is someone called Bob!");

qb.parse("insert isa person, has firstname 'Alice';").execute();

qb.parse("match $x isa person; delete $x;").execute();


Reasoning can be configured using QueryBuilder objects in the following way:

Switching reasoning on

//tx is a GraknTx instance
qb = tx.graql().infer(true);

Switching materialisation on

//tx is a GraknTx instance
qb = tx.graql().infer(true).materialise(true);

Once the QueryBuilder has been defined, the constructed queries will obey the specified reasoning variants.

The table below summarises the available reasoning configuration options together with their defaults.

Option Description Default
QueryBuilder::infer(boolean) controls whether reasoning should be turned on False=Off
QueryBuilder::materialise(boolean) controls whether inferred knowledge should be persisted to knowledge base False=Off
Tags: graql java