apache tinkerpop logo

3.3.0

IO Reference

gremlin io2

IO features, capabilities and use cases are initially discussed in the TinkerPop Reference Documentation. This document focuses more on the details of the implementations for both production and consumption of the various formats. It contains samples of the various formats and development details that provide deeper insight for their usage.

GraphML

gremlin graphml The GraphML file format is a common XML-based representation of a graph. It uses an edge list format where vertices and their properties are listed and edges and their properties are listed by referencing the in and out vertices for each edge. GraphML does support a number of features which are not implemented by TinkerPop (e.g. extending GraphML with custom types) and there are features of TinkerPop that are not supported by GraphML (e.g. meta-properties), but GraphML does represent the most universal way to consume or produce a graph for integration with other systems as GraphML tends to have fairly wide support.

In TinkerPop, GraphML is also not extended for purpose of serializing just any type (i.e. serialize just a Vertex to XML). It is only supported for a Graph instance.

The following example is a representation of the Modern toy graph in GraphML:

<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.1/graphml.xsd">
  <key id="labelV" for="node" attr.name="labelV" attr.type="string" />
  <key id="name" for="node" attr.name="name" attr.type="string" />
  <key id="lang" for="node" attr.name="lang" attr.type="string" />
  <key id="age" for="node" attr.name="age" attr.type="int" />
  <key id="labelE" for="edge" attr.name="labelE" attr.type="string" />
  <key id="weight" for="edge" attr.name="weight" attr.type="double" />
  <graph id="G" edgedefault="directed">
    <node id="1">
      <data key="labelV">person</data>
      <data key="name">marko</data>
      <data key="age">29</data>
    </node>
    <node id="2">
      <data key="labelV">person</data>
      <data key="name">vadas</data>
      <data key="age">27</data>
    </node>
    <node id="3">
      <data key="labelV">software</data>
      <data key="name">lop</data>
      <data key="lang">java</data>
    </node>
    <node id="4">
      <data key="labelV">person</data>
      <data key="name">josh</data>
      <data key="age">32</data>
    </node>
    <node id="5">
      <data key="labelV">software</data>
      <data key="name">ripple</data>
      <data key="lang">java</data>
    </node>
    <node id="6">
      <data key="labelV">person</data>
      <data key="name">peter</data>
      <data key="age">35</data>
    </node>
    <edge id="7" source="1" target="2">
      <data key="labelE">knows</data>
      <data key="weight">0.5</data>
    </edge>
    <edge id="8" source="1" target="4">
      <data key="labelE">knows</data>
      <data key="weight">1.0</data>
    </edge>
    <edge id="9" source="1" target="3">
      <data key="labelE">created</data>
      <data key="weight">0.4</data>
    </edge>
    <edge id="10" source="4" target="5">
      <data key="labelE">created</data>
      <data key="weight">1.0</data>
    </edge>
    <edge id="11" source="4" target="3">
      <data key="labelE">created</data>
      <data key="weight">0.4</data>
    </edge>
    <edge id="12" source="6" target="3">
      <data key="labelE">created</data>
      <data key="weight">0.2</data>
    </edge>
  </graph>
</graphml>

Consider the following points when reading a GraphML file to TinkerPop that was generated outside of TinkerPop:

  • Supports the following values in attr.type:

    • string

    • float

    • double

    • int

    • long

    • boolean

  • Does not currently support the <default> tag in the schema definitions.

  • The GraphML will be read as a directed graph regardless of the value supplied edgedefault setting in the <graph> tag as that is the nature of the type of graph that TinkerPop supports.

  • The vertex and edge id values will always be treated as a String if the Graph instance consuming the data supports user-supplied identifiers (i.e. TinkerGraph).

  • By default the labels for vertex and edges are referred to as "labelV" and "labelE" respectively. It is possible to change these defaults on the Builder for the GraphReader. If no label is supplied, the reader will default to "vertex" and "edge" respectively as is the general expectation in TinkerPop when those values are omitted.

GraphSON

gremlin graphson GraphSON is a JSON-based format that is designed for human readable output that is easily supported in any programming language through the wide-array of JSON parsing libraries that exist on virtually all platforms. GraphSON is considered both a "graph" format and a generalized object serialization format. That characteristic makes it useful as a serialization format for Gremlin Server where arbitrary objects of varying types may be returned as results.

When considering GraphSON as a "graph" format, the relevant feature to consider is the writeGraph and readGraph methods on the GraphSONWriter and GraphSONReader interfaces, respectively. These methods write the entire Graph instance as output or read an entire Graph instance input and they do so in a way external to generalized object serialization. In other words, the output of:

final Graph graph = TinkerFactory.createModern();
final GraphWriter writer = graph.io(IoCore.graphson()).writer();
writer.writeGraph("tinkerpop-modern.json");

will be different of:

final Graph graph = TinkerFactory.createModern();
final GraphWriter writer = graph.io(IoCore.graphson()).writer();
final OutputStream os = new FileOutputStream("tinkerpop-modern.json");
writer.writeObject(os, graph);

Generalized object serialization will be discussed later in this section, so for now the focus will be on the "graph" format. Unlike GraphML, GraphSON does not use an edge list format. It uses an adjacency list. In the adjacency list, each vertex is essentially a line in the file and the vertex line contains a list of all the edges associated with that vertex. The GraphSON 2.0 representation looks like this for the Modern toy graph:

