A HTTP client for the Gremlin Server.


  • An easy to use client class GremlinRestClient that allows you to submit scripts to the Gremlin Server.
  • A a series of mid-level classes that all inherit from GremlinRestClient and Graph. These classes correspond to various Tinkerpop 3 vendor implementations and provide convenience methods for creating indices, schemas, etc.
  • The Create API, utilized by the Graph classes. Allows for easy programmatic creation of nodes and edges using Python dict and tuple.


The latest release of gremlinrestclient is 0.0.10.


  • Python 2.7-3.4
  • Tinkerpop 3 Gremlin Server 3.0.0 (3.0.0.M9 for use with Titan 0.9.0-M2)


  • requests >= 2.7.0


Install using pip:

$ pip install gremlinrestclient

Getting Started

Use the simple client: GremlinRestClient.

Minimal Example

Submit a script to the Gremlin Server:

>>> import gremlinrestclient
>>> client = gremlinrestclient.GremlinRestClient()
>>> resp = client.execute(
...     "graph.addVertex(label, p1, 'name', p2)",
...     bindings={"p1": "person", "p2": "dave"})
>>> resp
Response(status_code=200, data=[{u'properties': {u'name': [{u'id': 226,
u'value': u'dave'}]}, u'type': u'vertex', u'id': 225, u'label': u'person'}],
message={}, metadata=u'')

Create API

The Graph subclasses use the Create API to make the creation of nodes and edges easier. In the spirit of keeping it simple, nodes are dict objects. It is important to note that the key “label” always refers to the optional node label, and if the key “id” is passed it will be clobbered. If you need a property called “id”, consider using “_id” instead.

Consider the following example:

>>> graph = gremlinrestclient.TinkerGraph()
>>> d = {"name": "dave", "label": "person"}
>>> coll = graph.create(d)
>>> coll
        Vertex(id=227, label=u'person', properties={u'name': [{u'id': 228, u'value': u'dave'}]}),), edges=())
>>> vertex.vertices
(Vertex(id=227, label=u'person', properties={u'name': [{u'id': 228, u'value': u'dave'}]}),)

The create method returns a namedtuple called Collection. Collection contains two fields, vertices and edges, which are tuples of Vertex and Edge objects respectively. Lot’s of tuples.

To create edges, we use more tuple (not to be confused with the namedtuple Vertex). Observar:

>>> d = {"name": "dave", "label": "person"}
>>> p = {"name": "python", "label": "lang"}
>>> e = (d, "LIKES", p, {'weight': 1})
>>> graph.create(e)
        Vertex(id=248, label=u'person', properties={u'name': [{u'id': 249, u'value': u'dave'}]}),
        Vertex(id=250, label=u'lang', properties={u'name': [{u'id': 251, u'value': u'python'}]})),
        Edge(id=252, source_id=248, label=u'LIKES', target_id=250, properties={u'weight': 1}),))

Edge tuples are always the same (source, label, target, properties), but there are several ways to pass the source and target nodes to the tuple list. Instead of passing a node dictionary directly to an edge, you can pass the node dictionary as an argument, and pass its index to the edge tuple:

>>> p = {"name": "python", "label": "lang"}
>>> graph.create({"name": "dave", "label": "person"}, (0, "LIKES", p, {'weight': 1}))
        Vertex(id=229, label=u'person', properties={u'name': [{u'id': 230, u'value': u'dave'}]}),
        Vertex(id=231, label=u'lang', properties={u'name': [{u'id': 232, u'value': u'python'}]})),
        Edge(id=233, source_id=229, label=u'LIKES', target_id=231, properties={}),))

Here, the 0 in the edge tuple simple refers to the zeroith argument passed to the create() method.

Finally, you can pass a gremlinrestclient.graph.Vertex object (or two) to the edge tuple. Check:

>>> d = {"name": "dave", "label": "person"}
>>> coll = graph.create(d)
>>> dave, = coll.vertices  # Unpack tuple of length 1
>>> graph.create(
...     {"name": "python", "label": "lang"},
...     (dave, "LIKES", 0, {'weight': 1}))
        Vertex(id=261, label=u'lang', properties={u'name': [{u'id': 262, u'value': u'python'}]}),),
        Edge(id=263, source_id=259, label=u'LIKES', target_id=261, properties={u'weight': 1}),))

Note that only newly created nodes and edges are created in the collection.


Contributions are welcome. If you find a bug, or have a suggestion, please open an issue on Github. If you would like to make a pull request, please make sure to add appropriate tests and run them:

$ python test

In the future there will be CI and more info on contributing.


Indices and tables