h1. Introduction

Pilot is a graph database operator that allows you to perform common application-level operations on graph databases without delving into the details of their implementation or requiring knowledge of the component technologies. Pilot aims to support graph databases conforming to the "property graph model":http://github.com/tinkerpop/gremlin/wiki/Defining-a-Property-Graph. Pilot employs technologies from the "Tinkerpop":http://www.tinkerpop.com stack -- specifically "Blueprints":http://blueprints.tinkerpop.com and "Gremlin":http://gremlin.tinkerpop.com -- for general access and manipulation of the underlying graph database, but also uses native graph database APIs to further optimize performance for certain operations. In addition, Pilot also handles multithreading and transaction management, while keeping all of these abstracted away from the calling application. As such, Pilot is ideally suited for use in concurrent web applications.

• Supported graph database providers: ** "OrientDB":http://www.orientechnologies.com ** "Neo4j":http://neo4j.org ** "Tinkergraph":https://github.com/tinkerpop/blueprints/wiki/TinkerGraph (the Blueprints in-memory reference implementation) ** (others may be added in future if there is demand)

• Some of the functionality currently supported by Pilot include: ** Get edges between given vertices ** Get neighbors of a given vertex ** Retrieving vertices corresponding to some properties (see Property Graph Model) ** Transaction management ** Thread synchronization for multithreaded access ** Large commit optimization ** Application profiling

• Planned additions: ** Support for "Furnace":https://github.com/tinkerpop/furnace/wiki ** FOAF(n) ** DFS ** BFS

h1. Using Pilot

To use Pilot in your project, simply drop the JAR into your project or system classpath.

To build the JAR using "Maven":http://maven.apache.org (recommended):

Clone the repository on your machine

In the root folder, type 'mvn clean install'

Once the build completes, copy the JAR file in the target/ folder into your system or project classpath location

You can now use Pilot in your project by adding the import 'import com.countvajhula.pilot.*'

To create the JAR manually from source (you will need to have the dependencies -- Blueprints, Neo4j, OrientDB, Gremlin -- already present in your system classpath):

Clone the repository on your machine

Go to the folder /src which contains the Pilot Groovy source files

Type 'groovyc *.groovy' -- this will create a directory structure com/countvajhula/pilot in the current directory

Now type 'jar -cf pilot.jar com/countvajhula/pilot/*.class' -- this will create the file 'pilot.jar' in the current directory

Copy this JAR into a system classpath location

Now you can use Pilot in your project by adding the import 'import com.countvajhula.pilot.*'

h1. Examples

h3. Initializing a graph

GraphInterface myGraph = GraphManagerProxy.initializeGraph('/Users/sid/graph/mygraphdb1', GraphInterface.GraphProvider.ORIENTDB, false) //the read-only flag will be removed in a future version

h3. Miscellaneous operations

After initializing the graph, all operations defined in GraphInterface.groovy can be used by calling the methods on this GraphInterface instance (API is similar to the Blueprints Graph interface API): Vertex v1 = myGraph.addVertex() myGraph.setElementProperty(v1, 'name', 'Sid') Vertex v2 = myGraph.addVertex() myGraph.setElementProperty(v2, 'name', 'Dan') Edge ee1 = myGraph.addEdge(v1, v2, 'friends') myGraph.setElementProperty(ee1, 'since', 2007)

// retrieves the edge between v1 and v2 Edge ee2 = myGraph.getEdge(v1, v2, 'friends')

// get list of friends by name myGraph.getNeighbors(v1, 'friends', 'name')

h3. Transactions

myGraph.beginManagedTransaction()

//... // as many graph operations/mutations as you like //...

myGraph.concludeManagedTransaction()

h3. Profiling

GraphManagerProxy.startProfiler(myGraph, "Name-of-profile")

//... // whatever graph operations you want to profile //...

String results = GraphManagerProxy.stopProfiler(myGraph)

h1. Documentation

The "Wiki":https://github.com/countvajhula/pilot/wiki would be a good place to start. Also try the demo script "TestFlight.groovy":http://github.com/countvajhula/testflight for a working implementation of some of the features.