{"id":{"@type":"g:Int32","@value":1},"label":"person","outE":{"created":[{"id":{"@type":"g:Int32","@value":9},"inV":{"@type":"g:Int32","@value":3},"properties":{"weight":{"@type":"g:Double","@value":0.4}}}],"knows":[{"id":{"@type":"g:Int32","@value":7},"inV":{"@type":"g:Int32","@value":2},"properties":{"weight":{"@type":"g:Double","@value":0.5}}},{"id":{"@type":"g:Int32","@value":8},"inV":{"@type":"g:Int32","@value":4},"properties":{"weight":{"@type":"g:Double","@value":1.0}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":0},"value":"marko"}],"age":[{"id":{"@type":"g:Int64","@value":1},"value":{"@type":"g:Int32","@value":29}}]}}
{"id":{"@type":"g:Int32","@value":2},"label":"person","inE":{"knows":[{"id":{"@type":"g:Int32","@value":7},"outV":{"@type":"g:Int32","@value":1},"properties":{"weight":{"@type":"g:Double","@value":0.5}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":2},"value":"vadas"}],"age":[{"id":{"@type":"g:Int64","@value":3},"value":{"@type":"g:Int32","@value":27}}]}}
{"id":{"@type":"g:Int32","@value":3},"label":"software","inE":{"created":[{"id":{"@type":"g:Int32","@value":9},"outV":{"@type":"g:Int32","@value":1},"properties":{"weight":{"@type":"g:Double","@value":0.4}}},{"id":{"@type":"g:Int32","@value":11},"outV":{"@type":"g:Int32","@value":4},"properties":{"weight":{"@type":"g:Double","@value":0.4}}},{"id":{"@type":"g:Int32","@value":12},"outV":{"@type":"g:Int32","@value":6},"properties":{"weight":{"@type":"g:Double","@value":0.2}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":4},"value":"lop"}],"lang":[{"id":{"@type":"g:Int64","@value":5},"value":"java"}]}}
{"id":{"@type":"g:Int32","@value":4},"label":"person","inE":{"knows":[{"id":{"@type":"g:Int32","@value":8},"outV":{"@type":"g:Int32","@value":1},"properties":{"weight":{"@type":"g:Double","@value":1.0}}}]},"outE":{"created":[{"id":{"@type":"g:Int32","@value":10},"inV":{"@type":"g:Int32","@value":5},"properties":{"weight":{"@type":"g:Double","@value":1.0}}},{"id":{"@type":"g:Int32","@value":11},"inV":{"@type":"g:Int32","@value":3},"properties":{"weight":{"@type":"g:Double","@value":0.4}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":6},"value":"josh"}],"age":[{"id":{"@type":"g:Int64","@value":7},"value":{"@type":"g:Int32","@value":32}}]}}
{"id":{"@type":"g:Int32","@value":5},"label":"software","inE":{"created":[{"id":{"@type":"g:Int32","@value":10},"outV":{"@type":"g:Int32","@value":4},"properties":{"weight":{"@type":"g:Double","@value":1.0}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":8},"value":"ripple"}],"lang":[{"id":{"@type":"g:Int64","@value":9},"value":"java"}]}}
{"id":{"@type":"g:Int32","@value":6},"label":"person","outE":{"created":[{"id":{"@type":"g:Int32","@value":12},"inV":{"@type":"g:Int32","@value":3},"properties":{"weight":{"@type":"g:Double","@value":0.2}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":10},"value":"peter"}],"age":[{"id":{"@type":"g:Int64","@value":11},"value":{"@type":"g:Int32","@value":35}}]}}

At a glance, one can see that this is not a valid JSON document. While that may seem incorrect, there is a reason. The "graph" format is designed by default to be splittable, such that distributed systems like Spark can easily divide the a GraphSON file for processing. If this data were represented as an "array of vertices" with square brackets at the beginning and end of the file, the format would be less conducive to fit that purpose. It is possible to change this behavior by building the GraphSONWriter with the wrapAdjacencyList setting set to true, in which case the output will be a valid JSON document that looks like this:

{ "vertices": [
  {"id":{"@type":"g:Int32","@value":1},"label":"person","outE":{"created":[{"id":{"@type":"g:Int32","@value":9},"inV":{"@type":"g:Int32","@value":3},"properties":{"weight":{"@type":"g:Double","@value":0.4}}}],"knows":[{"id":{"@type":"g:Int32","@value":7},"inV":{"@type":"g:Int32","@value":2},"properties":{"weight":{"@type":"g:Double","@value":0.5}}},{"id":{"@type":"g:Int32","@value":8},"inV":{"@type":"g:Int32","@value":4},"properties":{"weight":{"@type":"g:Double","@value":1.0}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":0},"value":"marko"}],"age":[{"id":{"@type":"g:Int64","@value":1},"value":{"@type":"g:Int32","@value":29}}]}}
  {"id":{"@type":"g:Int32","@value":2},"label":"person","inE":{"knows":[{"id":{"@type":"g:Int32","@value":7},"outV":{"@type":"g:Int32","@value":1},"properties":{"weight":{"@type":"g:Double","@value":0.5}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":2},"value":"vadas"}],"age":[{"id":{"@type":"g:Int64","@value":3},"value":{"@type":"g:Int32","@value":27}}]}}
  {"id":{"@type":"g:Int32","@value":3},"label":"software","inE":{"created":[{"id":{"@type":"g:Int32","@value":9},"outV":{"@type":"g:Int32","@value":1},"properties":{"weight":{"@type":"g:Double","@value":0.4}}},{"id":{"@type":"g:Int32","@value":11},"outV":{"@type":"g:Int32","@value":4},"properties":{"weight":{"@type":"g:Double","@value":0.4}}},{"id":{"@type":"g:Int32","@value":12},"outV":{"@type":"g:Int32","@value":6},"properties":{"weight":{"@type":"g:Double","@value":0.2}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":4},"value":"lop"}],"lang":[{"id":{"@type":"g:Int64","@value":5},"value":"java"}]}}
  {"id":{"@type":"g:Int32","@value":4},"label":"person","inE":{"knows":[{"id":{"@type":"g:Int32","@value":8},"outV":{"@type":"g:Int32","@value":1},"properties":{"weight":{"@type":"g:Double","@value":1.0}}}]},"outE":{"created":[{"id":{"@type":"g:Int32","@value":10},"inV":{"@type":"g:Int32","@value":5},"properties":{"weight":{"@type":"g:Double","@value":1.0}}},{"id":{"@type":"g:Int32","@value":11},"inV":{"@type":"g:Int32","@value":3},"properties":{"weight":{"@type":"g:Double","@value":0.4}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":6},"value":"josh"}],"age":[{"id":{"@type":"g:Int64","@value":7},"value":{"@type":"g:Int32","@value":32}}]}}
  {"id":{"@type":"g:Int32","@value":5},"label":"software","inE":{"created":[{"id":{"@type":"g:Int32","@value":10},"outV":{"@type":"g:Int32","@value":4},"properties":{"weight":{"@type":"g:Double","@value":1.0}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":8},"value":"ripple"}],"lang":[{"id":{"@type":"g:Int64","@value":9},"value":"java"}]}}
  {"id":{"@type":"g:Int32","@value":6},"label":"person","outE":{"created":[{"id":{"@type":"g:Int32","@value":12},"inV":{"@type":"g:Int32","@value":3},"properties":{"weight":{"@type":"g:Double","@value":0.2}}}]},"properties":{"name":[{"id":{"@type":"g:Int64","@value":10},"value":"peter"}],"age":[{"id":{"@type":"g:Int64","@value":11},"value":{"@type":"g:Int32","@value":35}}]}}
]}
Note
The writeGraph method essentially calls writeVertices with the directionality of BOTH. The writeVertices method simply calls writeVertex which detaches each Vertex instance into a directional StarGraph which forms the basis for the format.

The following sections discuss the GraphSON object serialization format as available in each version of GraphSON. Core to understanding these sections is to understand that GraphSON can be produced with and without types being embedded in the output. Without embedded types, the type system is restricted to standard JSON types of Object, List, String, Number, Boolean and that will lead to "lossyness" in the format (i.e. a float will be interpreted as double).

Version 1.0

Version 1.0 of GraphSON was released with TinkerPop 3.0.0. When types are embedded, GraphSON uses the standard Jackson type embedding approach that writes the full Java class name into a "@class" field in the JSON. While this approach isn’t especially language agnostic it does at least give some hint as to what the expected type is.

This section focuses on non-embedded types and their formats as there was little usage of embedded types in generalized object serialization use cases. The format was simply too cumbersome to parse of non-Jackson enabled libraries and the use cases for it were limited. GraphSON Version 2.0 attempts to improve upon this limitation.

Graph Structure

Edge

{
  "id" : 13,
  "label" : "develops",
  "type" : "edge",
  "inVLabel" : "software",
  "outVLabel" : "person",
  "inV" : 10,
  "outV" : 1,
  "properties" : {
    "since" : 2009
  }
}

Path

{
  "labels" : [ [ ], [ ], [ ] ],
  "objects" : [ {
    "id" : 1,
    "label" : "person",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 0,
        "value" : "marko"
      } ],
      "location" : [ {
        "id" : 6,
        "value" : "san diego",
        "properties" : {
          "startTime" : 1997,
          "endTime" : 2001
        }
      }, {
        "id" : 7,
        "value" : "santa cruz",
        "properties" : {
          "startTime" : 2001,
          "endTime" : 2004
        }
      }, {
        "id" : 8,
        "value" : "brussels",
        "properties" : {
          "startTime" : 2004,
          "endTime" : 2005
        }
      }, {
        "id" : 9,
        "value" : "santa fe",
        "properties" : {
          "startTime" : 2005
        }
      } ]
    }
  }, {
    "id" : 10,
    "label" : "software",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 4,
        "value" : "gremlin"
      } ]
    }
  }, {
    "id" : 11,
    "label" : "software",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 5,
        "value" : "tinkergraph"
      } ]
    }
  } ]
}

Property

{
  "key" : "since",
  "value" : 2009
}

TinkerGraph

TinkerGraph has a custom serializer that is registered as part of the TinkerIoRegistry.

{
  "vertices" : [ {
    "id" : 1,
    "label" : "person",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 0,
        "value" : "marko"
      } ],
      "location" : [ {
        "id" : 6,
        "value" : "san diego",
        "properties" : {
          "startTime" : 1997,
          "endTime" : 2001
        }
      }, {
        "id" : 7,
        "value" : "santa cruz",
        "properties" : {
          "startTime" : 2001,
          "endTime" : 2004
        }
      }, {
        "id" : 8,
        "value" : "brussels",
        "properties" : {
          "startTime" : 2004,
          "endTime" : 2005
        }
      }, {
        "id" : 9,
        "value" : "santa fe",
        "properties" : {
          "startTime" : 2005
        }
      } ]
    }
  }, {
    "id" : 7,
    "label" : "person",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 1,
        "value" : "stephen"
      } ],
      "location" : [ {
        "id" : 10,
        "value" : "centreville",
        "properties" : {
          "startTime" : 1990,
          "endTime" : 2000
        }
      }, {
        "id" : 11,
        "value" : "dulles",
        "properties" : {
          "startTime" : 2000,
          "endTime" : 2006
        }
      }, {
        "id" : 12,
        "value" : "purcellville",
        "properties" : {
          "startTime" : 2006
        }
      } ]
    }
  }, {
    "id" : 8,
    "label" : "person",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 2,
        "value" : "matthias"
      } ],
      "location" : [ {
        "id" : 13,
        "value" : "bremen",
        "properties" : {
          "startTime" : 2004,
          "endTime" : 2007
        }
      }, {
        "id" : 14,
        "value" : "baltimore",
        "properties" : {
          "startTime" : 2007,
          "endTime" : 2011
        }
      }, {
        "id" : 15,
        "value" : "oakland",
        "properties" : {
          "startTime" : 2011,
          "endTime" : 2014
        }
      }, {
        "id" : 16,
        "value" : "seattle",
        "properties" : {
          "startTime" : 2014
        }
      } ]
    }
  }, {
    "id" : 9,
    "label" : "person",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 3,
        "value" : "daniel"
      } ],
      "location" : [ {
        "id" : 17,
        "value" : "spremberg",
        "properties" : {
          "startTime" : 1982,
          "endTime" : 2005
        }
      }, {
        "id" : 18,
        "value" : "kaiserslautern",
        "properties" : {
          "startTime" : 2005,
          "endTime" : 2009
        }
      }, {
        "id" : 19,
        "value" : "aachen",
        "properties" : {
          "startTime" : 2009
        }
      } ]
    }
  }, {
    "id" : 10,
    "label" : "software",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 4,
        "value" : "gremlin"
      } ]
    }
  }, {
    "id" : 11,
    "label" : "software",
    "type" : "vertex",
    "properties" : {
      "name" : [ {
        "id" : 5,
        "value" : "tinkergraph"
      } ]
    }
  } ],
  "edges" : [ {
    "id" : 13,
    "label" : "develops",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 10,
    "outV" : 1,
    "properties" : {
      "since" : 2009
    }
  }, {
    "id" : 14,
    "label" : "develops",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 11,
    "outV" : 1,
    "properties" : {
      "since" : 2010
    }
  }, {
    "id" : 15,
    "label" : "uses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 10,
    "outV" : 1,
    "properties" : {
      "skill" : 4
    }
  }, {
    "id" : 16,
    "label" : "uses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 11,
    "outV" : 1,
    "properties" : {
      "skill" : 5
    }
  }, {
    "id" : 17,
    "label" : "develops",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 10,
    "outV" : 7,
    "properties" : {
      "since" : 2010
    }
  }, {
    "id" : 18,
    "label" : "develops",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 11,
    "outV" : 7,
    "properties" : {
      "since" : 2011
    }
  }, {
    "id" : 19,
    "label" : "uses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 10,
    "outV" : 7,
    "properties" : {
      "skill" : 5
    }
  }, {
    "id" : 20,
    "label" : "uses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 11,
    "outV" : 7,
    "properties" : {
      "skill" : 4
    }
  }, {
    "id" : 21,
    "label" : "develops",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 10,
    "outV" : 8,
    "properties" : {
      "since" : 2012
    }
  }, {
    "id" : 22,
    "label" : "uses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 10,
    "outV" : 8,
    "properties" : {
      "skill" : 3
    }
  }, {
    "id" : 23,
    "label" : "uses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 11,
    "outV" : 8,
    "properties" : {
      "skill" : 3
    }
  }, {
    "id" : 24,
    "label" : "uses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 10,
    "outV" : 9,
    "properties" : {
      "skill" : 5
    }
  }, {
    "id" : 25,
    "label" : "uses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : 11,
    "outV" : 9,
    "properties" : {
      "skill" : 3
    }
  }, {
    "id" : 26,
    "label" : "traverses",
    "type" : "edge",
    "inVLabel" : "software",
    "outVLabel" : "software",
    "inV" : 11,
    "outV" : 10
  } ]
}

Vertex

{
  "id" : 1,
  "label" : "person",
  "type" : "vertex",
  "properties" : {
    "name" : [ {
      "id" : 0,
      "value" : "marko"
    } ],
    "location" : [ {
      "id" : 6,
      "value" : "san diego",
      "properties" : {
        "startTime" : 1997,
        "endTime" : 2001
      }
    }, {
      "id" : 7,
      "value" : "santa cruz",
      "properties" : {
        "startTime" : 2001,
        "endTime" : 2004
      }
    }, {
      "id" : 8,
      "value" : "brussels",
      "properties" : {
        "startTime" : 2004,
        "endTime" : 2005
      }
    }, {
      "id" : 9,
      "value" : "santa fe",
      "properties" : {
        "startTime" : 2005
      }
    } ]
  }
}

VertexProperty

{
  "id" : 0,
  "value" : "marko",
  "label" : "name"
}

RequestMessage

Authentication Response

The following RequestMessage is an example of the response that should be made to a SASL-based authentication challenge.

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "authentication",
  "processor" : "",
  "args" : {
    "saslMechanism" : "PLAIN",
    "sasl" : "AHN0ZXBocGhlbgBwYXNzd29yZA=="
  }
}

Session Eval

The following RequestMessage is an example of a simple session request for a script evaluation with parameters.

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "eval",
  "processor" : "session",
  "args" : {
    "gremlin" : "g.V(x)",
    "language" : "gremlin-groovy",
    "session" : "41d2e28a-20a4-4ab0-b379-d810dede3786",
    "bindings" : {
      "x" : 1
    }
  }
}

Session Eval Aliased

The following RequestMessage is an example of a session request for a script evaluation with an alias that binds the TraversalSource of "g" to "social".

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "eval",
  "processor" : "session",
  "args" : {
    "gremlin" : "social.V(x)",
    "language" : "gremlin-groovy",
    "aliases" : {
      "g" : "social"
    },
    "session" : "41d2e28a-20a4-4ab0-b379-d810dede3786",
    "bindings" : {
      "x" : 1
    }
  }
}

Session Close

The following RequestMessage is an example of a request to close a session.

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "close",
  "processor" : "session",
  "args" : {
    "session" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
  }
}

Sessionless Eval

The following RequestMessage is an example of a simple sessionless request for a script evaluation with parameters.

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "eval",
  "processor" : "",
  "args" : {
    "gremlin" : "g.V(x)",
    "language" : "gremlin-groovy",
    "bindings" : {
      "x" : 1
    }
  }
}

Sessionless Eval Aliased

The following RequestMessage is an example of a sessionless request for a script evaluation with an alias that binds the TraversalSource of "g" to "social".

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "eval",
  "processor" : "",
  "args" : {
    "gremlin" : "social.V(x)",
    "language" : "gremlin-groovy",
    "aliases" : {
      "g" : "social"
    },
    "bindings" : {
      "x" : 1
    }
  }
}

ResponseMessage

Authentication Challenge

When authentication is enabled, an initial request to the server will result in an authentication challenge. The typical response message will appear as follows, but handling it could be different dependending on the SASL implementation (e.g. multiple challenges maybe requested in some cases, but not in the default provided by Gremlin Server).

{
  "requestId" : "41d2e28a-20a4-4ab0-b379-d810dede3786",
  "status" : {
    "message" : "",
    "code" : 407,
    "attributes" : { }
  },
  "result" : {
    "data" : null,
    "meta" : { }
  }
}

Standard Result

The following ResponseMessage is a typical example of the typical successful response Gremlin Server will return when returning results from a script.

{
  "requestId" : "41d2e28a-20a4-4ab0-b379-d810dede3786",
  "status" : {
    "message" : "",
    "code" : 200,
    "attributes" : { }
  },
  "result" : {
    "data" : [ {
      "id" : 1,
      "label" : "person",
      "type" : "vertex",
      "properties" : {
        "name" : [ {
          "id" : 0,
          "value" : "marko"
        } ],
        "location" : [ {
          "id" : 6,
          "value" : "san diego",
          "properties" : {
            "startTime" : 1997,
            "endTime" : 2001
          }
        }, {
          "id" : 7,
          "value" : "santa cruz",
          "properties" : {
            "startTime" : 2001,
            "endTime" : 2004
          }
        }, {
          "id" : 8,
          "value" : "brussels",
          "properties" : {
            "startTime" : 2004,
            "endTime" : 2005
          }
        }, {
          "id" : 9,
          "value" : "santa fe",
          "properties" : {
            "startTime" : 2005
          }
        } ]
      }
    } ],
    "meta" : { }
  }
}

Version 2.0

Version 2.0 of GraphSON was first introduced on TinkerPop 3.2.2. It was designed to be less tied to Jackson (a JVM library) and to be less lossy as it pertained to types. While the GraphSON 1.0 section focused on GraphSON without embedded types, GraphSON 2.0 will do the opposite as embedded types is the expected manner in which non-JVM languages will interact with TinkerPop.

With GraphSON 2.0, there are essentially two type formats:

  • A non-typed value which is assumed the type implied by JSON. These non-types are limited to String, Boolean, Map and Collection.

  • All other values are typed by way of a "complex object" that defines a @typeId and @value. The @typeId is composed of two parts: a namespace and a type name, in the format "namespace:typename". A namespace allows TinkerPop providers and users to categorize custom types that they may implement and avoid collision with existing TinkerPop types. By default, TinkerPop types will have the namespace "g" (or "gx" for "extended" types).

Core

Class

{
  "@type" : "g:Class",
  "@value" : "java.io.File"
}

Date

{
  "@type" : "g:Date",
  "@value" : 1481750076295
}

Double

{
  "@type" : "g:Double",
  "@value" : 100.0
}

Float

{
  "@type" : "g:Float",
  "@value" : 100.0
}

Integer

{
  "@type" : "g:Int32",
  "@value" : 100
}

Long

{
  "@type" : "g:Int64",
  "@value" : 100
}

Timestamp

{
  "@type" : "g:Timestamp",
  "@value" : 1481750076295
}

UUID

{
  "@type" : "g:UUID",
  "@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
}

Graph Structure

Edge

{
  "@type" : "g:Edge",
  "@value" : {
    "id" : {
      "@type" : "g:Int32",
      "@value" : 13
    },
    "label" : "develops",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : {
      "@type" : "g:Int32",
      "@value" : 10
    },
    "outV" : {
      "@type" : "g:Int32",
      "@value" : 1
    },
    "properties" : {
      "since" : {
        "@type" : "g:Int32",
        "@value" : 2009
      }
    }
  }
}

Path

{
  "@type" : "g:Path",
  "@value" : {
    "labels" : [ [ ], [ ], [ ] ],
    "objects" : [ {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person"
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "label" : "software"
        "label" : "software",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 4
              },
              "value" : "gremlin",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 10
              },
              "label" : "name"
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "label" : "software"
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 5
              },
              "value" : "tinkergraph",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 11
              },
              "label" : "name"
            }
          } ]
        }
      }
    } ]
  }
}

Property

{
  "@type" : "g:Property",
  "@value" : {
    "key" : "since",
    "value" : {
      "@type" : "g:Int32",
      "@value" : 2009
    },
    "element" : {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 13
        },
        "label" : "develops",
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        }
      }
    }
  }
}

StarGraph

{
  "starVertex" : {
    "@type" : "g:Vertex",
    "@value" : {
      "id" : {
        "@type" : "g:Int32",
        "@value" : 1
      },
      "label" : "person",
      "properties" : {
        "name" : [ {
          "@type" : "g:VertexProperty",
          "@value" : {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 0
            },
            "value" : "marko",
            "vertex" : {
              "@type" : "g:Int32",
              "@value" : 1
            },
            "label" : "name"
          }
        } ],
        "location" : [ {
          "@type" : "g:VertexProperty",
          "@value" : {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 6
            },
            "value" : "san diego",
            "vertex" : {
              "@type" : "g:Int32",
              "@value" : 1
            },
            "label" : "location",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 1997
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              }
            }
          }
        }, {
          "@type" : "g:VertexProperty",
          "@value" : {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 7
            },
            "value" : "santa cruz",
            "vertex" : {
              "@type" : "g:Int32",
              "@value" : 1
            },
            "label" : "location",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              }
            }
          }
        }, {
          "@type" : "g:VertexProperty",
          "@value" : {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 8
            },
            "value" : "brussels",
            "vertex" : {
              "@type" : "g:Int32",
              "@value" : 1
            },
            "label" : "location",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          }
        }, {
          "@type" : "g:VertexProperty",
          "@value" : {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 9
            },
            "value" : "santa fe",
            "vertex" : {
              "@type" : "g:Int32",
              "@value" : 1
            },
            "label" : "location",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          }
        } ]
      }
    }
  }
}

TinkerGraph

TinkerGraph has a custom serializer that is registered as part of the TinkerIoRegistry.

{
  "@type" : "tinker:graph",
  "@value" : {
    "vertices" : [ {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 0
              },
              "value" : "marko",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "name"
            }
          } ],
          "location" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 6
              },
              "value" : "san diego",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 1997
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2001
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 7
              },
              "value" : "santa cruz",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2001
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 8
              },
              "value" : "brussels",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 9
              },
              "value" : "santa fe",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 1
              },
              "value" : "stephen",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 7
              },
              "label" : "name"
            }
          } ],
          "location" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 10
              },
              "value" : "centreville",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 7
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 1990
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2000
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 11
              },
              "value" : "dulles",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 7
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2000
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2006
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 12
              },
              "value" : "purcellville",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 7
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2006
                }
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 8
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 2
              },
              "value" : "matthias",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 8
              },
              "label" : "name"
            }
          } ],
          "location" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 13
              },
              "value" : "bremen",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 8
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2007
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 14
              },
              "value" : "baltimore",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 8
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2007
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2011
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 15
              },
              "value" : "oakland",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 8
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2011
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2014
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 16
              },
              "value" : "seattle",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 8
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2014
                }
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 9
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 3
              },
              "value" : "daniel",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 9
              },
              "label" : "name"
            }
          } ],
          "location" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 17
              },
              "value" : "spremberg",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 9
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 1982
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 18
              },
              "value" : "kaiserslautern",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 9
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2009
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 19
              },
              "value" : "aachen",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 9
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2009
                }
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "label" : "software",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 4
              },
              "value" : "gremlin",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 10
              },
              "label" : "name"
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "label" : "software",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 5
              },
              "value" : "tinkergraph",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 11
              },
              "label" : "name"
            }
          } ]
        }
      }
    } ],
    "edges" : [ {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 13
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2009
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 14
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2010
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 15
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 4
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 16
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 5
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 17
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2010
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 18
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2011
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 19
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 5
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 20
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 4
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 21
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 8
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2012
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 22
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 8
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 3
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 23
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 8
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 3
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 24
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 9
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 5
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 25
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 9
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 3
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 26
        },
        "label" : "traverses",
        "inVLabel" : "software",
        "outVLabel" : "software",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 10
        }
      }
    } ]
  }
}

