Skip to content

Getting Started

Jump to bottom Edit New page
okram edited this page Jun 14, 2012 · 75 revisions

In the beginning, there existed two deities known as Uranus and Gaia. They gave birth to the Titans (a race of powerful beings). Saturn, Titan of time, set reality in motion. Ultimately, time yielded the existence of the sky, the sea, and the end of life—death. To rule these notions, Saturn had three sons: Jupiter (sky), Neptune (sea), and Pluto (underworld). The son’s of Saturn were not Titans, but a race of seemingly less powerful deities known the world over as the Gods. Fearful that his sons would overthrow him, Saturn devoured them and imprisoned them in his stomach. This caused a great war between the Titans and Gods. Ultimately, the Gods won and Jupiter took the thrown as leader of the Gods.


Jupiter
Neptune
Pluto

The Graph of the Gods

The examples in this section make extensive use of a toy graph distributed with Titan called The Graph of the Gods. This graph is diagrammed below. The abstract data model is known as a property graph and this particular instance describes the relationships between the beings and places of the Roman pantheon. The Graph of the Gods GraphML file is available at this location.

Downloading Titan and Running the Gremlin Shell

Unbeknownst to the Gods, there still lived one Titan. This Titan can not be seen, has no name, and is only apparent in the fact that reality exists. Upon the shoulders of this lost Titan, all of reality hangs together in an undulating web of relations.

Titan can be downloaded from the Downloads section of the project repository. Once retrieved and unpacked, a Gremlin terminal can be started. The Gremlin REPL (i.e. interactive shell) is distributed with Titan and differs slightly from the main Gremlin distribution in that is comes preloaded with Titan-specific imports and helper methods. In the example below, titan.zip is used, however, be sure to unzip the zip-file that was downloaded.

$ unzip titan.zip
Archive:  titan.zip
   creating: titan/
  inflating: titan/pom.xml  
   creating: titan/src/
   creating: titan/src/assembly/
...
$ cd titan
$ bin/gremlin.sh 

         \,,,/
         (o o)
-----oOOo-(_)-oOOo-----
gremlin>

The Gremlin terminal is a Groovy shell. Groovy is a superset of Java that has various shorthand notations that make interactive programming easier. The basic examples below demonstrate handling numbers, strings, and maps.

gremlin> 100-10
==>90
gremlin> "Titan:" + " The Rise of Big Graph Data"
==>Titan: The Rise of Big Graph Data
gremlin> [name:'aurelius',vocation:['philosopher','emperor']]
==>name=aurelius
==>vocation=[philosopher, emperor]

Loading Data Into Titan


Gremlin is a graph traversal language that can be used with any Blueprints enabled graph database. The example below will load The Graph of the Gods into Titan. TitanFactory provides methods to create various Titan instances (e.g. local, distributed, etc.). A local instance of Titan is created using the TitanFactory.open(String directory) method. For the sake of understanding graphs, local mode is sufficient. Other pages in the documentation demonstrate distributed Titan using Cassandra and using HBase.

gremlin> g = TitanFactory.open('/tmp/titan')              
==>titangraph[local:/tmp/titan]

The created Titan database is empty and ready to be loaded with data. Before doing so, a key index is created over the property name. This will ensure that all vertices with the property name are indexed by their respective name value. With a key index on name, looking up a vertex by its name takes log(n) time.

gremlin> g.createKeyIndex('name', Vertex.class)
==>null
gremlin> g.stopTransaction(SUCCESS)
==>null

The following snippet loads The Graph of the Gods dataset which comes packaged with Titan in the data/ directory. Given that there is an index on name property, the Saturn vertex can be retrieved. The property map (i.e. the key/value pairs of Saturn) can then be examined. As demonstrated, the Saturn vertex has a name of “saturn” and a type of “titan.” Finally, the grandchild of Saturn can be retrieved with a traversal that expresses: “Who is Saturns’ childs’ child?” (the inverse of “father” is “child”). The result is Hercules.

gremlin> g.loadGraphML('data/graph-of-the-gods.xml')
==>null
gremlin> saturn = g.V('name','saturn').next()
==>v[20]
gremlin> saturn.map()
==>name=saturn
==>type=titan
gremlin> saturn.in('father').in('father').name
==>hercules

Graph Traversal Examples

