4.0.0-SNAPSHOT
IO Reference
IO features, capabilities and use cases are initially discussed in the Apache 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
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
edgedefaultsetting in the<graph>tag as that is the nature of the type of graph that TinkerPop supports. -
The vertex and edge
idvalues will always be treated as aStringif theGraphinstance 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
Builderfor theGraphReader. 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
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 versions 1 to 3 were considered to be 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. However, starting in GraphSON 4, GraphSON
is only intended to be a network serialization format that is only able to serialize specific types defined by the
format. It is only meant to be used with the TinkerPop HTTP API.
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 4.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 form 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 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). It is also worth considering that choosing a GraphSON format without embedded types may also restrict the
type of results that can be obtained. For example, g.V().groupCount() returns a format with a Map. That’s fine
for GraphSON, but the key in that Map is a complex object (i.e. a Vertex) and as such is not compatible with JSON
itself which can only support String keys.
|
Warning
|
The application/json mime type is shared with all versions of GraphSON and their variations and does not
reflect a particular one. Servers will return the GraphSON version and variation that this mime type is configured for
and it could be different (or change) from server to server. When building applications, it is recommended that the
mime type is made explicit on requests to avoid breaking changes or unexpected results.
|
Version 4.0
Version 4.0 of GraphSON was first introduced on TinkerPop 4.0.0 and is represented by the
application/vnd.gremlin-v4.0+json mime type. There also exists an untyped version:
application/vnd.gremlin-v4.0+json;types=false. It is very similar to GraphSON 3.0, with just several key differences:
many underused or duplicated types have been removed, labels are now list of strings and request/response formats have
changed quite a bit, and custom types have been replaced with Provider Defined Type (PDT).
Boolean
Matches the JSON Boolean and doesn’t have type information.
truetrueComposite PDT
JSON Object with two required keys: "type" and "fields"
"type" is a JSON String
"fields" is a g:Map
{
"@type": "g:CompositePdt",
"@value": {
"type": "tinkerId",
"fields": {
"@type": "g:Map",
"@value": [
"intId",
{
"@type": "g:Int32",
"@value": -1360894799
},
"strId",
"0"
]
}
}
}{
"type": "tinkerId",
"fields": {
"intId": -1360894799,
"strId": "0"
}
}DateTime
JSON String representing a datetime in the ISO-8601 format.
{
"@type" : "g:DateTime",
"@value" : "2007-12-03T10:15:30+01:00"
}"2007-12-03T10:15:30+01:00"Double
A JSON Number with the same range as a IEEE754 double precision floating point or a JSON String with one of the following values: "-Infinity", "Infinity", "NaN"
{
"@type" : "g:Double",
"@value" : 100.0
}100.0Float
A JSON Number with the same range as a IEEE754 single precision floating point or a JSON String with one of the following values: "-Infinity", "Infinity", "NaN"
{
"@type" : "g:Float",
"@value" : 100.0
}100.0Integer
A JSON Number with the same range as a 4-byte signed integer.
{
"@type" : "g:Int32",
"@value" : 100
}100List
List is a JSON Array. The type is used to distinguish between different collection types that are also mapped to JSON Array. The untyped version converts complex types to JSON String.
{
"@type": "g:List",
"@value": [
{
"@type": "g:Int32",
"@value": 1
},
"person",
true,
null
]
}[ 1, "person", true, null ]Long
A JSON Number with the same range as a 8-byte signed integer.
{
"@type" : "g:Int64",
"@value" : 100
}100Map
Map is a JSON Array to provide the ability to allow for non-String keys, which is not possible in JSON. The untyped version converts complex types to JSON String.
{
"@type": "g:Map",
"@value": [
{
"@type": "g:List",
"@value": [
{
"@type": "g:Int32",
"@value": 1
},
{
"@type": "g:Int32",
"@value": 2
},
{
"@type": "g:Int32",
"@value": 3
}
]
},
null,
"test",
{
"@type": "g:Int32",
"@value": 123
},
{
"@type": "g:DateTime",
"@value": "2024-09-02T10:30Z"
},
"red"
]
}{
"[1, 2, 3]": null,
"test": 123,
"2024-09-02T10:30Z": "red"
}Null
Matches the JSON Null and doesn’t have type information.
nullnullPrimitive PDT
JSON Object with two required keys: "type" and "value"
"type" is a JSON String
"value" is a JSON String
{
"@type": "g:PrimitivePdt",
"@value": {
"type": "tinkerId",
"value": "-1360894799"
}
}{
"type": "tinkerId",
"value": "-1360894799"
}Set
A JSON Array. The untyped version converts complex types to JSON String.
{
"@type": "g:Set",
"@value": [
null,
{
"@type": "g:Int32",
"@value": 2
},
"person",
true
]
}[ null, 2, "person", true ]String
Matches the JSON String and doesn’t have type information.
"abc""abc"UUID
JSON String form of UUID.
{
"@type" : "g:UUID",
"@value" : "41d2e28a-20a4-4ab0-b379-d810dede3786"
}"41d2e28a-20a4-4ab0-b379-d810dede3786"Edge
JSON Object (required keys are: id, label, inVLabel, outVLabel, inV, outV)
"id" is any GraphSON 4.0 type
"inV", "outV" is an Object that contains "id" which is any GraphSON 4.0 type and "label" which is a g:List of String
"label" is a g:List of String
"properties" is an optional Object containing Arrays of g:Property
The untyped version has one additional required key "type" which is always "vertex".
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 13
},
"label": [
"develops"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 1
},
"label": [
"person"
]
},
"properties": {
"since": [
{
"@type": "g:Property",
"@value": {
"key": "since",
"value": {
"@type": "g:Int32",
"@value": 2009
}
}
}
]
}
}
}{
"id": 13,
"label": [
"develops"
],
"type": "edge",
"inV": {
"id": 10,
"label": [
"software"
]
},
"outV": {
"id": 1,
"label": [
"person"
]
},
"properties": {
"since": [
2009
]
}
}Graph
TinkerGraph has a custom serializer that is registered as part of the TinkerIoRegistry. Graph is a JSON Object with
two required keys: "vertices" and "edges"
"vertices" is an Array of g:Vertex
"edges" is an Array of g:Edge
{
"@type": "g: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",
"label": [
"name"
]
}
}
],
"location": [
{
"@type": "g:VertexProperty",
"@value": {
"id": {
"@type": "g:Int64",
"@value": 6
},
"value": "san diego",
"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",
"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",
"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",
"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",
"label": [
"name"
]
}
}
],
"location": [
{
"@type": "g:VertexProperty",
"@value": {
"id": {
"@type": "g:Int64",
"@value": 10
},
"value": "centreville",
"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",
"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",
"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",
"label": [
"name"
]
}
}
],
"location": [
{
"@type": "g:VertexProperty",
"@value": {
"id": {
"@type": "g:Int64",
"@value": 13
},
"value": "bremen",
"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",
"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",
"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",
"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",
"label": [
"name"
]
}
}
],
"location": [
{
"@type": "g:VertexProperty",
"@value": {
"id": {
"@type": "g:Int64",
"@value": 17
},
"value": "spremberg",
"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",
"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",
"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",
"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",
"label": [
"name"
]
}
}
]
}
}
}
],
"edges": [
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 13
},
"label": [
"develops"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 1
},
"label": [
"person"
]
},
"properties": {
"since": [
{
"@type": "g:Property",
"@value": {
"key": "since",
"value": {
"@type": "g:Int32",
"@value": 2009
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 14
},
"label": [
"develops"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 11
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 1
},
"label": [
"person"
]
},
"properties": {
"since": [
{
"@type": "g:Property",
"@value": {
"key": "since",
"value": {
"@type": "g:Int32",
"@value": 2010
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 15
},
"label": [
"uses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 1
},
"label": [
"person"
]
},
"properties": {
"skill": [
{
"@type": "g:Property",
"@value": {
"key": "skill",
"value": {
"@type": "g:Int32",
"@value": 4
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 16
},
"label": [
"uses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 11
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 1
},
"label": [
"person"
]
},
"properties": {
"skill": [
{
"@type": "g:Property",
"@value": {
"key": "skill",
"value": {
"@type": "g:Int32",
"@value": 5
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 17
},
"label": [
"develops"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 7
},
"label": [
"person"
]
},
"properties": {
"since": [
{
"@type": "g:Property",
"@value": {
"key": "since",
"value": {
"@type": "g:Int32",
"@value": 2010
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 18
},
"label": [
"develops"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 11
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 7
},
"label": [
"person"
]
},
"properties": {
"since": [
{
"@type": "g:Property",
"@value": {
"key": "since",
"value": {
"@type": "g:Int32",
"@value": 2011
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 19
},
"label": [
"uses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 7
},
"label": [
"person"
]
},
"properties": {
"skill": [
{
"@type": "g:Property",
"@value": {
"key": "skill",
"value": {
"@type": "g:Int32",
"@value": 5
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 20
},
"label": [
"uses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 11
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 7
},
"label": [
"person"
]
},
"properties": {
"skill": [
{
"@type": "g:Property",
"@value": {
"key": "skill",
"value": {
"@type": "g:Int32",
"@value": 4
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 21
},
"label": [
"develops"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 8
},
"label": [
"person"
]
},
"properties": {
"since": [
{
"@type": "g:Property",
"@value": {
"key": "since",
"value": {
"@type": "g:Int32",
"@value": 2012
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 22
},
"label": [
"uses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 8
},
"label": [
"person"
]
},
"properties": {
"skill": [
{
"@type": "g:Property",
"@value": {
"key": "skill",
"value": {
"@type": "g:Int32",
"@value": 3
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 23
},
"label": [
"uses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 11
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 8
},
"label": [
"person"
]
},
"properties": {
"skill": [
{
"@type": "g:Property",
"@value": {
"key": "skill",
"value": {
"@type": "g:Int32",
"@value": 3
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 24
},
"label": [
"uses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 9
},
"label": [
"person"
]
},
"properties": {
"skill": [
{
"@type": "g:Property",
"@value": {
"key": "skill",
"value": {
"@type": "g:Int32",
"@value": 5
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 25
},
"label": [
"uses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 11
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 9
},
"label": [
"person"
]
},
"properties": {
"skill": [
{
"@type": "g:Property",
"@value": {
"key": "skill",
"value": {
"@type": "g:Int32",
"@value": 3
}
}
}
]
}
}
},
{
"@type": "g:Edge",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 26
},
"label": [
"traverses"
],
"inV": {
"id": {
"@type": "g:Int32",
"@value": 11
},
"label": [
"software"
]
},
"outV": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
}
}
}
]
}
}{
"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",
"inV": {
"id": 10,
"label": [
"software"
]
},
"outV": {
"id": 1,
"label": [
"person"
]
},
"properties": {
"since": [
2009
]
}
},
{
"id": 14,
"label": [
"develops"
],
"type": "edge",
"inV": {
"id": 11,
"label": [
"software"
]
},
"outV": {
"id": 1,
"label": [
"person"
]
},
"properties": {
"since": [
2010
]
}
},
{
"id": 15,
"label": [
"uses"
],
"type": "edge",
"inV": {
"id": 10,
"label": [
"software"
]
},
"outV": {
"id": 1,
"label": [
"person"
]
},
"properties": {
"skill": [
4
]
}
},
{
"id": 16,
"label": [
"uses"
],
"type": "edge",
"inV": {
"id": 11,
"label": [
"software"
]
},
"outV": {
"id": 1,
"label": [
"person"
]
},
"properties": {
"skill": [
5
]
}
},
{
"id": 17,
"label": [
"develops"
],
"type": "edge",
"inV": {
"id": 10,
"label": [
"software"
]
},
"outV": {
"id": 7,
"label": [
"person"
]
},
"properties": {
"since": [
2010
]
}
},
{
"id": 18,
"label": [
"develops"
],
"type": "edge",
"inV": {
"id": 11,
"label": [
"software"
]
},
"outV": {
"id": 7,
"label": [
"person"
]
},
"properties": {
"since": [
2011
]
}
},
{
"id": 19,
"label": [
"uses"
],
"type": "edge",
"inV": {
"id": 10,
"label": [
"software"
]
},
"outV": {
"id": 7,
"label": [
"person"
]
},
"properties": {
"skill": [
5
]
}
},
{
"id": 20,
"label": [
"uses"
],
"type": "edge",
"inV": {
"id": 11,
"label": [
"software"
]
},
"outV": {
"id": 7,
"label": [
"person"
]
},
"properties": {
"skill": [
4
]
}
},
{
"id": 21,
"label": [
"develops"
],
"type": "edge",
"inV": {
"id": 10,
"label": [
"software"
]
},
"outV": {
"id": 8,
"label": [
"person"
]
},
"properties": {
"since": [
2012
]
}
},
{
"id": 22,
"label": [
"uses"
],
"type": "edge",
"inV": {
"id": 10,
"label": [
"software"
]
},
"outV": {
"id": 8,
"label": [
"person"
]
},
"properties": {
"skill": [
3
]
}
},
{
"id": 23,
"label": [
"uses"
],
"type": "edge",
"inV": {
"id": 11,
"label": [
"software"
]
},
"outV": {
"id": 8,
"label": [
"person"
]
},
"properties": {
"skill": [
3
]
}
},
{
"id": 24,
"label": [
"uses"
],
"type": "edge",
"inV": {
"id": 10,
"label": [
"software"
]
},
"outV": {
"id": 9,
"label": [
"person"
]
},
"properties": {
"skill": [
5
]
}
},
{
"id": 25,
"label": [
"uses"
],
"type": "edge",
"inV": {
"id": 11,
"label": [
"software"
]
},
"outV": {
"id": 9,
"label": [
"person"
]
},
"properties": {
"skill": [
3
]
}
},
{
"id": 26,
"label": [
"traverses"
],
"type": "edge",
"inV": {
"id": 11,
"label": [
"software"
]
},
"outV": {
"id": 10,
"label": [
"software"
]
}
}
]
}Path
Object with two required keys: "labels" and "objects"
"labels" is a g:List of g:Set of labels of the steps traversed
"objects" is a g:List of objects traversed
{
"@type": "g:Path",
"@value": {
"labels": {
"@type": "g:List",
"@value": [
{
"@type": "g:Set",
"@value": []
},
{
"@type": "g:Set",
"@value": []
},
{
"@type": "g:Set",
"@value": []
}
]
},
"objects": {
"@type": "g:List",
"@value": [
{
"@type": "g:Vertex",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 1
},
"label": [
"person"
]
}
},
{
"@type": "g:Vertex",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 10
},
"label": [
"software"
]
}
},
{
"@type": "g:Vertex",
"@value": {
"id": {
"@type": "g:Int32",
"@value": 11
},
"label": [
"software"
]
}
}
]
}
}
}{
"labels": [
[],
[],
[]
],
"objects": [
{
"id": 1,
"label": [
"person"
],
"type": "vertex"
},
{
"id": 10,
"label": [
"software"
],
"type": "vertex"
},
{
"id": 11,
"label": [
"software"
],
"type": "vertex"
}
]
}Property
JSON Object with two required keys: "key" and "value"
"key" is a String
"value" is any GraphSON 4.0 type
{
"@type": "g:Property",
"@value": {
"key": "since",
"value": {
"@type": "g:Int32",
"@value": 2009
}
}
}{
"key" : "since",
"value" : 2009
}Tree
JSON Object with one or more possibly nested "key" "value" pairs
"key" is an Element (g:Vertex, g:Edge, g:VertexProperty)
"value" is a g:Tree making this a recursively defined structure
{
"@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",
"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",
"label": [
"name"
]
}
}
]
}
}
},
"value": {
"@type": "g:Tree",
"@value": []
}
}
]
}
}
]
}[
{
"key": {
"id": 10,
"label": [
"software"
],
"type": "vertex",
"properties": {
"name": [
{
"id": 4,
"value": "gremlin"
}
]
}
},
"value": [
{
"key": {
"id": 11,
"label": [
"software"
],
"type": "vertex",
"properties": {
"name": [
{
"id": 5,
"value": "tinkergraph"
}
]
}
},
"value": []
}
]
}
]Vertex
JSON Object with required keys: "id", "label", "properties"
"id" is any GraphSON 4.0 type
"label" is a g:List of String
"properties" is an optional Object containing Arrays of g:VertexProperty
The untyped version has one additional required key "type" which is always "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",
"label": [
"name"
]
}
}
],
"location": [
{
"@type": "g:VertexProperty",
"@value": {
"id": {
"@type": "g:Int64",
"@value": 6
},
"value": "san diego",
"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",
"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",
"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",
"label": [
"location"
],
"properties": {
"startTime": {
"@type": "g:Int32",
"@value": 2005
}
}
}
}
]
}
}
}{
"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
JSON Object with required keys: "id", "value", "label", "properties"
"id" is any type GraphSON 4.0 type
"value" is any type GraphSON 4.0 type
"label" is a g:List of String
"properties" is an optional Object containing Arrays of "g:Property" (metaproperties)
{
"@type": "g:VertexProperty",
"@value": {
"id": {
"@type": "g:Int64",
"@value": 0
},
"value": "marko",
"label": [
"name"
]
}
}{
"id": 0,
"value": "marko",
"label": [
"name"
]
}BulkSet
JSON Array that contains the expanded entries of the BulkSet. Note: BulkSet is serialized to g:List so there is no BulkSet deserializer.
{
"@type": "g:List",
"@value": [
"marko",
"josh",
"josh"
]
}[ "marko", "josh", "josh" ]Direction
JSON String of the enum value.
{
"@type" : "g:Direction",
"@value" : "OUT"
}"OUT"T
JSON String of the enum value.
{
"@type" : "g:T",
"@value" : "label"
}"label"Standard Request
The following RequestMessage is an example of a simple sessionless request for a script evaluation with parameters.
{
"gremlin": "g.V(x)",
"materializeProperties": "tokens",
"timeoutMs": {
"@type": "g:Int64",
"@value": 1000
},
"g": "g",
"bindings": {
"@type": "g:Map",
"@value": [
"x",
{
"@type": "g:Int32",
"@value": 1
}
]
},
"language": "gremlin-groovy"
}{
"gremlin": "g.V(x)",
"materializeProperties": "tokens",
"timeoutMs": 1000,
"g": "g",
"bindings": {
"x": 1
},
"language": "gremlin-groovy"
}Standard Result
The following ResponseMessage is a typical example of the typical successful response Gremlin Server will return when returning results from a script.
{
"result": {
"data": {
"@type": "g:List",
"@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",
"label": [
"name"
]
}
}
],
"location": [
{
"@type": "g:VertexProperty",
"@value": {
"id": {
"@type": "g:Int64",
"@value": 6
},
"value": "san diego",
"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",
"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",
"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",
"label": [
"location"
],
"properties": {
"startTime": {
"@type": "g:Int32",
"@value": 2005
}
}
}
}
]
}
}
}
]
}
},
"status": {
"code": 200
}
}{
"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
}
}
]
}
}
]
},
"status": {
"code": 200
}
}Error Result
The following ResponseMessage is a typical example of the typical successful response Gremlin Server will return when returning results from a script.
{
"result": {
"data": {
"@type": "g:List",
"@value": []
}
},
"status": {
"code": 500,
"message": "A timeout occurred during traversal evaluation",
"exception": "ServerTimeoutExceededException"
}
}{
"result": {
"data": []
},
"status": {
"code": 500,
"message": "A timeout occurred during traversal evaluation",
"exception": "ServerTimeoutExceededException"
}
}Note that the "extended" types require the addition of the separate GraphSONXModuleV4d0 module as follows:
mapper = GraphSONMapper.build().
typeInfo(TypeInfo.PARTIAL_TYPES).
addCustomModule(GraphSONXModuleV4.build()).
version(GraphSONVersion.V4_0).create().createMapper()BigDecimal
A JSON Number.
{
"@type" : "g:BigDecimal",
"@value" : 123456789987654321123456789987654321
}123456789987654321123456789987654321BigInteger
A JSON Number.
{
"@type" : "g:BigInteger",
"@value" : 123456789987654321123456789987654321
}123456789987654321123456789987654321Byte
A JSON Number with the same range as a 1-byte signed integer.
{
"@type" : "g:Byte",
"@value" : 1
}1Binary
JSON String containing base64-encoded bytes
{
"@type" : "g:Binary",
"@value" : "c29tZSBieXRlcyBmb3IgeW91"
}"c29tZSBieXRlcyBmb3IgeW91"Char
A JSON String containing a single UTF-8 encoded character.
{
"@type" : "g:Char",
"@value" : "x"
}"x"Duration
JSON String with ISO-8601 seconds based representation. The following example is a Duration of five days.
{
"@type" : "g:Duration",
"@value" : "PT120H"
}"PT120H"Short
A JSON Number with the same range as a 2-byte signed integer.
{
"@type" : "g:Int16",
"@value" : 100
}100Gryo
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.
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 theaddCustommethods. These methods allow registration of single classes with an optional custom serializer. -
Add a custom
IoRegistryimplementation with theaddRegistrymethod onGryoMapper.Builder. TheIoRegistrycontains registrations that will be supplied to theGryoMapper. 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. For best results, users should always utilize the same version of TinkerPop on the client as on the server.
|
Important
|
As of 3.6.0, Gryo MessageSerializer implementations have been removed from the codebase.
|
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.
GraphBinary
GraphBinary is a binary serialization format suitable for object trees, designed to reduce serialization overhead on both the client and the server, as well as limiting the size of the payload that is transmitted over the wire.
It describes arbitrary object graphs with a fully-qualified format:
{type_code}{type_info}{value_flag}{value}Where:
-
{type_code}is a single unsigned byte representing the type number. -
{type_info}is an optional sequence of bytes providing additional information of the type represented. This is specially useful for representing complex and custom types. -
{value_flag}is a single byte providing information about the value. Each type may have its own specific flags so see each type for more details. Generally, flags have the following meaning:-
0x01The value isnull. When this flag is set, no bytes for{value}will be provided.
-
-
{value}is a sequence of bytes which content is determined by the type.
All encodings are big-endian.
Quick examples, using hexadecimal notation to represent each byte:
-
01 00 00 00 00 01: a 32-bit integer number, that represents the decimal number 1. It’s composed by the type_code0x01, and empty flag value0x00and four bytes to describe the value. -
01 00 00 00 00 ff: a 32-bit integer, representing the number 256. -
01 01: a null value for a 32-bit integer. It’s composed by the type_code0x01, and a null flag value0x01. -
02 00 00 00 00 00 00 00 00 01: a 64-bit integer number 1. It’s composed by the type_code0x02, empty flags and eight bytes to describe the value.
Version 4.0
Forward Compatibility
The serialization format supports new types being added without the need to introduce a new version.
Changes to existing types require new revision.
Data Type Codes
Core Data Types
-
0x01: Int -
0x02: Long -
0x03: String -
0x04: DateTime -
0x07: Double -
0x08: Float -
0x09: List -
0x0a: Map -
0x0b: Set -
0x0c: UUID -
0x0d: Edge -
0x0e: Path -
0x0f: Property -
0x10: TinkerGraph -
0x11: Vertex -
0x12: VertexProperty -
0x18: Direction -
0x20: T -
0x22: BigDecimal -
0x23: BigInteger -
0x24: Byte -
0x25: Binary -
0x26: Short -
0x27: Boolean -
0x2b: Tree -
0xf0: CompositePDT -
0xf1: PrimitivePDT -
0xfd: Marker -
0xfe: Unspecified null object
Extended Types
-
0x80: Char -
0x81: Duration
Null handling
The serialization format defines two ways to represent null values:
-
Unspecified null object
-
Fully-qualified null
When a parent type can contain any subtype e.g., a object collection, a null value must be represented using the
"Unspecified Null Object" type code and the null value flag.
In contrast, when the parent type contains a type parameter that must be specified, a null value is represented using
a fully-qualified object using the appropriate type code and type information.
Data Type Formats
Int
Format: 4-byte two’s complement integer.
Example values:
-
00 00 00 01: 32-bit integer number 1. -
00 00 01 01: 32-bit integer number 256. -
ff ff ff ff: 32-bit integer number -1. -
ff ff ff fe: 32-bit integer number -2.
Long
Format: 8-byte two’s complement integer.
Example values
-
00 00 00 00 00 00 00 01: 64-bit integer number 1. -
ff ff ff ff ff ff ff fe: 64-bit integer number -2.
String
Format: {length}{text_value}
Where:
-
{length}is anIntdescribing the byte length of the text. Length is a positive number or zero to represent the empty string. -
{text_value}is a sequence of bytes representing the string value in UTF8 encoding.
Example values
-
00 00 00 03 61 62 63: the string 'abc'. -
00 00 00 04 61 62 63 64: the string 'abcd'. -
00 00 00 00: the empty string ''.
DateTime
A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system, such as 2007-12-03T10:15:30+01:00.
Format: {year}{month}{day}{time}{offset}
Where:
-
{year}is anIntfrom -999,999,999 to 999,999,999. -
{month}is aByteto represent the month, from 1 (January) to 12 (December) -
{day}is aBytefrom 1 to 31. -
{time}is aLongto represent nanoseconds since midnight, from 0 to 86399999999999 -
{offset}is anIntto represent total zone offset in seconds, from -64800 (-18:00) to 64800 (+18:00).
Double
Format: 8 bytes representing IEEE 754 double-precision binary floating-point format.
Example values
-
3f f0 00 00 00 00 00 00: Double 1 -
3f 70 00 00 00 00 00 00: Double 0.00390625 -
3f b9 99 99 99 99 99 9a: Double 0.1
Float
Format: 4 bytes representing IEEE 754 single-precision binary floating-point format.
Example values
-
3f 80 00 00: Float 1 -
3e c0 00 00: Float 0.375
List
An ordered collection of items. The format depends on the {value_flag}.
Format (value_flag=0x00): {length}{item_0}…{item_n}
Where:
-
{length}is anIntdescribing the length of the collection. -
{item_0}…{item_n}are the items of the list.{item_i}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}.
Format (value_flag=0x02): {length}{item_0}{bulk_0}…{item_n}{bulk_n}
Where:
-
{length}is anIntdescribing the length of the collection. -
{item_0}…{item_n}are the items of the list.{item_i}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{bulk_0}…{bulk_n}areIntthat represent how many times that item should be repeated in the expanded list.
Set
A collection that contains no duplicate elements.
Format: Same as List.
Map
A dictionary of keys to values. A {value_flag} equal to 0x02 means that the map is ordered.
Format: {length}{item_0}…{item_n}
Where:
-
{length}is anIntdescribing the length of the map. -
{item_0}…{item_n}are the items of the map.{item_i}is sequence of 2 fully qualified typed values one representing the key and the following representing the value, each composed of{type_code}{type_info}{value_flag}{value}.
UUID
A 128-bit universally unique identifier.
Format: 16 bytes representing the uuid.
Example
-
00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff: Uuid 00112233-4455-6677-8899-aabbccddeeff.
Edge
Format: {id}{label}{inVId}{inVLabel}{outVId}{outVLabel}{parent}{properties}
Where:
-
{id}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{label}is aList{value}. -
{inVId}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{inVLabel}is aList{value}. -
{outVId}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{outVLabel}is aList{value}. -
{parent}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}which contains the parentVertex. Note that as TinkerPop currently send "references" only, this value will always benull. -
{properties}is aListofPropertyobjects.
Example values:
01 00 00 00 00 0d id is 13
00 00 00 01 03 00 00 00 00 08 64 65 76 65 6c 6f 70 73 label is a size 1 list with string 'develops'
01 00 00 00 00 0a inVId is 10
00 00 00 01 03 00 00 00 00 08 73 6f 66 74 77 61 72 65 inVLabel is a size 1 list with string 'software'
01 00 00 00 00 01 outVId is 1
00 00 00 01 03 00 00 00 00 06 70 65 72 73 6f 6e outVLabel is a size 1 list with string 'person'
fe 01 parent is always null
09 00 00 00 00 01 properties is a size 1 list
0f 00 00 00 00 05 73 69 6e 63 65 01 00 00 00 07 d9 fe 01 property with key 'since' and value 2009 and null parentPath
Format: {labels}{objects}
Where:
-
{labels}is a fully qualifiedListin which each item is a fully qualifiedSetofString. -
{objects}is a fully qualifiedListof fully qualified typed values.
Property
Format: {key}{value}{parent}
Where:
-
{key}is aStringvalue. -
{value}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{parent}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}which is either anEdgeorVertexProperty. Note that as TinkerPop currently sends "references" only this value will always benull.
Graph
A collection of vertices and edges. Note that while similar the vertex/edge formats here hold some differences as
compared to the Vertex and Edge formats used for standard serialization/deserialiation of a single graph element.
Format: {vlength}{vertex_0}…{vertex_n}{elength}{edge_0}…{edge_n}
Where:
-
{vlength}is anIntdescribing the number of vertices. -
{vertex_0}…{vertex_n}are vertices as described below. -
{elength}is anIntdescribing the number of edges. -
{edge_0}…{edge_n}are edges as described below.
Vertex Format: {id}{label}{plength}{property_0}…{property_n}
-
{id}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{label}is aStringvalue. -
{plength}is anIntdescribing the number of properties on the vertex. -
{property_0}…{property_n}are the vertex properties consisting of{id}{label}{value}{parent}{properties}as defined inVertexPropertywhere the{parent}is alwaysnulland{properties}is aListofPropertyobjects.
Edge Format: {id}{label}{inVId}{inVLabel}{outVId}{outVLabel}{parent}{properties}
Where:
-
{id}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{label}is aStringvalue. -
{inVId}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{inVLabel}is alwaysnull. -
{outVId}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{outVLabel}is alwaysnull. -
{parent}is alwaysnull. -
{properties}is aListofPropertyobjects.
Vertex
Format: {id}{label}{properties}
Where:
-
{id}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{label}is aList{value}. -
{properties}is aListofVertexPropertyvalues.
Example values:
01 00 00 00 00 01 id is int 1
00 00 00 01 03 00 00 00 00 06 70 65 72 73 6f 6e label is size 1 list with string 'person'
09 00 00 00 00 01 12 00 02 00 00 00 00 00 00 00 00 09 properties is a size 1 list with VertexProperty id 9
00 00 00 01 03 00 00 00 00 08 6c 6f 63 61 74 69 6f 6e VertexProperty label is string 'location'
03 00 00 00 00 08 73 61 6e 74 61 20 66 65 VertexProperty value is string 'santa fe'
fe 01 VertexProperty parent is always null
09 00 00 00 00 01 VertexProperty has a size 1 list
0f 00 00 00 00 09 73 74 61 72 74 54 69 6d 65 metaproperty with string key 'startTime'
01 00 00 00 07 d5 fe 01 VertexProperty metaproperty value is 2005 with null parentVertexProperty
Format: {id}{label}{value}{parent}{properties}
Where:
-
{id}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{label}is aList{value}. -
{value}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. -
{parent}is a fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}which contains the parentVertex. Note that as TinkerPop currently send "references" only, this value will always benull. -
{properties}is aListofPropertyobjects.
Example values:
02 00 00 00 00 00 00 00 00 00 id is Long 0
00 00 00 01 03 00 00 00 00 04 6e 61 6d 65 label is size 1 list with string 'name'
03 00 00 00 00 05 6d 61 72 6b 6f value is string 'marko'
fe 01 parent is always null
09 00 00 00 00 00 metaproperties is empty listDirection
Format: a fully qualified single String representing the enum value.
Example values:
-
00 00 00 03 4F 55 54: OUT -
00 00 00 02 49 4E: IN
T
Format: a fully qualified single String representing the enum value.
Example values:
-
00 00 00 05 6C 61 62 65 6C: label -
00 00 00 02 69 64: id
BigDecimal
Represents an arbitrary-precision signed decimal number, consisting of an arbitrary precision integer unscaled value and a 32-bit integer scale.
Format: {scale}{unscaled_value}
Where:
-
{scale}is anInt. -
{unscaled_value}is aBigInteger.
BigInteger
A variable-length two’s complement encoding of a signed integer.
Format: {length}{value}
Where:
-
{length}is anIntdescribing the size of{value}in bytes. -
{value}is the two’s complement of theBigInteger.
Example values of the two’s complement {value}:
-
00: Integer 0. -
01: Integer 1. -
127: Integer 7f. -
00 80: Integer 128. -
ff: Integer -1. -
80: Integer -128. -
ff 7f: Integer -129.
Byte
Format: 1-byte two’s complement integer.
Example values:
-
01: 8-bit integer number 1. -
ff: 8-bit integer number -1.
Binary
Format: {length}{value}
Where:
-
{length}is anIntrepresenting the amount of bytes contained in the value. -
{value}sequence of bytes.
Short
Format: 2-byte two’s complement integer.
Example values:
-
00 01: 16-bit integer number 1. -
01 02: 16-bit integer number 258.
Boolean
Format: A single byte containing the value 0x01 when it’s true and 0 otherwise.
Tree
Format: {length}{item_0}…{item_n}
Where:
-
{length}is anIntdescribing the amount of items. -
{item_0}…{item_n}are the items of theTree.{item_i}is composed of a{key}which is a fully-qualified typed value followed by a{Tree}.
Marker
A 1-byte marker used to separate the end of the data and the beginning of the status of a ResponseMessage. This is
mainly used by language variants during deserialization.
Format: 1-byte integer with a value of 00.
CompositePDT
A composite custom type, represented as a type and a map of values.
Format: {type}{fields}
Where:
-
{type}is aStringcontaining the implementation specific text identifier of the custom type. -
{fields}is aMaprepresenting the fields of the composite type.
Example values:
03 00 00 00 00 05 50 6F 69 6E 74: the string "Point"
0A 00 00 00 00 02 31 30: length 2 map header
03 00 00 00 00 01 78 01 00 00 00 00 01: {x:1}
03 00 00 00 00 01 79 01 00 00 00 00 02: {y:2}PrimitivePDT
A primitive custom type, represented as a type and the stringified value.
Format: {type}{value}
Where:
-
{type}is aStringcontaining the implementation specific text identifier of the custom type. -
{value}is aStringrepresenting the string version of the value.
Example values:
03 00 00 00 00 05 55 69 6E 74 38: the string "Uint8"
03 00 00 00 00 02 31 30: the string "10"Unspecified Null Object
A null value for an unspecified Object value.
It’s represented using the null {value_flag} set and no sequence of bytes (which is FE 01).
Char
Format: one to four bytes representing a single UTF8 char, according to the Unicode standard.
For characters 0x00-0x7F, UTF-8 encodes the character as a single byte.
For characters 0x80-0x07FF, UTF-8 uses 2 bytes: the first byte is binary 110 followed by the 5 high bits of the
character, while the second byte is binary 10 followed by the 6 low bits of the character.
The 3 and 4-byte encodings are similar to the 2-byte encoding, except that the first byte of the 3-byte encoding starts
with 1110 and the first byte of the 4-byte encoding starts with 11110.
Example values (hex bytes)
-
97: Character 'a'. -
c2 a2: Character '¢'. -
e2 82 ac: Character '€'
Duration
A time-based amount of time.
Format: {seconds}{nanos}
Where:
-
{seconds}is aLong. -
{nanos}is anInt.
Request and Response Messages
Request and response messages are special container types used to represent messages from client to the server and the other way around. These messages are independent from the transport layer.
Request Message
Represents a message from the client to the server.
Format: {version}{fields}{gremlin}
Where:
-
{version}is aByterepresenting the specification version, with the most significant bit set to one. For this version of the format, the value expected is0x84(10000004). -
{fields}is aMap. -
{gremlin}is aString.
The total length is not part of the message as the transport layer will provide it. For example: in HTTP, there is the
Content-Length header which defines the payload size.
Response Message
Format: {version}{bulked}{result_data}{marker}{status_code}{status_message}{exception}
Where:
-
{version}is aByterepresenting the protocol version, with the most significant bit set to one. For this version of the protocol, the value expected is0x84(10000004). -
{bulked}is aByterepresenting whether{result_data}is bulked.00is false and01is true. -
{result_data}is a sequence of fully qualified typed value composed of{type_code}{type_info}{value_flag}{value}. If{bulked}is01then each value is followed by an 8-byte integer denoting the bulk of the preceding value. -
{marker}is aMarker. -
{status_code}is anInt. -
{status_message}is a nullableString. -
{exception}is a nullableString.
The total length is not part of the message as the transport layer will provide it.