Tree

{
  "@type" : "g:Tree",
  "@value" : [ {
    "key" : {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 0
              },
              "value" : "marko",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "name"
            }
          } ],
          "location" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 6
              },
              "value" : "san diego",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 1997
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2001
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 7
              },
              "value" : "santa cruz",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2001
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 8
              },
              "value" : "brussels",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 9
              },
              "value" : "santa fe",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          } ]
        }
      }
    },
    "value" : {
      "@type" : "g:Tree",
      "@value" : [ {
        "key" : {
          "@type" : "g:Vertex",
          "@value" : {
            "id" : {
              "@type" : "g:Int32",
              "@value" : 10
            },
            "label" : "software",
            "properties" : {
              "name" : [ {
                "@type" : "g:VertexProperty",
                "@value" : {
                  "id" : {
                    "@type" : "g:Int64",
                    "@value" : 4
                  },
                  "value" : "gremlin",
                  "vertex" : {
                    "@type" : "g:Int32",
                    "@value" : 10
                  },
                  "label" : "name"
                }
              } ]
            }
          }
        },
        "value" : {
          "@type" : "g:Tree",
          "@value" : [ {
            "key" : {
              "@type" : "g:Vertex",
              "@value" : {
                "id" : {
                  "@type" : "g:Int32",
                  "@value" : 11
                },
                "label" : "software",
                "properties" : {
                  "name" : [ {
                    "@type" : "g:VertexProperty",
                    "@value" : {
                      "id" : {
                        "@type" : "g:Int64",
                        "@value" : 5
                      },
                      "value" : "tinkergraph",
                      "vertex" : {
                        "@type" : "g:Int32",
                        "@value" : 11
                      },
                      "label" : "name"
                    }
                  } ]
                }
              }
            },
            "value" : {
              "@type" : "g:Tree",
              "@value" : [ ]
            }
          } ]
        }
      } ]
    }
  } ]
}

