Using aiogremlin

Before you get started, make sure you have the Gremlin Server up and running. All of the following example assume a running Gremlin Server version 3.2.4 at ws://localhost:8182/gremlin using the conf/gremlin-server-modern-py.yaml configuration:

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

Using the Gremlin Language Variant

aiogremlin is used almost exactly like the official Gremlin-Python, except that all operations are asynchronous. Thus when coding with aiogremlin coroutines and the async/await syntax are used in combination with an asyncio compatible event loop implementation (tornado, ZeroMQ, uvloop, etc.).

The following examples assume that you are already familiar with asyncio, coroutines, and the event loop. For readability, they strip away these details to focus on the syntax used by aiogremlin.

To create a traversal source, simply use DriverRemoteConnection combined with Graph:

>>> remote_connection = await DriverRemoteConnection.open(
...    'ws://localhost:8182/gremlin', 'g')
>>>  g = Graph().traversal().withRemote(remote_connection)

In aiogremlin, a Traversal implements the Asynchronous Iterator Protocol as defined by PEP 492:

>>> async for vertex in g.V():
...     print(vertex)

Furthermore, it implements several convience methods - toList, toSet, and next:

>>> vertex_list = await g.V().toList()
>>> vertex_set = await g.V().toSet()
>>> next_vertex = await g.V().next() # returns next result from the stream

Traversal also contains a reference to a AsyncRemoteTraversalSideEffects object that can be used to fetch side effects cached by the server (when applicable):

>>> t = g.V().aggregate('a')
>>> await t.iterate()  # evaluate the traversal
>>> keys = await t.side_effects.keys()
>>> se = await t.side_effects.get('a')
>>> await t.side_effects.close()

Don’t forget to close the DriverRemoteConnection when finished:

>>> await remote_connection.close()

Using DriverRemoteConnection

The DriverRemoteConnection object allows you to configure you database connection in one of two ways:

1. Passing configuration values as kwargs or a dict to the classmethod open:

>>> remote_connection = await DriverRemoteConnection.open(
...    'ws://localhost:8182/gremlin', 'g', port=9430)

2. Passing a Cluster object to the classmethod using:

>>> import asyncio
>>> from aiogremlin import Cluster
>>> loop = asyncio.get_event_loop()
>>> cluster = await Cluster.open(loop, port=9430, aliases={'g': 'g'})
>>> remote_connection = await DriverRemoteConnection.using(cluster)

In the case that the DriverRemoteConnection is created with using, it is not necessary to close the DriverRemoteConnection, but the underlying Cluster must be closed:

>>> await cluster.close()

Configuration options are specified in the final section of this document.

DriverRemoteConnection is also an asynchronous context manager. It can be used as follows:

>>> async with remote_connection:
...     g = Graph().traversal().withRemote(remote_connection)
...     # traverse
# remote_connection is closed upon exit

Taking this one step further, the open can be awaited in the async context manager statement:

>>> async with await DriverRemoteConnection.open() as remote_connection:
...     g = Graph().traversal().withRemote(remote_connection)
...     # traverse
# remote connection is closed upon exit

Using the driver Module

aiogremlin also includes an asynchronous driver modeled after the official Gremlin-Python driver implementation. However, instead of using threads for asynchronous I/O, it uses an asyncio based implemenation.

To submit a raw Gremlin script to the server, use the Client. This class should not be instantiated directly, instead use a Cluster object:

>>> cluster = await Cluster.open(loop)
>>> client = await cluster.connect()
>>> result_set = await client.submit('g.V().hasLabel(x)', {'x': 'person'})

The ResultSet returned by Client implements the async interator protocol:

>>> async for v in result_set:
...     print(v)

It also provides a convenience method all that aggregates and returns the result of the script in a list:

>>> results = await result_set.all()

Closing the client will close the underlying cluster:

>>> await client.close()

Configuring the Cluster object

Configuration options can be set on Cluster in one of two ways, either passed as keyword arguments to Cluster, or stored in a configuration file and passed to the open using the kwarg configfile. Configuration files can be either YAML or JSON format. Currently, Cluster uses the following configuration:

Key Description Default
scheme URI scheme, typically ‘ws’ or ‘wss’ for secure websockets ‘ws’
hosts A list of hosts the cluster will connect to [‘localhost’]
port The port of the Gremlin Server to connect to, same for all hosts 8182
ssl_certfile File containing ssl certificate ‘’
ssl_keyfile File containing ssl key ‘’
ssl_password File containing password for ssl keyfile ‘’
username Username for Gremlin Server authentication ‘’
password Password for Gremlin Server authentication ‘’
response_timeout Timeout for reading responses from the stream None
max_conns The maximum number of connections open at any time to this host 4
min_conns The minimum number of connection open at any time to this host 1
max_times_acquired The maximum number of times a single pool connection can be acquired and shared 16
max_inflight The maximum number of unresolved messages that may be pending on any one connection 64
message_serializer String denoting the class used for message serialization, currently only supports basic GraphSONMessageSerializer ‘classpath’