Chapter 7. Titan Server

gremlin-server

Titan uses the Gremlin Server engine as the server component to process and answer client queries.

Gremlin Server provides a way to remotely execute Gremlin scripts against one or more Titan instances hosted within it. By default, client applications can connect to it via WebSockets with a custom subprotocol (there are a number of clients developed in different languages to help support the subprotocol). Gremlin Server can also be configured to serve a simple REST-style endpoint for processing Gremlin as well. These configurations just represent the out-of-the-box options for Gremlin Server. It is certainly possible to also extend it with other means of communication by implementing the interfaces that it provides.

The Titan Download comes pre-configured to run Gremlin Server without any additional configuration. Alternatively, one can Download Gremlin Server separately and then install Titan manually.

7.1. Gremlin Server with Titan

There are two ways to download and install Gremlin Server with Titan.

  1. Titan’s zip downloads come with Gremlin Server, Titan, and BerkeleyDB pre-configured to work together.
  2. Download Gremlin Server separately and then manually install Titan.

Each of these approaches is described below.

7.1.1. Getting Started Quickly

  • Download a copy of the current titan-$VERSION.zip file from the Downloads page
  • Unzip it and enter the titan-$VERSION directory
  • Run bin/gremlin-server.sh. This step will start Gremlin Server with a BerkeleyDB instance.

7.1.2. Manual Installation

This section describes the process of downloading a stock Gremlin Server distribution and then installing Titan.

Gremlin Server can be downloaded at here.

Edit the GREMLIN_SERVER_HOME/conf/gremlin-server.yaml and include the following settings to the defaults:

...
graphs: {
  graph: conf/gremlin-server/titan-berkeleyje-server.properties}
plugins:
  - aurelius.titan
scriptEngines: {
  gremlin-groovy: {
    imports: [java.lang.Math],
    staticImports: [java.lang.Math.PI],
    scripts: [scripts/empty-sample.groovy]},
...

The entry for graphs defines the bindings to specific TitanGraph configuration. In the above case it binds graph to a Titan configuration at conf/titan-berkeleyje.properties. This means that when referencing the TitanGraph in remote contexts, this graph can simply be referred to as graph in scripts sent to the server. The plugins entry simply enables the Titan Gremlin Plugin, which enables auto-imports of Titan classes so that they can be referenced in remotely submitted scripts. Finally, note the scripts entry, which specifies a list of groovy scripts to execute in the engine. In this case, it points to scripts/empty-sample.groovy. Its contents look like this:

g = graph.traversal()

This scripts creates the GraphTraversalSource from which traversals can be spawned. The variable g becomes bound to the script engine so that on future requests it can be referenced directly.

Next add a conf/titan-berkeleyje.properties file which should contain something like:

gremlin.graph=com.thinkaurelius.titan.core.TitanFactory
storage.backend=berkeleyje
storage.directory=db/berkeley

Gremlin Server needs to have Titan and its related library dependencies made available to it. It has an ext directory where these libraries can be placed on Gremlin Server’s path. To get Titan on the path, issue the following command (it may take a few minutes to complete this step depending on network speed):

$ bin/gremlin-server.sh -i com.thinkaurelius.titan titan-all $VERSION

Start Gremlin Server with:

$ bin/gremlin-server.sh

7.2. Connecting to Gremlin Server

Regardless of the download and installation method chosen above, Gremlin Server will be ready to listen for WebSocket connections when it is started. The easiest way to test the connection is with Gremlin Console.

Start Gremlin Console with bin/gremlin.sh and use the :remote and :> commands to issue Gremlin to Gremlin Server:

$  bin/gremlin.sh
         \,,,/
         (o o)
-----oOOo-(3)-oOOo-----
plugin activated: tinkerpop.server
plugin activated: tinkerpop.hadoop
plugin activated: tinkerpop.utilities
plugin activated: aurelius.titan
plugin activated: tinkerpop.tinkergraph
gremlin> :remote connect tinkerpop.server conf/remote.yaml
==>Connected - localhost/127.0.0.1:8182
gremlin> :> graph.addVertex("name", "stephen")
==>v[256]
gremlin> :> g.V().values('name')
==>stephen

The :remote command tells the console to configure a remote connection to Gremlin Server using the conf/remote.yaml file to connect. That file points to a Gremlin Server instance running on localhost. The :> is the "submit" command which sends the Gremlin on that line to the currently active remote.