Vertex

{
  "@type" : "g:Vertex",
  "@value" : {
    "id" : {
      "@type" : "g:Int32",
      "@value" : 1
    },
    "label" : "person",
    "properties" : {
      "name" : [ {
        "@type" : "g:VertexProperty",
        "@value" : {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 0
          },
          "value" : "marko",
          "vertex" : {
            "@type" : "g:Int32",
            "@value" : 1
          },
          "label" : "name"
        }
      } ],
      "location" : [ {
        "@type" : "g:VertexProperty",
        "@value" : {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 6
          },
          "value" : "san diego",
          "vertex" : {
            "@type" : "g:Int32",
            "@value" : 1
          },
          "label" : "location",
          "properties" : {
            "startTime" : {
              "@type" : "g:Int32",
              "@value" : 1997
            },
            "endTime" : {
              "@type" : "g:Int32",
              "@value" : 2001
            }
          }
        }
      }, {
        "@type" : "g:VertexProperty",
        "@value" : {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 7
          },
          "value" : "santa cruz",
          "vertex" : {
            "@type" : "g:Int32",
            "@value" : 1
          },
          "label" : "location",
          "properties" : {
            "startTime" : {
              "@type" : "g:Int32",
              "@value" : 2001
            },
            "endTime" : {
              "@type" : "g:Int32",
              "@value" : 2004
            }
          }
        }
      }, {
        "@type" : "g:VertexProperty",
        "@value" : {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 8
          },
          "value" : "brussels",
          "vertex" : {
            "@type" : "g:Int32",
            "@value" : 1
          },
          "label" : "location",
          "properties" : {
            "startTime" : {
              "@type" : "g:Int32",
              "@value" : 2004
            },
            "endTime" : {
              "@type" : "g:Int32",
              "@value" : 2005
            }
          }
        }
      }, {
        "@type" : "g:VertexProperty",
        "@value" : {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 9
          },
          "value" : "santa fe",
          "vertex" : {
            "@type" : "g:Int32",
            "@value" : 1
          },
          "label" : "location",
          "properties" : {
            "startTime" : {
              "@type" : "g:Int32",
              "@value" : 2005
            }
          }
        }
      } ]
    }
  }
}

VertexProperty

{
  "@type" : "g:VertexProperty",
  "@value" : {
    "id" : {
      "@type" : "g:Int64",
      "@value" : 0
    },
    "value" : "marko",
    "vertex" : {
      "@type" : "g:Int32",
      "@value" : 1
    },
    "label" : "name"
  }
}

Graph Process

Barrier

{
  "@type" : "g:Barrier",
  "@value" : "normSack"
}

Binding

A "Binding" refers to a Bytecode.Binding.

{
  "@type" : "g:Binding",
  "@value" : {
    "key" : "x",
    "value" : {
      "@type" : "g:Int32",
      "@value" : 1
    }
  }
}

Bytecode

