Using ipython-gremlin

The following guide demonstrates the usage of ipython-gremlin through an example interactive live session. It assumes that an instance of Gremlin Server version 3.2.4 is running is running at localhost:8182 using the gremlin-server-modern.yaml configuration file:

$ ./bin/ conf/gremlin-server-modern.yaml

Using Gremlin Magic

The first thing to do is load the extension:

In [1]: %load_ext gremlin

By default, ipython-gremlin will connect to ws://localhost:8182/gremlin. This can be changed at the beginning of the session by configuring the GremlinMagic object, but the easy way to do this is to simply set the current connection to the desired url:

In [2]: %gremlin.connection.set_current ws://localhost:8182/gremlin
Alias-- localhost --created for database at ws://localhost:8182/gremlin

Notice the output stating that an alias has been created for this connection. Connection aliases will be further discussed later in this document.

Line Magic

The first two statements shown here use what is called “line magic”, which is denoted by the % symbol followed by a command name as well as any number of arguments.

Line magic is generally the best way to use ipython-gremlin, as it allows you to bind the results of a magic traversal to a variable, or integrate with Python code in other ways:

In [3]: verts = %gremlin g.V()

In [4]: verts
Out[4]: [v[1], v[2], v[3], v[4], v[5], v[6]]

In [5]: for v in verts:
   ...:     vid =
   ...:     props = %gremlin g.V(vid).properties()
   ...:     print(props)
   [vp[name->marko], vp[age->29]]
   [vp[name->vadas], vp[age->27]]
   [vp[name->lop], vp[lang->java]]
   [vp[name->josh], vp[age->32]]
   [vp[name->ripple], vp[lang->java]]
   [vp[name->peter], vp[age->35]]

Notice that ipython-gremlin can detect bindings stored in the user namespace:

In [6]: vid = 1

In [7]: %gremlin g.V(vid)
Out[7]: [v[1]]

Cell Magic

ipython-gremlin also supports “cell magic”, denoted by %%. This allows multi-line traversals to be submitted to the server. The downside to cell magic is that the results cannot be bound to a variable in the IPython namespace. Regardless, it can be useful for things like creating elements or executing management commands:

In [8]: %%gremlin
    ...: graph.addVertex('dog').property('name', 'ewok')
    ...: // ... do stuff ...
Out[8]: [v[13]]

Integration with pandas and networkx

When possible, results generated by traversal can be converted into pandas.DataFrame and networkx.MultiDiGraph objects. This helps facilitate plotting, transformation, and analysis.


Gremlin traversals can produce complex results and nested datastructures that are difficult to map to a two dimensional table. Despite this, many traversals return relatively simple results that are easy to translate to a tabular structure. For example:

In [9]: values = %gremlin g.V().valueMap(true)

In [10]: values.dataframe
    age  id     label    lang      name
0  [29]   1    person     NaN   [marko]
1  [27]   2    person     NaN   [vadas]
2   NaN   3  software  [java]     [lop]
3  [32]   4    person     NaN    [josh]
4   NaN   5  software  [java]  [ripple]
5  [35]   6    person     NaN   [peter]

In [11]: edges = %gremlin g.E()

In [12]: edges.dataframe
   id  inV    label  outV
0   7    2    knows     1
1   8    4    knows     1
2   9    3  created     1
3  10    5  created     4
4  11    3  created     4
5  12    3  created     6


When a traversal returns a collection of elements, they can be used to produce a NetworkX graph. Typically a container of edges or paths is the best way to utilize this functionality:

In [13]: edges.graph
Out[13]: <networkx.classes.multidigraph.MultiDiGraph at 0x7f806b8ee828>

In [14]: paths = %gremlin g.V().outE().inV().outE().inV().path()

In [15]: paths.graph
Out[15]: <networkx.classes.multidigraph.MultiDiGraph at 0x7f806b8a2208>

Managing Connections

Typically, Gremlin-Python manages connections using a Cluster object that maintains connection pools to a series of hosts specified using configuration parameters. ipython-gremlin has a simpler use case than many apps using Gremlin-Python or aiogremlin, and therefore doesn’t use a Cluster under the hood. Instead, it manages a registry of simple connections to individual hosts. To add a new host, simply use the line magic shown above:

In [16]: %gremlin.connection.set_current ws://davebshow@myhost:8182/gremlin
Alias-- davebshow@myhost --created for database at ws://localhost:8182/gremlin

If necessary, this creates a new connection to the specified host, and sets this connection as the current connection to be used by ipython-gremlin. An alias for this connection is created automagically, which can be used to refer to this connection. For example, to switch back to the default localhost connection:

In [17]: %gremlin.connection.set_current localhost
Now using connection at ws://localhost:8182/gremlin

Connection Aliases

ipython-gremlin allows the creation of custom aliases. If it is the first time a connection is created (using %gremlin.connection.set_current), the alias can be set during creation:

In [18]: %gremlin.connection.set_current ws://localhost:8182/gremlin as TestDB
Alias-- TestDB --created for database at ws://localhost:8182/gremlin
Now using connection at ws://localhost:8182/gremlin

For an existing connection, an alias can be set using the $gremlin.connection.set_alias line magic:

In [19]: %gremlin.connection.set_alias ws://localhost:8182/gremlin as TestDB2
Alias-- TestDB2 --created for database at ws://localhost:8182/gremlin

Getting the Current Connection

The current connection can be accessed using the line magic %gremlin.connection.current:

In [20]: %gremlin.connection.current
Out[20]: Connection at ws://localhost:8182/gremlin aliased as localhost

Cell Magic and Connection Management

Connections can also be managed using cell magic (%%gremlin). Connections are created, aliased, and set as current simply by passing a connection string on the first line of the cell:

In [21]: %%gremlin ws://localhost:8182/gremlin as MyHost
...: g.V()
Out[21]: [v[1], v[2], v[3], v[4], v[5], v[6]]

In [22]: %%gremlin MyHost
   ...: g.V()
Out[22]: [v[1], v[2], v[3], v[4], v[5], v[6]]

Closing Connections

ipython-gremlin tries to clean up conextions using the atexit module, but it is a good idea to explicitly close connections at the end of the interactive session. This is done using line magic:

In [23]: %gremlin.connection.close

Or, more simply:

In [24]: %gremlin.close

To close an individual connection, pass a valid connection string as an argument to %gremlin.connection.close:

In [25]: %gremlin.connection.close localhost


GremlinMagic also supports the Configurable interface. It provides a range of connection configuration options. These options are displayed using the %config cell magic:

In [26]: %config GremlinMagic
GremlinMagic options
    Current: {'g': 'g'}
    Aliases for underlying graph
    Current: ''
    Password used in SASL authentication
    Current: None
    Timeout for server response
    Current: None
    `ssl.SSLContext` object for SSL
    Current: 'ws://localhost:8182/gremlin'
    Default database URI if none is defined inline
    Current: ''
    Username used in SASL authentication

Changing this configuration is easy:

In [27]: %config GremlinMagic.username = 'davebshow'

In [28]: %config GremlinMagic.username
Out[28]: 'davebshow'

NOTE Configuration changes do not affect connections that have already been established. Please update configuration before performing other %gremlin line magic.

That’s it! I hope you enjoy using ipython-gremlin!