Fluent API queries

(a.k.a. Gremlin Language Variant - with extensions)

The DSE Java driver provides utilities to create a GraphStatement out of the popular open-source graph computing framework Apache TinkerPop. The query language for Apache Tinkerpop is called Gremlin and it is defined by a set of functions and variables defined in the Traversal API.

The Traversal API is a set of functions that define a Gremlin traversal, the graph operation to execute. In the DSE Java driver a traversal is considered like a query, that can be wrapped inside a GraphStatement.

Here’s how to create a GraphStatement out of a Apache TinkerPop Traversal:

// traversal() returns a dummy GraphTraversalSource that is not meant to be iterated itself
GraphTraversalSource g = DseGraph.traversal();
GraphTraversal traversal = g.V().has("name", "marko"); // Java-based Gremlin Traversal API, more comfortable than a String query

GraphStatement graphStatement = DseGraph.statementFromTraversal(traversal);

Executing a GraphStatement is explained in the statement execution section.

Note: using the Fluent API (and the DseGraph class) requires adding the module dse-java-driver-graph as a dependency. It can be found on Maven as:

<dependency>
    <groupId>com.datastax.dse</groupId>
    <artifactId>dse-java-driver-graph</artifactId>
    <version>1.9.0</version>
</dependency>

Gremlin Domain Specific Languages

The Gremlin language can be extended to match a user’s specific use cases and make the development of graph traversals easier. Doing so would require a GraphTraversal class that exposes their domain-specific grammar and methods and need this new grammar via the Fluent API.

As of DSE Java driver 1.4.0, the DseGraph class exposes additional utilities to create a traversal source equipped with custom user-defined traversal methods easily.

After generating a custom GraphTraversalSource as explained in the TinkerPop documentation, users may use it directly to create a GraphStatement out of a traversal. Here’s an example using GraphStatements:

// see TinkerPop documentation link for the generation of SocialTraversalSource
SocialTraversalSource gSocial = DseGraph.traversal(SocialTraversalSource.class);

GraphStatement gs = DseGraph.statementFromTraversal(gSocial.persons("marko").knows("vadas"));

DSE Search Text and Geo Gremlin predicates

For ease of use, DSE Search and Geo predicates are directly integrated and provided in the Fluent API.

Here’s an example allowing to use DSE Search to do an index search on a text field:

GraphTraversalSource g = DseGraph.traversal();
GraphTraversal traversal = g.V().has("textProp", Search.tokenPrefix("1")).next();

GraphStatement graphStatement = DseGraph.statementFromTraversal(traversal);

Or here is how to use the Geo class to do location-based traversals using DSE Search Geo indexing features:

GraphTraversalSource g = DseGraph.traversal();

Point center = Geo.point(12, 14);
double radius = 3;
GraphTraversal traversal = g.V().has("point", Geo.inside(center, radius));

GraphStatement graphStatement = DseGraph.statementFromTraversal(traversal);

Please check out the Javadocs of the Geo and Search classes to see all the available predicates.

Batch mutations with the Fluent API

The DSE Java driver allows to batch multiple graph updates inside a single transaction via the Fluent API.

To do so, the DseGraph class is necessary to create a TraversalBatch object. This object will be the holder of all the graph mutations the user wishes to apply within the same transaction.

All operations will be applied if the execution completes successfully or none if any of the operation fails.

Once the TraversalBatch instance has been successfully populated with the desired traversal mutations, the TraversalBatch needs to be converted into a GraphStatement to be executed on the DseSession, with the instance method TraversalBatch#asGraphStatement(). Then on the created GraphStatement, all the usual Graph options will be available.

Here’s a code example:

GraphTraversalSource g = DseGraph.traversal();
TraversalBatch batch = DseGraph.batch();
// Add two vertices
batch.add(g.addV("person").property("name", "batch1").property("age", 1));
batch.add(g.addV("person").property("name", "batch2").property("age", 2));
// Add an edge between
batch.add(g.V().has("name", "batch1").as("v1").V().has("name", "batch2").addE("knows").from("v1").property("weight", 2.3f));
GraphStatement statement = batch.asGraphStatement(); 
statement.setConsistencyLevel(ConsistencyLevel.LOCAL_ONE);

It is also possible to add a TraversalBatch to another, via the TraversalBatch#addAll method.

Check out the Java doc of the DseGraph.batch() method for more information.

The TraversalBatch feature is only usable against DSE 6.0+.

Prepared statements

Prepared graph statements are not supported by DSE yet (they will be added in the near future).