The following Bytecode example represents the traversal of g.V().hasLabel('person').out().in().tree(). Obviously the serialized Bytecode woudl be quite different for the endless variations of commands that could be used together in the Gremlin language.

{
  "@type" : "g:Bytecode",
  "@value" : {
    "step" : [ [ "V" ], [ "hasLabel", "person" ], [ "out" ], [ "in" ], [ "tree" ] ]
  }
}

Cardinality

{
  "@type" : "g:Cardinality",
  "@value" : "list"
}

Column

{
  "@type" : "g:Column",
  "@value" : "keys"
}

Direction

{
  "@type" : "g:Direction",
  "@value" : "OUT"
}

Operator

{
  "@type" : "g:Operator",
  "@value" : "sum"
}

Order

{
  "@type" : "g:Order",
  "@value" : "incr"
}

Pick

{
  "@type" : "g:Pick",
  "@value" : "any"
}

Pop

{
  "@type" : "g:Pop",
  "@value" : "all"
}

Lambda

{
  "@type" : "g:Lambda",
  "@value" : {
    "script" : "{ it.get() }",
    "language" : "gremlin-groovy",
    "arguments" : 1
  }
}

Metrics

{
  "@type" : "g:Metrics",
  "@value" : {
    "dur" : {
      "@type" : "g:Double",
      "@value" : 100.0
    },
    "counts" : {
      "traverserCount" : {
        "@type" : "g:Int64",
        "@value" : 4
      },
      "elementCount" : {
        "@type" : "g:Int64",
        "@value" : 4
      }
    },
    "name" : "TinkerGraphStep(vertex,[~label.eq(person)])",
    "annotations" : {
      "percentDur" : {
        "@type" : "g:Double",
        "@value" : 25.0
      }
    },
    "id" : "7.0.0()",
    "metrics" : [ {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 7
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 7
          }
        },
        "name" : "VertexStep(OUT,vertex)",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "3.0.0()"
      }
    } ]
  }
}

P

{
  "@type" : "g:P",
  "@value" : {
    "predicate" : "gt",
    "value" : {
      "@type" : "g:Int32",
      "@value" : 0
    }
  }
}

P and

{
  "@type" : "g:P",
  "@value" : {
    "predicate" : "and",
    "value" : [ {
      "@type" : "g:P",
      "@value" : {
        "predicate" : "gt",
        "value" : {
          "@type" : "g:Int32",
          "@value" : 0
        }
      }
    }, {
      "@type" : "g:P",
      "@value" : {
        "predicate" : "lt",
        "value" : {
          "@type" : "g:Int32",
          "@value" : 10
        }
      }
    } ]
  }
}

P or

{
  "@type" : "g:P",
  "@value" : {
    "predicate" : "or",
    "value" : [ {
      "@type" : "g:P",
      "@value" : {
        "predicate" : "gt",
        "value" : {
          "@type" : "g:Int32",
          "@value" : 0
        }
      }
    }, {
      "@type" : "g:P",
      "@value" : {
        "predicate" : "within",
        "value" : [ {
          "@type" : "g:Int32",
          "@value" : -1
        }, {
          "@type" : "g:Int32",
          "@value" : -10
        }, {
          "@type" : "g:Int32",
          "@value" : -100
        } ]
      }
    } ]
  }
}

Scope

{
  "@type" : "g:Scope",
  "@value" : "local"
}

T

{
  "@type" : "g:T",
  "@value" : "label"
}

TraversalMetrics

{
  "@type" : "g:TraversalMetrics",
  "@value" : {
    "dur" : {
      "@type" : "g:Double",
      "@value" : 0.004
    },
    "metrics" : [ {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 4
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 4
          }
        },
        "name" : "TinkerGraphStep(vertex,[~label.eq(person)])",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "7.0.0()"
      }
    }, {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 13
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 13
          }
        },
        "name" : "VertexStep(OUT,vertex)",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "2.0.0()"
      }
    }, {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 7
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 7
          }
        },
        "name" : "VertexStep(OUT,vertex)",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "3.0.0()"
      }
    }, {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 1
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 1
          }
        },
        "name" : "TreeStep",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "4.0.0()"
      }
    } ]
  }
}

Traverser

{
  "@type" : "g:Traverser",
  "@value" : {
    "bulk" : {
      "@type" : "g:Int64",
      "@value" : 1
    },
    "value" : {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 0
              },
              "value" : "marko",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "name"
            }
          } ],
          "location" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 6
              },
              "value" : "san diego",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 1997
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2001
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 7
              },
              "value" : "santa cruz",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2001
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 8
              },
              "value" : "brussels",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 9
              },
              "value" : "santa fe",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          } ]
        }
      }
    }
  }
}

RequestMessage

Authentication Response

The following RequestMessage is an example of the response that should be made to a SASL-based authentication challenge.

{
  "requestId" : {
    "@type" : "g:UUID",
    "@value" : "cb682578-9d92-4499-9ebc-5c6aa73c5397"
  },
  "op" : "authentication",
  "processor" : "",
  "args" : {
    "saslMechanism" : "PLAIN",
    "sasl" : "AHN0ZXBocGhlbgBwYXNzd29yZA=="
  }
}

Session Eval

The following RequestMessage is an example of a simple session request for a script evaluation with parameters.

