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;
At the top right corner. there is the keyspace handler which allows you to select a keyspace to visualise.
At the top center, there is the menu bar where you can access the main functionalities related to your Graql queries.
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
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.
Shows the list of keyspaces and allows you to delete an exisiting one or create a new one.
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;
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.
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.
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.
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.
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.
You may also select multiple nodes by holding Cmd/Ctrl and clicking on nodes.
Change the Display
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.
Query Settings can be accessed under the cog icon at the right hand of the horizontal icon set. The following settings are available:
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)
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.
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:
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.
The tool tip on the bottom right of the graph will display the number of nodes and edges in the graph.
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.
Allows user to configure the host and port of Grakn.
Allows user to clear all saved preferences:
- Favourite queries
- Query limit
- Neighbours limit
- Autoload roleplayers
- Node labels
- Node Colours
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!