How to use the Grakn Workbase Visualiser.

Visualiser UI

Introduction

The Grakn visualiser provides a graphical tool to inspect and query your knowledge graph data. This article shows how to run it with a basic example and introduces the visualiser’s key features.

Loading an Example Knowledge Graph

If you have not yet set up the Grakn environment, please see the Setup guide.

You can find the basic-genealogy.gql example that we will work with in the examples directory of the Grakn distribution zip. You can also find this file on Github.

The first step is to load the schema and data into Grakn. You need to use your terminal to do this, as the visualiser is a read-only interface to a knowledge graph. From the terminal, start Grakn, and load the file as follows:

./grakn server start
./graql console -f ./examples/basic-genealogy.gql -k "family"

To illustrate the use of different keyspaces we will use a keyspace called family in this example. You can simply use the default (grakn) keyspace if you prefer, by omitting the -k argument.

You can test in the Graql shell that all has loaded correctly. For example:

./graql console -k family
>>>match $p isa person, has identifier $i;

Keyspace Handler

At the top right corner. there is the keyspace handler which allows you to select a keyspace to visualise.

Visualiser UI

At the top center, there is the menu bar where you can access the main functionalities related to your Graql queries.

Visualiser UI

From left to right:

  • Starred Queries button - List all the saved queries which you can use or delete

  • Types Panel button - Provides a list of concepts that are available in your keyspace, divided into “Entities”, “Attributes”, “Relationships”.

  • Graql Editor - Input box for your graql queries
    • enter - run query
    • shift + enter - will add a new line to the editor (useful for long queries)
    • shift + up/down - navigate through previous graql queries
  • Save Query - Allows user to save the current query to starred queries

  • Execute Query button - executes the graql query.

  • Clear Graql Editor button - clears the graql editor

  • Query Settings button - provides the user with certain settings for queries

Context Menu

  • Node Settings - Open the node settings panel to show different information about the node on the graph and change the colour or the nodes of the same type.

  • Delete Node - Delete a node or multiple nodes from the graph.

  • Explain - If the node is inferred, show the relationships and nodes which explain how it is inferred.

  • Shortest Path - Show shortest path between two nodes.

  • Clear Graph - Clear everything on the graph.

Manage Keyspace

Shows the list of keyspaces and allows you to delete an exisiting one or create a new one.

Manage keyspaces

Interacting With The Graph

Make a Query

The graph will be empty at this point. You can submit queries by typing them into the form in the middle of the top menu bar. You will then need to click > or hit enter to visualise the knowledge graph. For example:

match $x isa person, has firstname "John"; get;

John query

You can zoom the display in and out, and move the nodes around for better visibility.

Alternatively, for simple visualisation, you can click the Types dropdown in the top menu to list out what is in the schema. For our example, go to the Entities dropdown and choose person. The query specific to your selection will be displayed in the form with a default offset and result limit, which is applied by the visualiser offset 0; limit 30.

match $x isa person; offset 0; limit 30; get;

You can change the offset and limit on the number of results as described below.

Visualiser UI

Save a Query

If you make a query that you think you’ll need to repeat regularly, and don’t want to type it, or copy and paste it each time, you can save your query. The small plus sign in a circle on the right hand side of the form will bring up a tool tip, allowing you to assign it a name and save it. Saved queries can then be retrieved using the star button on the left hand side of the menu bar.

Visualiser UI Visualiser UI

Investigate a Node

A single click on any node in the knowledge graph brings up a tool tip of information about the node at the top right hand side of the screen. The information displayed includes the ID of the node, its type and any attributes associated with it, as shown in the figure below.

Single click

A double click on a node will bring up the relationships associated with the node, as shown below. The first doule click will load a single batch of relationships as per the neighbours limit. Any consequent double click will load the next batch of relationships.

Double click

Holding shift and double clicking on a node also brings up the attributes associated with it, displaying them in the knowledge graph, as shown below. The first shift + doule click will load a single batch of attributes as per the neighbours limit. Any consequent shift + double click will load the next batch of attributes.

shift double click

You may also select multiple nodes by holding Cmd/Ctrl and clicking on nodes.

Change the Display

Selecting Node Settings in the context menu opens the node settings panel on the lower left hand side of the screen. You can use this to show different information about a node on the graph and change the colour of the nodes.

Single click

Query Settings

Query Settings can be accessed under the cog icon at the right hand of the horizontal icon set. The following settings are available:

Person query

Limit Query

You can change the offset and limit on the number of results returned by editing the value directly in the submission form, or by adjusting the Query Limit setting. (This limit will only be enforced only when no offset is specified by the user in the query)

Limit Neighbours

Allows the user to limit the nodes loaded when double clicking or shift + double clicking on a node.

Autoload Role Players

You can enable or disable loading role players with relationships. This is useful when you only want to visualise the relationships without their role players. You can see the differences between the same query when autoload roleplayers is enabled and disabled below.

enabled: Person query disabled: Person query

Explain an Inferred Concept

If a nodes is inferred, you can select the Explain option from the context menu and get the explainaion of how it is inferred. e.g if the cousin relationship is inferred, selecting explain would give us the following:

explain

explain

Shortest Path

Select two nodes and select the Shortest Path option in the context menu to display the shortest path between the two nodes if it exists.

explain

explain

Graph Data

The tool tip on the bottom right of the graph will display the number of nodes and edges in the graph.

canvas data

Commands

Selecting the information icon on the bottom left of the graph opens a modal containing all the ways to interact with the graql editor and graph.

commands icon

Manage Settings

Engine Settings

Allows user to configure the host and port of Grakn.

engine settings

Preference Settings

Allows user to clear all saved preferences:

  • Favourite queries
  • Query limit
  • Neighbours limit
  • Autoload roleplayers
  • Node labels
  • Node Colours

preference settings

Where Next?

Now you have started getting to grips with Grakn, please explore our additional example code and documentation. We are always adding more and welcome ideas and improvement suggestions. Please get in touch!