This document will teach you how to set up a Grakn environment, start it up and load a simple example.

First: Download GRAKN.AI

Download Grakn

For more information on how to download older versions of GRAKN.AI, compile from source code, or import the Grakn Java API library as a development dependency, please visit our Downloads page.

Install GRAKN.AI

Unzip the download into your preferred location and run the following in the terminal to start Grakn:

cd [your Grakn install directory]
./grakn server start

On macOS, you can install it using the brew package manager. Binaries will be added to your path:

brew install grakn
grakn server start

This will start Grakn, which is an HTTP server providing batch loading, monitoring and the browser dashboard.

Grakn Engine is configured by default to use port 4567, but this can be changed in the file, found within the /conf directory of the installation.

Test the Graql Shell

To test that the installation is working correctly, we will load a simple schema and some data from a file and test it in the Graql shell and Grakn visualiser. The file we will use is basic-genealogy.gql, which is included in the /examples folder of the Grakn installation zip, or /usr/local/Cellar/grakn/<version>/libexec/examples folder if you installed with brew.

Type in the following in the terminal to load the example knowledge graph. This starts the Graql shell in non-interactive mode, loading the specified file and exiting after the load is complete.

./graql console -f ./examples/basic-genealogy.gql

Then type the following to start the Graql shell in its interactive (REPL) mode:

./graql console

The Graql shell starts and you see a >>> prompt. Graql is our knowledge-oriented query language, which allows you to interface with Grakn. We will enter a query to check that everything is working.

match $x isa person, has identifier $n; get;

You should see a printout of a number of lines of text, each of which includes a name, such as “William Sanford Titus” or “Elizabeth Niesz”.

If you see the above output then congratulations! You have set up Grakn.

Test the Visualiser

The Grakn visualiser provides a graphical tool to inspect and query your data. You can open the visualiser by navigating to localhost:4567 in your web browser. The visualiser allows you to make queries or simply browse the schema within the graph. The screenshot below shows a basic query (match $x isa person; get $x;) typed into the form at the top of the main pane, and visualised by pressing “>” to submit the query:

Person query

You can zoom the display in and out, and move the nodes around for better visibility. Please see our visualiser documentation for further details.


If you are having trouble getting Grakn running, please check our FAQ page, and if you have any questions, do ask them on our discussion forum, on Stack Overflow or on our Slack channel.

Where next?

Our Quickstart Tutorial will go into more detail about using Grakn and Graql.

You can find additional example code and documentation on this portal. We are always adding more and welcome ideas and improvement suggestions. Please get in touch!