{
  "requestId" : {
    "@type" : "g:UUID",
    "@value" : "cb682578-9d92-4499-9ebc-5c6aa73c5397"
  },
  "op" : "eval",
  "processor" : "session",
  "args" : {
    "gremlin" : "g.V(x)",
    "language" : "gremlin-groovy",
    "session" : {
      "@type" : "g:UUID",
      "@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
    },
    "bindings" : {
      "x" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

Session Eval Aliased

The following RequestMessage is an example of a session request for a script evaluation with an alias that binds the TraversalSource of "g" to "social".

{
  "requestId" : {
    "@type" : "g:UUID",
    "@value" : "cb682578-9d92-4499-9ebc-5c6aa73c5397"
  },
  "op" : "eval",
  "processor" : "session",
  "args" : {
    "gremlin" : "social.V(x)",
    "language" : "gremlin-groovy",
    "aliases" : {
      "g" : "social"
    },
    "session" : {
      "@type" : "g:UUID",
      "@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
    },
    "bindings" : {
      "x" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

Session Close

The following RequestMessage is an example of a request to close a session.

{
  "requestId" : {
    "@type" : "g:UUID",
    "@value" : "cb682578-9d92-4499-9ebc-5c6aa73c5397"
  },
  "op" : "close",
  "processor" : "session",
  "args" : {
    "session" : {
      "@type" : "g:UUID",
      "@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
    }
  }
}

Sessionless Eval

The following RequestMessage is an example of a simple sessionless request for a script evaluation with parameters.

{
  "requestId" : {
    "@type" : "g:UUID",
    "@value" : "cb682578-9d92-4499-9ebc-5c6aa73c5397"
  },
  "op" : "eval",
  "processor" : "",
  "args" : {
    "gremlin" : "g.V(x)",
    "language" : "gremlin-groovy",
    "bindings" : {
      "x" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

Sessionless Eval Aliased

The following RequestMessage is an example of a sessionless request for a script evaluation with an alias that binds the TraversalSource of "g" to "social".

{
  "requestId" : {
    "@type" : "g:UUID",
    "@value" : "cb682578-9d92-4499-9ebc-5c6aa73c5397"
  },
  "op" : "eval",
  "processor" : "",
  "args" : {
    "gremlin" : "social.V(x)",
    "language" : "gremlin-groovy",
    "aliases" : {
      "g" : "social"
    },
    "bindings" : {
      "x" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

ResponseMessage

Authentication Challenge

When authentication is enabled, an initial request to the server will result in an authentication challenge. The typical response message will appear as follows, but handling it could be different dependending on the SASL implementation (e.g. multiple challenges maybe requested in some cases, but not in the default provided by Gremlin Server).

{
  "requestId" : "41d2e28a-20a4-4ab0-b379-d810dede3786",
  "status" : {
    "message" : "",
    "code" : 407,
    "attributes" : { }
  },
  "result" : {
    "data" : null,
    "meta" : { }
  }
}

Standard Result

The following ResponseMessage is a typical example of the typical successful response Gremlin Server will return when returning results from a script.

{
  "requestId" : "41d2e28a-20a4-4ab0-b379-d810dede3786",
  "status" : {
    "message" : "",
    "code" : 200,
    "attributes" : { }
  },
  "result" : {
    "data" : [ {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 0
              },
              "value" : "marko",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "name"
            }
          } ],
          "location" : [ {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 6
              },
              "value" : "san diego",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 1997
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2001
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 7
              },
              "value" : "santa cruz",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2001
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 8
              },
              "value" : "brussels",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2004
                },
                "endTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          }, {
            "@type" : "g:VertexProperty",
            "@value" : {
              "id" : {
                "@type" : "g:Int64",
                "@value" : 9
              },
              "value" : "santa fe",
              "vertex" : {
                "@type" : "g:Int32",
                "@value" : 1
              },
              "label" : "location",
              "properties" : {
                "startTime" : {
                  "@type" : "g:Int32",
                  "@value" : 2005
                }
              }
            }
          } ]
        }
      }
    } ],
    "meta" : { }
  }
}

Extended

Note that the "extended" types require the addition of the separate GraphSONXModuleV2d0 module as follows:

mapper = GraphSONMapper.build().
                        typeInfo(TypeInfo.PARTIAL_TYPES).
                        addCustomModule(GraphSONXModuleV2d0.build().create(false)).
                        version(GraphSONVersion.V2_0).create().createMapper()

BigDecimal

{
  "@type" : "gx:BigDecimal",
  "@value" : 123456789987654321123456789987654321
}

BigInteger

{
  "@type" : "gx:BigInteger",
  "@value" : 123456789987654321123456789987654321
}

Byte

{
  "@type" : "gx:Byte",
  "@value" : 1
}

ByteBuffer

{
  "@type" : "gx:ByteBuffer",
  "@value" : "c29tZSBieXRlcyBmb3IgeW91"
}

Char

{
  "@type" : "gx:Char",
  "@value" : "x"
}

Duration

The following example is a Duration of five days.

{
  "@type" : "gx:Duration",
  "@value" : "PT120H"
}

InetAddress

{
  "@type" : "gx:InetAddress",
  "@value" : "localhost"
}

Instant

{
  "@type" : "gx:Instant",
  "@value" : "2016-12-14T16:39:19.349Z"
}

LocalDate

{
  "@type" : "gx:LocalDate",
  "@value" : "2016-01-01"
}

LocalDateTime

{
  "@type" : "gx:LocalDateTime",
  "@value" : "2016-01-01T12:30"
}

LocalTime

{
  "@type" : "gx:LocalTime",
  "@value" : "12:30:45"
}

MonthDay

{
  "@type" : "gx:MonthDay",
  "@value" : "--01-01"
}

OffsetDateTime

{
  "@type" : "gx:OffsetDateTime",
  "@value" : "2007-12-03T10:15:30+01:00"
}

OffsetTime

{
  "@type" : "gx:OffsetTime",
  "@value" : "10:15:30+01:00"
}

Period

The following example is a Period of one year, six months and fifteen days.

{
  "@type" : "gx:Period",
  "@value" : "P1Y6M15D"
}

Short

{
  "@type" : "gx:Int16",
  "@value" : 100
}

Year

The following example is of the Year "2016".

{
  "@type" : "gx:Year",
  "@value" : "2016"
}

YearMonth

The following example is a YearMonth of "June 2016"

{
  "@type" : "gx:YearMonth",
  "@value" : "2016-06"
}

ZonedDateTime

{
  "@type" : "gx:ZonedDateTime",
  "@value" : "2016-12-23T12:12:24.000000036+02:00[GMT+02:00]"
}

ZoneOffset

The following example is a ZoneOffset of three hours, six minutes, and nine seconds.

{
  "@type" : "gx:ZoneOffset",
  "@value" : "+03:06:09"
}

Version 3.0

Version 3.0 of GraphSON was first introduced on TinkerPop 3.3.0. It is quite similar to GraphSON 2.0 in many ways in terms of features, but it does not have an "untyped" version as previous version of GraphSON had.

Core

Class

{
  "@type" : "g:Class",
  "@value" : "java.io.File"
}

Date

{
  "@type" : "g:Date",
  "@value" : 1481750076295
}

Double

{
  "@type" : "g:Double",
  "@value" : 100.0
}

Float

{
  "@type" : "g:Float",
  "@value" : 100.0
}

Integer

{
  "@type" : "g:Int32",
  "@value" : 100
}

Long

{
  "@type" : "g:Int64",
  "@value" : 100
}

Timestamp

{
  "@type" : "g:Timestamp",
  "@value" : 1481750076295
}

UUID

{
  "@type" : "g:UUID",
  "@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
}

Graph Structure

Edge

{
  "@type" : "g:Edge",
  "@value" : {
    "id" : {
      "@type" : "g:Int32",
      "@value" : 13
    },
    "label" : "develops",
    "inVLabel" : "software",
    "outVLabel" : "person",
    "inV" : {
      "@type" : "g:Int32",
      "@value" : 10
    },
    "outV" : {
      "@type" : "g:Int32",
      "@value" : 1
    },
    "properties" : {
      "since" : {
        "@type" : "g:Int32",
        "@value" : 2009
      }
    }
  }
}

Path

{
  "@type" : "g:Path",
  "@value" : {
    "labels" : [ [ ], [ ], [ ] ],
    "objects" : [ {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 0
            },
            "value" : "marko"
          } ],
          "location" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 6
            },
            "value" : "san diego",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 1997
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 7
            },
            "value" : "santa cruz",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 8
            },
            "value" : "brussels",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 9
            },
            "value" : "santa fe",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "label" : "software",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 4
            },
            "value" : "gremlin"
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "label" : "software",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 5
            },
            "value" : "tinkergraph"
          } ]
        }
      }
    } ]
  }
}

Property

{
  "@type" : "g:Property",
  "@value" : {
    "key" : "since",
    "value" : {
      "@type" : "g:Int32",
      "@value" : 2009
    },
    "edge" : {
      "id" : {
        "@type" : "g:Int32",
        "@value" : 13
      },
      "label" : "develops",
      "inV" : {
        "@type" : "g:Int32",
        "@value" : 10
      },
      "outV" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

StarGraph

{
  "starVertex" : {
    "@type" : "g:Vertex",
    "@value" : {
      "id" : {
        "@type" : "g:Int32",
        "@value" : 1
      },
      "label" : "person",
      "properties" : {
        "name" : [ {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 0
          },
          "value" : "marko"
        } ],
        "location" : [ {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 6
          },
          "value" : "san diego",
          "properties" : {
            "startTime" : {
              "@type" : "g:Int32",
              "@value" : 1997
            },
            "endTime" : {
              "@type" : "g:Int32",
              "@value" : 2001
            }
          }
        }, {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 7
          },
          "value" : "santa cruz",
          "properties" : {
            "startTime" : {
              "@type" : "g:Int32",
              "@value" : 2001
            },
            "endTime" : {
              "@type" : "g:Int32",
              "@value" : 2004
            }
          }
        }, {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 8
          },
          "value" : "brussels",
          "properties" : {
            "startTime" : {
              "@type" : "g:Int32",
              "@value" : 2004
            },
            "endTime" : {
              "@type" : "g:Int32",
              "@value" : 2005
            }
          }
        }, {
          "id" : {
            "@type" : "g:Int64",
            "@value" : 9
          },
          "value" : "santa fe",
          "properties" : {
            "startTime" : {
              "@type" : "g:Int32",
              "@value" : 2005
            }
          }
        } ]
      }
    }
  }
}

TinkerGraph

TinkerGraph has a custom serializer that is registered as part of the TinkerIoRegistry.

{
  "@type" : "tinker:graph",
  "@value" : {
    "vertices" : [ {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 0
            },
            "value" : "marko"
          } ],
          "location" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 6
            },
            "value" : "san diego",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 1997
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 7
            },
            "value" : "santa cruz",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 8
            },
            "value" : "brussels",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 9
            },
            "value" : "santa fe",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 1
            },
            "value" : "stephen"
          } ],
          "location" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 10
            },
            "value" : "centreville",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 1990
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2000
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 11
            },
            "value" : "dulles",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2000
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2006
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 12
            },
            "value" : "purcellville",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2006
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 8
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 2
            },
            "value" : "matthias"
          } ],
          "location" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 13
            },
            "value" : "bremen",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2007
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 14
            },
            "value" : "baltimore",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2007
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2011
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 15
            },
            "value" : "oakland",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2011
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2014
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 16
            },
            "value" : "seattle",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2014
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 9
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 3
            },
            "value" : "daniel"
          } ],
          "location" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 17
            },
            "value" : "spremberg",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 1982
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 18
            },
            "value" : "kaiserslautern",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2009
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 19
            },
            "value" : "aachen",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2009
              }
            }
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "label" : "software",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 4
            },
            "value" : "gremlin"
          } ]
        }
      }
    }, {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "label" : "software",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 5
            },
            "value" : "tinkergraph"
          } ]
        }
      }
    } ],
    "edges" : [ {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 13
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2009
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 14
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2010
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 15
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 4
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 16
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 5
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 17
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2010
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 18
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2011
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 19
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 5
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 20
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 7
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 4
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 21
        },
        "label" : "develops",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 8
        },
        "properties" : {
          "since" : {
            "@type" : "g:Int32",
            "@value" : 2012
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 22
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 8
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 3
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 23
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 8
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 3
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 24
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 10
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 9
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 5
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 25
        },
        "label" : "uses",
        "inVLabel" : "software",
        "outVLabel" : "person",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 9
        },
        "properties" : {
          "skill" : {
            "@type" : "g:Int32",
            "@value" : 3
          }
        }
      }
    }, {
      "@type" : "g:Edge",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 26
        },
        "label" : "traverses",
        "inVLabel" : "software",
        "outVLabel" : "software",
        "inV" : {
          "@type" : "g:Int32",
          "@value" : 11
        },
        "outV" : {
          "@type" : "g:Int32",
          "@value" : 10
        }
      }
    } ]
  }
}

