Performing Gremlin Queries

Neo4jClient exposes a rich set of interfaces for building and executing Gremlin based queries. As a fluent interface, performing Gremlin queries feels very similar to LINQ-to-Objects with the added power of the graph model.

If you're not already familiar with Gremlin, you should probably start by reading their documentation.

Accessing the Gremlin Interface

The entire Gremlin client implementation is done via extension methods in the Neo4jClient.Gremlin namespace. Before continuing with the samples on this page, ensure you have imported this namespace:

using Neo4jClient.Gremlin;

Basic Steps

All Gremlin queries initiate from a NodeReference. The graph client provides a reference to the well-known root node via the graphClient.RootNode property.

From there, C# queries look almost the same as their native Gremlin equivalents.

g.v(0).outE[[label:'FOO']].inV[[Bar:'baz']] could be implemented as:

var nodes = graphClient.RootNode.OutE("FOO").InV<MyNode>(n => n.Bar == "baz");
foreach (var node in nodes)
{
    Console.WriteLine(string.Format("Got node {0}", node.Reference.Id));
    // node.Data.Bar == "baz"
}

Deferred Execution

Similar to LINQ-to-Objects, all of the Gremlin client methods return either a scalar result or an enumerable. Methods that return a scalar result, such as GremlinCount, execute the query immediately. Methods that return an enumerable, such as InV and OutE execute the query when the result is enumerated.

Apply the same precautions and optimization that you would for other LINQ based providers.

In Combination With LINQ-to-Objects

Gremlin enumerables can be easily combined with LINQ-to-Objects methods.

For performance reasons, only use LINQ-to-Objects functionality where you are unable to achieve the same effect in the original Gremlin query.

Assuming this graph:

This query would retrieve all four nodes from neo4j, then filter them back to two in the .NET process (bad):

graphClient.RootNode.Out<Person>("KNOWS").Where(p => p.Sex == Sex.Male)

Alternatively, this query would only retrieve two nodes from neo4j (good):

graphClient.RootNode.Out<Person>("KNOWS", p => p.Sex == Sex.Male)

Count() vs GremlinCount()

For now, we only return basic enumerables. As a result, if you call Count() against a Gremlin result, .NET will be the one performing the count. Our client will retrieve all of the candidate nodes or relationships, then .NET will count them one at a time. This is obviously inefficient.

Instead, you should use the GremlinCount() method. Over the wire, this will be translated to Gremlin's native count() method and only that one scalar value will be returned.

In time we'll implement a full IQueryProvider and be able to intercept these types of calls.

Query Debugging

Predicate Encoding

Attached Node References

This revision is from 2012-02-12 07:25