Hercules, son of Jupiter and Alcmene, bore super human strength. Hercules was a demigod because his father was a god and his mother was a human. Juno, wife of Jupiter, was furious with Jupiter’s infidelity. In revenge, she blinded Hercules with temporary insanity and caused him to kill his wife and children. To atone for the slaying, Hercules was ordered by the Oracle of Delphi to serve Eurystheus. Eurystheus appointed Hercules to 12 labors.


Nemean 		Hydra
Cerberus

In the previous section, it was demonstrated that Saturns’ grandchild was Hercules. This can be expressed using a loop. In essence, Hercules is the vertex that is 2-steps away from Saturn along the in('father') path.

gremlin> hercules = saturn.in('father').loop(1){it.loops < 3}.next()
==>v[24]

Hercules is a demigod. To prove that Hercules is half human and half god, his parent’s origins must be examined. It is possible to traverse from the Hercules vertex to his mother and father. Finally, it is possible to determine the type of each of them — yielding “god” and “human.”

gremlin> hercules.out('father','mother')
==>v[16]
==>v[44]
gremlin> hercules.out('father','mother').name
==>jupiter
==>alcmene
gremlin> hercules.out('father','mother').type
==>god
==>human
gremlin> hercules.type
==>demigod

The examples thus far have been with respect to the genetic lines of the various actors in the Roman pantheon. However, the property graph data model is expressive enough to represent multiple types of things and relationships. In this way, The Graph of the Gods can also identify Hercules’ various heroic exploits - his famous 12 labors.

gremlin> hercules.out('battled')
==>v[40]
==>v[12]
==>v[48]
gremlin> hercules.out('battled').map
==>{name=nemean, type=monster}
==>{name=hydra, type=monster}
==>{name=cerberus, type=monster}
gremlin> hercules.outE('battled').has('time',T.gt,1).inV.name
==>hydra
==>cerberus

More Complex Graph Traversal Examples

In the depths of Tartarus lives Pluto. His relationship with Hercules was strained by the fact that Hercules battled his pet, Cerberus. However, Hercules is his nephew — how should he make Hercules pay for his insolence?

The Gremlin traversals below provide more examples over The Graph of the Gods. The explanation of each traversal is provided in the prior line as a // comment.



Coinhabitors of Tartarus

gremlin> pluto = g.V('name','pluto').next()
==>v[4]
gremlin> // who are pluto's cohabitants?
gremlin> pluto.out('lives').in('lives').name                
==>cerberus
==>pluto
gremlin> // pluto can't be his own cohabitant
gremlin> pluto.out('lives').in('lives').except([pluto]).name
==>cerberus

Pluto’s Brothers

gremlin> // where do pluto's brothers live?
gremlin> pluto.out('brother').out('lives').name
==>sky
==>sea
gremlin> // which brother lives in which place?
gremlin> pluto.out('brother').as('god').out('lives').as('place').select
==>[god:v[16], place:v[36]]
==>[god:v[8], place:v[32]]
gremlin> // what is the name of the brother and the name of the place?
gremlin> pluto.out('brother').as('god').out('lives').as('place').select{it.name}
==>[god:jupiter, place:sky]
==>[god:neptune, place:sea]

Moving Forward with Titan

This section presented some basic examples of how to create a local Titan instance, load it with data represented in GraphML, and traverse that data using Gremlin. In essence, a graph database is all about representing some world model (structure) and traversing it to solve problems (process). The remainder of this documentation discusses more in-depth examples and configurations for using Titan. For more information on other aspects of Titan, please see the following projects.

  • Blueprints – The property graph model interface implemented by Titan which provides various utilities to aid developers.
  • Gremlin – A graph traversal language for expressing complex walks through a graph.
  • Frames – An graph-to-object mapper for rendering Java objects from graph data.
  • Rexster – A graph server for exposing the graph via REST along with various HTML-based GUI tools for managing the graph.

Finally, for developing against a Titan SNAPSHOT version, be sure to add the following repository to the pom.xml. For stable releases, no repository is required as stable releases are deployed to Apache’s Central Repository.

<repository>
  <id>sonatype-nexus-snapshots</id>
  <name>Sonatype Nexus Snapshots</name>
  <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  <releases>
    <enabled>false</enabled>
  </releases>
  <snapshots>
    <enabled>true</enabled>
  </snapshots>
</repository>
Add a custom footer
Add a custom sidebar
Clone this wiki locally