Tree

{
  "@type" : "g:Tree",
  "@value" : [ {
    "key" : {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 0
            },
            "value" : "marko"
          } ],
          "location" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 6
            },
            "value" : "san diego",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 1997
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 7
            },
            "value" : "santa cruz",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 8
            },
            "value" : "brussels",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 9
            },
            "value" : "santa fe",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          } ]
        }
      }
    },
    "value" : {
      "@type" : "g:Tree",
      "@value" : [ {
        "key" : {
          "@type" : "g:Vertex",
          "@value" : {
            "id" : {
              "@type" : "g:Int32",
              "@value" : 10
            },
            "label" : "software",
            "properties" : {
              "name" : [ {
                "id" : {
                  "@type" : "g:Int64",
                  "@value" : 4
                },
                "value" : "gremlin"
              } ]
            }
          }
        },
        "value" : {
          "@type" : "g:Tree",
          "@value" : [ {
            "key" : {
              "@type" : "g:Vertex",
              "@value" : {
                "id" : {
                  "@type" : "g:Int32",
                  "@value" : 11
                },
                "label" : "software",
                "properties" : {
                  "name" : [ {
                    "id" : {
                      "@type" : "g:Int64",
                      "@value" : 5
                    },
                    "value" : "tinkergraph"
                  } ]
                }
              }
            },
            "value" : {
              "@type" : "g:Tree",
              "@value" : [ ]
            }
          } ]
        }
      } ]
    }
  } ]
}

Vertex

{
  "@type" : "g:Vertex",
  "@value" : {
    "id" : {
      "@type" : "g:Int32",
      "@value" : 1
    },
    "label" : "person",
    "properties" : {
      "name" : [ {
        "id" : {
          "@type" : "g:Int64",
          "@value" : 0
        },
        "value" : "marko"
      } ],
      "location" : [ {
        "id" : {
          "@type" : "g:Int64",
          "@value" : 6
        },
        "value" : "san diego",
        "properties" : {
          "startTime" : {
            "@type" : "g:Int32",
            "@value" : 1997
          },
          "endTime" : {
            "@type" : "g:Int32",
            "@value" : 2001
          }
        }
      }, {
        "id" : {
          "@type" : "g:Int64",
          "@value" : 7
        },
        "value" : "santa cruz",
        "properties" : {
          "startTime" : {
            "@type" : "g:Int32",
            "@value" : 2001
          },
          "endTime" : {
            "@type" : "g:Int32",
            "@value" : 2004
          }
        }
      }, {
        "id" : {
          "@type" : "g:Int64",
          "@value" : 8
        },
        "value" : "brussels",
        "properties" : {
          "startTime" : {
            "@type" : "g:Int32",
            "@value" : 2004
          },
          "endTime" : {
            "@type" : "g:Int32",
            "@value" : 2005
          }
        }
      }, {
        "id" : {
          "@type" : "g:Int64",
          "@value" : 9
        },
        "value" : "santa fe",
        "properties" : {
          "startTime" : {
            "@type" : "g:Int32",
            "@value" : 2005
          }
        }
      } ]
    }
  }
}

VertexProperty

{
  "@type" : "g:VertexProperty",
  "@value" : {
    "id" : {
      "@type" : "g:Int64",
      "@value" : 0
    },
    "value" : "marko",
    "vertex" : {
      "@type" : "g:Int32",
      "@value" : 1
    },
    "label" : "name"
  }
}

Graph Process

Barrier

{
  "@type" : "g:Barrier",
  "@value" : "normSack"
}

Binding

A "Binding" refers to a Bytecode.Binding.

{
  "@type" : "g:Binding",
  "@value" : {
    "key" : "x",
    "value" : {
      "@type" : "g:Int32",
      "@value" : 1
    }
  }
}

Bytecode

The following Bytecode example represents the traversal of g.V().hasLabel('person').out().in().tree(). Obviously the serialized Bytecode woudl be quite different for the endless variations of commands that could be used together in the Gremlin language.

{
  "@type" : "g:Bytecode",
  "@value" : {
    "step" : [ [ "V" ], [ "hasLabel", "person" ], [ "out" ], [ "in" ], [ "tree" ] ]
  }
}

Cardinality

{
  "@type" : "g:Cardinality",
  "@value" : "list"
}

Column

{
  "@type" : "g:Column",
  "@value" : "keys"
}

Direction

{
  "@type" : "g:Direction",
  "@value" : "OUT"
}

Operator

{
  "@type" : "g:Operator",
  "@value" : "sum"
}

Order

{
  "@type" : "g:Order",
  "@value" : "incr"
}

Pick

{
  "@type" : "g:Pick",
  "@value" : "any"
}

Pop

{
  "@type" : "g:Pop",
  "@value" : "all"
}

Lambda

{
  "@type" : "g:Lambda",
  "@value" : {
    "script" : "{ it.get() }",
    "language" : "gremlin-groovy",
    "arguments" : 1
  }
}

Metrics

{
  "@type" : "g:Metrics",
  "@value" : {
    "dur" : {
      "@type" : "g:Double",
      "@value" : 100.0
    },
    "counts" : {
      "traverserCount" : {
        "@type" : "g:Int64",
        "@value" : 4
      },
      "elementCount" : {
        "@type" : "g:Int64",
        "@value" : 4
      }
    },
    "name" : "TinkerGraphStep(vertex,[~label.eq(person)])",
    "annotations" : {
      "percentDur" : {
        "@type" : "g:Double",
        "@value" : 25.0
      }
    },
    "id" : "7.0.0()",
    "metrics" : [ {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 7
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 7
          }
        },
        "name" : "VertexStep(OUT,vertex)",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "3.0.0()"
      }
    } ]
  }
}

P

{
  "@type" : "g:P",
  "@value" : {
    "predicate" : "gt",
    "value" : {
      "@type" : "g:Int32",
      "@value" : 0
    }
  }
}

P and

{
  "@type" : "g:P",
  "@value" : {
    "predicate" : "and",
    "value" : [ {
      "@type" : "g:P",
      "@value" : {
        "predicate" : "gt",
        "value" : {
          "@type" : "g:Int32",
          "@value" : 0
        }
      }
    }, {
      "@type" : "g:P",
      "@value" : {
        "predicate" : "lt",
        "value" : {
          "@type" : "g:Int32",
          "@value" : 10
        }
      }
    } ]
  }
}

P or

{
  "@type" : "g:P",
  "@value" : {
    "predicate" : "or",
    "value" : [ {
      "@type" : "g:P",
      "@value" : {
        "predicate" : "gt",
        "value" : {
          "@type" : "g:Int32",
          "@value" : 0
        }
      }
    }, {
      "@type" : "g:P",
      "@value" : {
        "predicate" : "within",
        "value" : [ {
          "@type" : "g:Int32",
          "@value" : -1
        }, {
          "@type" : "g:Int32",
          "@value" : -10
        }, {
          "@type" : "g:Int32",
          "@value" : -100
        } ]
      }
    } ]
  }
}

Scope

{
  "@type" : "g:Scope",
  "@value" : "local"
}

T

{
  "@type" : "g:T",
  "@value" : "label"
}

TraversalMetrics

{
  "@type" : "g:TraversalMetrics",
  "@value" : {
    "dur" : {
      "@type" : "g:Double",
      "@value" : 0.004
    },
    "metrics" : [ {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 4
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 4
          }
        },
        "name" : "TinkerGraphStep(vertex,[~label.eq(person)])",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "7.0.0()"
      }
    }, {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 13
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 13
          }
        },
        "name" : "VertexStep(OUT,vertex)",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "2.0.0()"
      }
    }, {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 7
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 7
          }
        },
        "name" : "VertexStep(OUT,vertex)",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "3.0.0()"
      }
    }, {
      "@type" : "g:Metrics",
      "@value" : {
        "dur" : {
          "@type" : "g:Double",
          "@value" : 100.0
        },
        "counts" : {
          "traverserCount" : {
            "@type" : "g:Int64",
            "@value" : 1
          },
          "elementCount" : {
            "@type" : "g:Int64",
            "@value" : 1
          }
        },
        "name" : "TreeStep",
        "annotations" : {
          "percentDur" : {
            "@type" : "g:Double",
            "@value" : 25.0
          }
        },
        "id" : "4.0.0()"
      }
    } ]
  }
}

Traverser

{
  "@type" : "g:Traverser",
  "@value" : {
    "bulk" : {
      "@type" : "g:Int64",
      "@value" : 1
    },
    "value" : {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 0
            },
            "value" : "marko"
          } ],
          "location" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 6
            },
            "value" : "san diego",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 1997
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 7
            },
            "value" : "santa cruz",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 8
            },
            "value" : "brussels",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 9
            },
            "value" : "santa fe",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          } ]
        }
      }
    }
  }
}

RequestMessage

Authentication Response

