Guidelines for Building a Neo4j Application
From Neo4j Wiki
The goal of this document is to provide a condensed set of guidelines for people who are familiar with the basics of Neo4j, but don't feel entirely confident on how to put their skills to use in a real-world application. It works on a macro- rather than a micro scale and tries to convey a mindset rather than specific details. If you want code-level patterns, see the HOWTOs.
Please note that this is a very early draft version that is no more than half done. In the near future, we're going to make a real effort to shape up our documentation, including this guide. Until then, your best bet is to read through whatever is here, then check out the Design Guide.
Contents |
[edit] Mindset
Like most (all?) programmers today, you were probably born and raised in an RDBMS world. Having been fostered in a world where the bottom layer of all architectural diagrams is the "SQL sink," you most likely carry with you a number of assumptions. The challenge is to let go of those hidden assumptions as you now work with an architecture without a 35 year old legacy. This section includes a set of guidelines that we hope will make this easier.
[edit] Focus on the domain model
The first thing to keep in mind as you start a Neo4j project is to focus on the domain model. Step up to the white board, forget UML and E/R diagrams and just draw a conceptual model of your project's domain. For example, to the right is a conceptual model of one day in the life of our good friend Björn's. You can see from the white board that he owns a car, which he uses to drive his kids and groceries to the daycare. (No, we don't know why he supplies the daycare with groceries.)
When you have a first draft of your domain model, you'll notice how easy it is to represent it in the graph. Take a look at the graph to the right. It is in fact quite similar to the scribbles on the white board. Over the past five years, we've built a lot of applications on top of Neo4j and we've noticed that it's usually trivial to go from a domain model to a representation in the graph: all entities and their relationships from your white board are explicit in the graph (as either nodes, relationships or properties). We call this white board friendly.
So focus on the domain model. Go directly to a graph representation. And then build an object-oriented domain layer on top of the graph.
[edit] Assume the graph is always in memory (Neo4j will make it so)
With legacy architectures, there's usually a serialization stage between your domain model and its persistent state in the storage backend. In raw JDBC applications, you serialize your OO classes to strings that you send over the wire. In EJB applications, you use DTOs as data capsules to/from the entity layer. In other frameworks, there's commonly a load/store pattern where you first load an entity from the store, perform some operations on it and then store it back.
With Neo4j, forget all about that. You have a domain layer on top of the graph (see below for some pointers on that). Each domain entity typically wraps a node (or a relationship) and when you're implementing that class your mindset should be that you're working with an in-memory data structure. There's no need to load/store anything, and no need to inject data from the graph into DTOs. There's no state in your domain layer. Each entity simply wraps a node, to which it forwards all data handling requests (typically getters and setters). Your domain layer is an adaptation of the generic graph to a type safe, object-oriented abstraction expressed in the vocabulary of your domain.
[edit] Assume everything's automatically persistent (Neo4j will make it so)
This is a corollary to the previous guideline. When you implement your domain model, your focus should be on reading and writing data to the graph in a transactional context. The transactions are logically demarcated to follow business operations and state is shared through the graph. As a side effect, everything is persistent with proper ACID semantics. You don't ever have to worry about explicitly instructing Neo4j to store anything.
