Getting Started

Welcome to Gremlin. Gremlin is a domain specific language for traversing graphs. Graphs are data structures where there exists vertices (i.e. dots, nodes) and edges (i.e. lines, arcs). Gremlin was designed to work with a type of graph called a property graph. Property graphs are defined, in detail, in the Defining a Property Graph section of this documentation. By using Gremlin, it is possible make use of a REPL (command line/console) to interactively traverse a graph. Moreover, it is possible to embed Gremlin traversal expressions within a larger applications (via Groovy/Java).

Installing Gremlin

Here are the steps to get Gremlin up and running. Either git clone from http://github.com/tinkerpop/gremlin.git and build the latest version of Gremlin or you can download a pre-built version. For the latter, follow the steps below.

1. Download the latest distribution of Gremlin from downloads.
2. Unzip the downloaded gremlin-xx.zip and cd to the gremlin-xx/ directory it creates.
3. Run gremlin.sh (unix) or gremin.bat (windows) to start the Gremlin console.

Using the Gremlin Console

marko$ ./gremlin.sh 
         \,,,/
         (o o)
-----oOOo-(_)-oOOo-----
gremlin>

Thats it. The default Gremlin Groovy console is loaded and ready for commands. Please review Groovy for help on Groovy-related constructs. In short, Groovy is a superset of Java. What works in Java, works in Groovy. However, Groovy provides many shorthands to make it easier to interact with the Java API. Moreoever, Gremlin provides many neat shorthands to make it easier to express paths through a property graph.

gremlin> i = 'goodbye'
==>goodbye
gremlin> j = 'self'
==>self
gremlin> i + " " + j
==>goodbye self
gremlin> "${i} ${j}"
==>goodbye self

We will use a simple, 6 vertex/6 edge, graph that is provided with Gremlin and is fully diagrammed in Defining a Property Graph. This graph is used so much throughout the documentation that it is hard coded and can be constructed using the TinkerGraphFactory.createTinkerGraph() factory method.

gremlin> g = TinkerGraphFactory.createTinkerGraph()
==>tinkergraph[vertices:6 edges:6]
gremlin> g.class
==>class com.tinkerpop.blueprints.pgm.impls.tg.TinkerGraph
gremlin> // lets look at all the vertices
gremlin> g.V
==>v[3]
==>v[2]
==>v[1]
==>v[6]
==>v[5]
==>v[4]
gremlin> // lets look at all the names of those vertices
gremlin> g.V.name
==>lop
==>vadas
==>marko
==>peter
==>ripple
==>josh
gremlin> // lets look at all the properties of those vertices
gremlin> g.V.map
==>{name=lop, lang=java}
==>{name=vadas, age=27}
==>{name=marko, age=29}
==>{name=peter, age=35}
==>{name=ripple, lang=java}
==>{name=josh, age=32}
gremlin> // lets look at all the edges
gremlin> g.E
==>e[10][4-created->5]
==>e[7][1-knows->2]
==>e[9][1-created->3]
==>e[8][1-knows->4]
==>e[11][4-created->3]
==>e[12][6-created->3]
gremlin> v = g.v(1)
==>v[1]
gremlin> v.name + ' is ' + v.age + ' years old.'
==>marko is 29 years old.
gremlin> // lets do a traversal from the '1' marko vertex to the adjacent outgoing vertices.
gremlin> v.out
==>v[2]
==>v[3]
==>v[4]
gremlin> // lets only take 'knows' labeled edges
gremlin> v.out('knows')
==>v[2]
==>v[4]
gremlin> // lets do a traversal from the '1' marko vertex to its outgoing edges.
gremlin> // in the property graph world, edges are first class citizens that can be traversed to.
gremlin> v.outE
==>e[7][1-knows->2]
==>e[9][1-created->3]
==>e[8][1-knows->4]
gremlin> v.outE('knows')
==>e[7][1-knows->2]
==>e[8][1-knows->4]
gremlin> // what are the weight values on all outgoing edges
gremlin> v.outE.weight
==>0.5
==>0.4
==>1.0
gremlin> // lets only traverse to the head vertices of those edges
gremlin> // that have a weight that is less than 1.0
gremlin> v.outE.filter{it.weight < 1.0}.inV
==>v[2]
==>v[3]                           
gremlin> // lets get the property maps of these vertices.
gremlin> v.outE.filter{it.weight < 1.0}.inV.map
==>{name=vadas, age=27}
==>{name=lop, lang=java}
gremlin> // lets traverse to marko's 30+ year old friends' created projects
gremlin> v.out('knows').filter{it.age > 30}.out('created').name
==>ripple
==>lop

What was presented is some of the basic functionality in Gremlin. The remainder of this documentation will discuss path construction and their use in performing graph algorithms on property graph structures.