A graph database is a storage engine that is specialized in storing and retrieving vast networks of data. It efficiently stores nodes and relationships and allows high performance traversal of those structures. Properties can be added to nodes and relationships.

Graph databases are well suited for storing most kinds of domain models. In almost all domains, there are certain things connected to other things. In most other modeling approaches, the relationships between things are reduced to a single link without identity and attributes. Graph databases allow to keep the rich relationships that originate from the domain, equally well-represented in the database without resorting to also modeling the relationships as "things". There is very little "impedance mismatch" when putting real-life domains into a graph database.

Neo4j is a NOSQL graph database. It is a fully transactional database (ACID) that stores data structured as graphs. A graph consists of nodes, connected by relationships. Inspired by the structure of the human mind, it allows for high query performance on complex data, while remaining intuitive and simple for the developer.

Neo4j has been in commercial development for 10 years and in production for over 7 years. Most importantly it has a helpful and contributing community surrounding it, but it also:

In addition, Neo4j has ACID transactions, durable persistence, concurrency control, transaction recovery, high availability, and more. Neo4j is released under a dual free software/commercial license model.

The API of org.neo4j.graphdb.GraphDatabaseService provides access to the storage engine. Its features include creating and retrieving nodes and relationships, managing indexes (via the IndexManager), database life cycle callbacks, transaction management, and more.

The EmbeddedGraphDatabase is an implementation of GraphDatabaseService that is used to embed Neo4j in a Java application. This implementation is used so as to provide the highest and tightest integration with the database. Besides the embedded mode, the Neo4j server provides access to the graph database via an HTTP-based REST API.

Using the API of GraphDatabaseService, it is easy to create nodes and relate them to each other. Relationships are typed. Both nodes and relationships can have properties. Property values can be primitive Java types and Strings, or arrays of both. Node creation and modification has to happen within a transaction, while reading from the graph store can be done with or without a transaction.

GraphDatabaseService graphDb = new EmbeddedGraphDatabase( "helloworld" );
Transaction tx = graphDb.beginTx();
try {
	Node firstNode = graphDb.createNode();
	firstNode.setProperty( "message", "Hello, " );
	Node secondNode = graphDb.createNode();
	secondNode.setProperty( "message", "world!" );

	Relationship relationship = firstNode.createRelationshipTo( secondNode,
		DynamicRelationshipType.of("KNOWS") );
	relationship.setProperty( "message", "brave Neo4j" );
	tx.success();
} finally {
	tx.finish();
}

Getting a single node or relationship and examining it is not the main use case of a graph database. Fast graph traversal of complex, interconnected data and application of graph algorithms are. Neo4j provides a DSL for defining TraversalDescriptions that can then be applied to a start node and will produce a lazy java.lang.Iterable result of nodes and/or relationships.

TraversalDescription traversalDescription = Traversal.description()
   .depthFirst()
   .relationships(KNOWS)
   .relationships(LIKES, Direction.INCOMING)
   .evaluator(Evaluators.toDepth(5));
for (Path position : traversalDescription.traverse(myStartNode)) {
   System.out.println("Path from start node to current position is " + position);
}

The best way for retrieving start nodes for traversals and queries is by using Neo4j's integrated index facilities. The GraphDatabaseService provides access to the IndexManager which in turn provides named indexes for nodes and relationships. Both can be indexed with property names and values. Retrieval is done with query methods on indexes, returning an IndexHits iterator.

Spring Data Neo4j provides automatic indexing via the @Indexed annotation, eliminating the need for manual index management.

IndexManager indexManager = graphDb.index();
Index<Node> nodeIndex = indexManager.forNodes("a-node-index");
Node node = ...;
Transaction tx = graphDb.beginTx();
try {
    nodeIndex.add(node, "property","value");
    tx.success();
} finally {
    tx.finish();
}
for (Node foundNode : nodeIndex.get("property","value")) {
    // found node
}

Neo4j provides a graph query language called "Cypher" which draws from many sources. It resembles SQL but with an iconic representation of patterns in the graph (concepts drawn from SPARQL). The Cypher execution engine was written in Scala to leverage the high expressiveness for lazy sequence operations of the language and the parser combinator library. A screencast explaining the possibilities in detail can be found on the Neo4j video site.

Cypher queries always begin with a start set of nodes. Those can be either expressed by their IDs or by an index lookup expression. Those start-nodes are then related to other nodes in the match clause. Start and match clauses can introduce new identifiers for nodes and relationships. In the where clause additional filtering of the result set is applied by evaluating expressions. The return clause defines which part of the query result will be available. Aggregation also happens in the return clause by using aggregation functions on some of the values. Sorting can happen in the order by clause and the skip and limit parts restrict the result set to a certain window.

Cypher can be executed on an embedded graph database using an ExecutionEngine and CypherParser. This is encapsulated in Spring Data Neo4j with CypherQueryEngine. The Neo4j-REST-Server comes with a Cypher-Plugin that is accessible remotely and is available in the Spring Data Neo4j REST-Binding.

// Actors who played a Matrix movie:
start movie=node:Movie("title:Matrix*") match movie<-[:ACTS_IN]-actor
    return actor.name, actor.birthplace?

// User-Ratings:
start user=node:User(login='micha') match user-[r:RATED]->movie where r.stars > 3
    return movie.title, r.stars, r.comment

// Mutual Friend recommendations:
start user=node:Micha(login='micha') match user-[:FRIEND]-friend-[r:RATED]->movie where r.stars > 3
    return friend.name, movie.title, r.stars, r.comment?

// Movie suggestions based on a movie:
start movie=node:Movie(id='13') match (movie)<-[:ACTS_IN]-()-[:ACTS_IN]->(suggestion)
    return suggestion.title, count(*) order by count(*) desc limit 5

// Co-Actors, sorted by count and name of Lucy Liu
start lucy=node(1000) match lucy-[:ACTS_IN]->movie<-[:ACTS_IN]-co_actor
    return count(*), co_actor.name order by count(*) desc,co_actor.name limit 20

// Recommendations including counts, grouping and sorting
start user=node:User(login='micha') match user-[:FRIEND]-()-[r:RATED]->movie
    return movie.title, AVG(r.stars), count(*) order by AVG(r.stars) desc, count(*) desc

Gremlin is an expressive Groovy DSL developed by Marko Rodriguez as part of the Tinkerpop stack. It builds on top of a pipe implementation (Blueprints Pipes) that uses connected operations to traverse a graph. Gremlin has a concise syntax but is Turing complete.

Gremlin can be executed by including the Tinkerpop and Blueprints dependencies and then requesting a ScriptEngine of type "gremlin" from the javax.Script* facilities. In Spring Data Neo4j this is encapsulated in GremlinQueryEngine. The Neo4j-REST-Server also comes with a Gremlin-Plugin that is accessible remotely and is available in the Spring Data Neo4j REST-Binding.

// Vertex with id 1
v = g.v(1)

// determine the name of the vertices that vertex 1 knows and that are older than 30 years of age
v.outE{it.label=='knows'}.inV{it.age > 30}.name

// calculate basic collaborative filtering for vertex 1
m = [:]
g.v(1).out('likes').in('likes').out('likes').groupCount(m)
m.sort{a,b -> a.value <=> b.value}