Overview and setup guide for Java developers.

Basic Setup

This section will discuss how to start developing with Grakn using the Java API. All Grakn applications require the following Maven dependency:



This dependency will give you access to the Core API as well as an in-memory knowledge graph, which serves as a toy knowledge graph, should you wish to use the stack without having to have an instance of the Grakn server running.

Server Dependent Setup

If you require persistence and would like to access the entirety of the Grakn stack, then it is vital to have an instance of engine running.
Please see the Setup Guide on more details on how to set up a Grakn server.

Alternatively, you may include a reference to the snapshot repository, which contains the third-party dependencies. Add the following to your pom.xml:

  <!--Snapshot repository for 3rd party libraries -->

Here are some links to guides for adding external jars using different IDEs:

Connecting to Grakn

First, make sure that Grakn is running. Otherwise, boot it up with grakn server start. Now, connect to Grakn with:

GraknSession session = RemoteGrakn.session(new SimpleURI("localhost:48555"), Keyspace.of("grakn"));
try (GraknTx tx = session.open(GraknTxType.READ)) {
  // ...

A “Keyspace” uniquely identifies the knowledge graph and allows you to create different knowledge graphs.

Please note that keyspaces are not case sensitive, so the following two keyspaces are actually the same:

    GraknTx tx1 = RemoteGrakn.session(new SimpleURI("localhost:48555"), Keyspace.of("grakn")).open(GraknTxType.WRITE);
    GraknTx tx2 = RemoteGrakn.session(new SimpleURI("localhost:48555"), Keyspace.of("grakn")).open(GraknTxType.WRITE);

All knowledge graphs are also singletons specific to their keyspaces so be aware that in the following case:

   tx1 = RemoteGrakn.session(new SimpleURI("localhost:48555"), Keyspace.of("grakn")).open(GraknTxType.WRITE);
   tx2 = RemoteGrakn.session(new SimpleURI("localhost:48555"), Keyspace.of("grakn")).open(GraknTxType.WRITE);
   tx3 = RemoteGrakn.session(new SimpleURI("localhost:48555"), Keyspace.of("grakn")).open(GraknTxType.WRITE);

any changes to tx1, tx2, or tx3 will all be persisted to the same knowledge graph.

Controlling The Behaviour of Knowledge Graph Transactions

When initialising a transaction on a knowledge graph it is possible to define the type of transaction with GraknTxType. We currently support three types of transactions:

  • GraknTxType.WRITE - A transaction that allows mutations to be performed on the knowledge graph
  • GraknTxType.READ - Prohibits any mutations to be performed to the knowledge graph
  • GraknTxType.BATCH - Allows faster mutations to be performed to the knowledge graph at the cost of switching off some internal consistency checks. This option should only be used if you are certain that you are loading a clean dataset.

Where Next?

The pages in this section of the documentation cover some of the public APIs available to Java developers:

There is also a page (in progress) that discusses advanced topics in Java development, such as transactions and multi-threading.

There is an example described in our blog that discusses how to get set up to develop using Java, and how to work with the Java API.

Tags: java