Object Model

Let’s consider the example of theperson vertex, taken from the "modern" and "the crew" graphs defined in theTinkerFactory.In our object world, it would be defined as aPerson class that extendsVertex.By default, the vertex’s label matches its simple class name, hence we have to un-capitalize it using the@Alias annotation.

The person’sname andage properties become primitive fields in the class.The@PrimaryKey and@OrderingKey annotations on them not only indicate that they are mandatory,but also allow theperson to be found easily through theHasKeys.of(person)SubTraversal.Think of theSubTraversal as a reusable function that takes aGraphTraversal, performs a few steps on it, and returns it back (to allow for chaining).TheKnowsPeople field in this class is an example of an in-lineSubTraversal, albeit a stronger-typed version of it calledToVertex, to indicate that it ends up selecting vertices.Note that these traversal functions are not stored in the graph.

Next, we look at itstitles field, which is defined to be aSet.As you might expect, the cardinality of the underlying property becomesset.Similarly, thelocations field takes on thelist cardinality.Further, each element in thelocations list has it’s own meta-properties, and ergo deserves aLocation class of it’s own.

An edge is defined much like the vertex, except it extends theEdge class.By default, an edge’s label is it’s un-capitalized simple class name, and hence no@Alias is needed:

You can find more examples of gremlin object verticeshere and edgeshere.

Updating Objects

TheGraph interface lets you update the graph usingVertex orEdge objects.You can get it via dependency injection, assuming you’ve anObject provider forGraphTraversalSource:

Or, the good old fashioned way, using theGraphFactory:

Now that we know how to obtain aGraph instance, let’s see how to change it usingJava objects.Here, we createsoftware vertices fortinkergraph andgremlin, and add atraverses edge fromgremlin totinkergraph.

Below, aperson vertex containing a list oflocations is added, along with three outgoing edges.

To see how themodern and thecrew reference graphs may be created using the objectGraph interface, gohere.

Querying Objects

There are two ways to get a handle to theQuery interface.You can inject it like so:

Otherwise, you can create it using theGraphFactory like so:

Next, let’s see how to use theQuery interface.The following snippet queries the graph by chaining twoSubTraversals (a function denoting a partial traversal), and parses the result into a list ofPerson vertices.

Below, we query by anAnyTraversal (a function on theGraphTraversalSource), and get a singlePerson back.

The type of the result may be primitives too, and that is handled as shown below.

Last, we show a traversal involving select steps, which requires special handling as it may return a map.

To see more examples showcasing how the objectQuery interface may be used, gohere.

Service Provider Interface

A provider that wishes to plug intogremlin-objects through dependency injection, will need to provide aGraphTraversalSource of it’s choice, through theObject qualifier.For users that don’t use dependency injection, they may manually pass theGraphTraversalSource to theGraphFactory.

Registering Native Types

Typically, gremlin property values are Java primitives.Sometimes, a provider treats a custom type as a primitive.For instance,DataStax lets you define property keys of the primitive geometric typePoint.Such types can be registered using thePrimitives#registerPrimitiveClass methods.

Registering Custom Parsers

When aGraphTraversal is completed, it usually returns (a list of) gremlinElement(s).However, when some providers execute a traversal, the result comprises custom element types.For instance, whenDataStax executes a graph query, it returns a result set made up ofGraphNode(s), a proprietary element type.We give such providers a way to tell us how to parse such custom elements using theParsers#registerElementParser method.

GremlinDsl Traversals

Thegremlin-core module defines aGremlinDsl annotation that lets you define custom traversals by extending theGraphTraversal andGraphTraversalSource.However, it requires some familiarity ofgremlin-core internals.

Peopod for Tinkerpop 3

Peopod represents elements as annotated interfaces or abstract classes.While it generates boilerplate for traversals to adjacent vertices, it doesn’t let you co-locate arbitrary traversals.This library is less intrusive and more flexible.

User Defined Steps

An older version of TinkerPop allowed you to define custom steps usingClosures, not unlike theAnyTraversal andSubTraversal functions.However, they aren’t as developer friendly as the functional interfaces provided here.Moreover, it doesn’t allow for co-locating the traversal logic along with the element model, as we do here.

Language Variants

The concept of lifting the property graph into objects is language-independent.To quote the TinkerPop docs, "with JSR-223, any language compiler written for the JVM can directly access the JVM and any of its libraries", and that would includegremlin-objects.For GLVs not written for the JVM, it can be ported over as long as it supports basic reflection.Case in point, the Gremlin-Python variant could achieve the object mapping through thedir,getattr andsetattr built-in functions.

Provider Support

In reality, it is fairly easy for a provider to plug-intogremlin-objects simply by supplying aGraphTraversalSource of their choosing.The ability to register custom primitive types and traversal result parsers allows for further customization.Sinceneo4j already has it’s ownNeo4jGraph, it’s a good candidate to become the next test case.

DataFrame Support

Some providers useGraphFrames to execute bulk operations and graph algorithms on top of Tinkerpop.Assuming they can work withDataFrames, one could build aGraphTraversalSource,which translates the objectGraph andQuery operations intoDataFrame tables, and adapt’s it to the provider’sGraphFrame.

Traversal Storage

TheAnyTraversal andSubTraversalinterfaces extendFormattable so that the steps defined in it’s body can be revealed.Let’s say that we stored the bytecode of these types of functional fields as a hidden property in the element.That could potentially allow us to executeuser defined traversals using a, say,traversal.call('function-name') step.