The following RequestMessage is an example of the response that should be made to a SASL-based authentication challenge.

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "authentication",
  "processor" : "",
  "args" : {
    "saslMechanism" : "PLAIN",
    "sasl" : "AHN0ZXBocGhlbgBwYXNzd29yZA=="
  }
}

Session Eval

The following RequestMessage is an example of a simple session request for a script evaluation with parameters.

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "eval",
  "processor" : "session",
  "args" : {
    "gremlin" : "g.V(x)",
    "language" : "gremlin-groovy",
    "session" : {
      "@type" : "g:UUID",
      "@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
    },
    "bindings" : {
      "x" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

Session Eval Aliased

The following RequestMessage is an example of a session request for a script evaluation with an alias that binds the TraversalSource of "g" to "social".

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "eval",
  "processor" : "session",
  "args" : {
    "gremlin" : "social.V(x)",
    "language" : "gremlin-groovy",
    "aliases" : {
      "g" : "social"
    },
    "session" : {
      "@type" : "g:UUID",
      "@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
    },
    "bindings" : {
      "x" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

Session Close

The following RequestMessage is an example of a request to close a session.

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "close",
  "processor" : "session",
  "args" : {
    "session" : {
      "@type" : "g:UUID",
      "@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
    }
  }
}

Sessionless Eval

The following RequestMessage is an example of a simple sessionless request for a script evaluation with parameters.

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "eval",
  "processor" : "",
  "args" : {
    "gremlin" : "g.V(x)",
    "language" : "gremlin-groovy",
    "bindings" : {
      "x" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

Sessionless Eval Aliased

The following RequestMessage is an example of a sessionless request for a script evaluation with an alias that binds the TraversalSource of "g" to "social".

{
  "requestId" : "cb682578-9d92-4499-9ebc-5c6aa73c5397",
  "op" : "eval",
  "processor" : "",
  "args" : {
    "gremlin" : "social.V(x)",
    "language" : "gremlin-groovy",
    "aliases" : {
      "g" : "social"
    },
    "bindings" : {
      "x" : {
        "@type" : "g:Int32",
        "@value" : 1
      }
    }
  }
}

ResponseMessage

Authentication Challenge

When authentication is enabled, an initial request to the server will result in an authentication challenge. The typical response message will appear as follows, but handling it could be different depending on the SASL implementation (e.g. multiple challenges maybe requested in some cases, but no in the default provided by Gremlin Server).

{
  "requestId" : "41d2e28a-20a4-4ab0-b379-d810dede3786",
  "status" : {
    "message" : "",
    "code" : 407,
    "attributes" : { }
  },
  "result" : {
    "data" : null,
    "meta" : { }
  }
}

Standard Result

The following ResponseMessage is a typical example of the typical successful response Gremlin Server will return when returning results from a script.

{
  "requestId" : "41d2e28a-20a4-4ab0-b379-d810dede3786",
  "status" : {
    "message" : "",
    "code" : 200,
    "attributes" : { }
  },
  "result" : {
    "data" : [ {
      "@type" : "g:Vertex",
      "@value" : {
        "id" : {
          "@type" : "g:Int32",
          "@value" : 1
        },
        "label" : "person",
        "properties" : {
          "name" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 0
            },
            "value" : "marko"
          } ],
          "location" : [ {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 6
            },
            "value" : "san diego",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 1997
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 7
            },
            "value" : "santa cruz",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2001
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 8
            },
            "value" : "brussels",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2004
              },
              "endTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          }, {
            "id" : {
              "@type" : "g:Int64",
              "@value" : 9
            },
            "value" : "santa fe",
            "properties" : {
              "startTime" : {
                "@type" : "g:Int32",
                "@value" : 2005
              }
            }
          } ]
        }
      }
    } ],
    "meta" : { }
  }
}

Extended

Note that the "extended" types require the addition of the separate GraphSONXModuleV2d0 module as follows:

mapper = GraphSONMapper.build().
                        typeInfo(TypeInfo.PARTIAL_TYPES).
                        addCustomModule(GraphSONXModuleV2d0.build().create(false)).
                        version(GraphSONVersion.V2_0).create().createMapper()

BigDecimal

{
  "@type" : "gx:BigDecimal",
  "@value" : 123456789987654321123456789987654321
}

BigInteger

{
  "@type" : "gx:BigInteger",
  "@value" : 123456789987654321123456789987654321
}

Byte

{
  "@type" : "gx:Byte",
  "@value" : 1
}

ByteBuffer

{
  "@type" : "gx:ByteBuffer",
  "@value" : "c29tZSBieXRlcyBmb3IgeW91"
}

Char

{
  "@type" : "gx:Char",
  "@value" : "x"
}

Duration

The following example is a Duration of five days.

{
  "@type" : "gx:Duration",
  "@value" : "PT120H"
}

InetAddress

{
  "@type" : "gx:InetAddress",
  "@value" : "localhost"
}

Instant

{
  "@type" : "gx:Instant",
  "@value" : "2016-12-14T16:39:19.349Z"
}

LocalDate

{
  "@type" : "gx:LocalDate",
  "@value" : "2016-01-01"
}

LocalDateTime

{
  "@type" : "gx:LocalDateTime",
  "@value" : "2016-01-01T12:30"
}

LocalTime

{
  "@type" : "gx:LocalTime",
  "@value" : "12:30:45"
}

MonthDay

{
  "@type" : "gx:MonthDay",
  "@value" : "--01-01"
}

OffsetDateTime

{
  "@type" : "gx:OffsetDateTime",
  "@value" : "2007-12-03T10:15:30+01:00"
}

OffsetTime

{
  "@type" : "gx:OffsetTime",
  "@value" : "10:15:30+01:00"
}

Period

The following example is a Period of one year, six months and fifteen days.

{
  "@type" : "gx:Period",
  "@value" : "P1Y6M15D"
}

Short

{
  "@type" : "gx:Int16",
  "@value" : 100
}

Year

The following example is of the Year "2016".

{
  "@type" : "gx:Year",
  "@value" : "2016"
}

YearMonth

The following example is a YearMonth of "June 2016"

{
  "@type" : "gx:YearMonth",
  "@value" : "2016-06"
}

ZonedDateTime

{
  "@type" : "gx:ZonedDateTime",
  "@value" : "2016-12-23T12:12:24.000000036+02:00[GMT+02:00]"
}

ZoneOffset

The following example is a ZoneOffset of three hours, six minutes, and nine seconds.

{
  "@type" : "gx:ZoneOffset",
  "@value" : "+03:06:09"
}

Gryo

gremlin kryo Gryo uses the popular Kryo library to handle binary serialization for the JVM. There currently aren’t any Kryo implementations in other languages so the binding of this format to the JVM is a bit of a limitation, but if building a system on the JVM the use of Gryo over other serialization format should yield smaller data sizes than other formats like GraphSON or GraphML, improved serialization speed, as well as better support for the various Java data types that might not be supported otherwise.

Gryo is useful both as a "graph" serialization format and as a generalized serialization format that can read or write any object. This characteristic makes it ideal for use in Gremlin Server, which is designed to return arbitrary results of varying types.

It is unlikely that Gryo users will try to consume or produce Gryo without using TinkerPop and Kryo classes to help do it. Attempting to read or write a byte stream of Gryo without those tools would be challenging, so the depths of what the Gryo format looks like in a byte-by-byte perspective will not be discussed here. It is enough to know that TinkerPop has Kryo-based serializers for certain classes that it supports and that the bytes written or read must be Kryo compliant.

One of the key aspects of Gryo is that, by default, it requires that all types expected to be used to be registered with the GryoMapper. There are two ways to do that:

  • On the GryoMapper.Builder, use the addCustom methods. These methods allow registration of single classes with an optional custom serializer.

  • Add a custom IoRegistry implementation with the addRegistry method on GryoMapper.Builder. The IoRegistry contains registrations that will be supplied to the GryoMapper. There is additional documentation on how this works in the provider documentation.

When using addCustom or addRegistry, it is important to remember that the order in which those methods are called is important. The registrations get numeric "registration ids" and their order must match if the the Gryo is expected to be compatible. Calls to addCustom will be applied first, prior to calls to addRegistry (which internally call addCustom).

It is possible to disable registration by setting registrationRequired on the GryoMapper.Builder to false, but Gryo is less efficient with this feature is turned off.

Until TinkerPop 3.3.0 there has only been one version of Gryo in 1.0 and the format for that version has generally expanded as new releases of TinkerPop have been produced. "Expansion" has generally meant that new types have come to be supported over time. The addition of new types means that while Gryo has remained at 1.0, older releases that produced Gryo files will not be compatible with newer TinkerPop releases if the newer types are utilized. On the flip side, newer release of TinkerPop are fully backward compatible with Gryo produced on older versions of TinkerPop.

As of TinkerPop 3.3.0, there is now a new version of Gryo in 3.0 that is only partially compatible with 1.0. Attempts to use 3.0 serializers with 1.0 serializers will likely lead to failure.

Both versions of Gryo support all the types defined by GraphSON as well as others that are bound more specifically to the JVM. The GryoVersion class contains a listing of all the default registered classes.