Get Started

Launch the gremlin.sh (or gremlin.bat on Windows OS) console script located in the bin directory:

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

Open the graph database

Before playing with Gremlin you need a valid OrientGraph instance that points to an OrientDB database. To know all the database types look at Storage types.

When you're working with a local or an in-memory database, if the database does not exist it's created for you automatically. Using the remote connection you need to create the database on the target server before using it. This is due to security restrictions.

Once created the OrientGraph instance with a proper URL is necessary to assign it to a variable. Gremlin is written in Groovy, so it supports all the Groovy syntax, and both can be mixed to create very powerful scripts!

Example with a local database (see below for more information about it):

Working with a remote database

To open a database on a remote server be sure the server is up and running first. To start the server just launch server.sh (or server.bat on Windows OS) script. For more information look at OrientDB Server

Use security

OrientDB supports security by creating multiple users and roles associated with certain privileges. To know more look at Security. To open the graph database with a different user than the default, pass the user and password as additional parameters:

Save changes

OrientDB assigns a temporary identifier to each vertex and edge that is created. To save them to the database stopTransaction(SUCCESS) should be called

gremlin> g.stopTransaction(SUCCESS)

Retrieve a vertex

To retrieve a vertex by its ID, use the v(id) method passing the Record ID as an argument (with or without the prefix '#'). This example retrieves the first vertex created in the above example.

gremlin> g.v('5:0')
==>v[#5:0]

Get all the vertices

To retrieve all the vertices in the opened graph use .V (V in upper-case):

gremlin> g.V
==>v[#5:0]
==>v[#5:1]

Retrieve an edge

Retrieving an edge is very similar to retrieving a vertex. Use the e(id) method passing the Record ID as an argument (with or without the prefix '#'). This example retrieves the first edge created in the previous example.

gremlin> g.e('6:0')
==>e[#6:0][#5:0-friend->#5:1]

Get all the edges

To retrieve all the edges in the opened graph use .E (E in upper-case):

gremlin> g.E
==>e[#6:0][#5:0-friend->#5:1]

Traversal

The power of Gremlin is in traversal. Once you have a graph loaded in your database you can traverse it in many different ways.

Basic Traversal

To display all the outgoing edges of the first vertex just created append the .outE at the vertex. Example:

gremlin> v1.outE
==>e[#6:0][#5:0-friend->#5:1]

To display all the incoming edges of the second vertex created in the previous examples append the .inE at the vertex. Example:

gremlin> v2.inE
==>e[#6:0][#5:0-friend->#5:1]

In this case the edge is the same because it's the outgoing edge of 5:0 and the incoming edge of 5:1.

Passing input parameters

Some Gremlin expressions require declaration of input parameters to be
run. This is the case, for example, of bound variables, as described
in JSR223 Gremlin Script Engine. OrientDB has enabled a mechanism to
pass variables to a Gremlin pipeline declared in a command as
described below:

Declaring output

In the simplest case, the output of the last step (https://github.com/tinkerpop/gremlin/wiki/Gremlin-Steps) in the Gremlin pipeline corresponds to the output of the overall Gremlin expression. However, it is possible to instruct the Gremlin engine to consider any of the input variables as output. This can be declared as:

There are more possibilities to define the output in the Gremlin pipelines. So this mechanism is expected to be extended in the future. Please, contact OrientDB mailing list to discuss customized outputs.

Conclusions

Now you've learned how to use Gremlin on top of OrientDB. The best place to go in depth with this powerful language is the Gremlin WiKi.