Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

A guest post from Nigel Small, whose current areas of interest include Python, JavaScript, PostgreSQL, Neo4j and Linux. He has also founded a number of open source projects, most significantly py2neo, and is an active blogger, speaker and Neo4j community member who can be reached at @technige.

Neo4j began life in the object-oriented, caffeine-laden world of Java, designed as a data store to be directly embedded within applications built upon the Java platform. Since then, support for other languages and platforms has been introduced and the Neo4j community has continued to grow more and more technology agnostic. Bindings now exist for .NET, Ruby, Python, Node.js and PHP, among others. So, no matter what the project, there’s no excuse for not diving into Neo4j.

This article focuses on Python — a language whose philosophy is considerably different from that of Java — and shows how the Py2neo library can be used to build a simple application.

A quick REST

But first, a few basics. None of the foreign language bindings could exist for Neo4j without its server API. This interface exposes a set of RESTful web services with a JSON-based message format and a comprehensive discovery mechanism. The quickest and easiest way to see this interface in action is by using cURL:

The JSON object returned from this endpoint contains a set of resource names and the URIs under which they can be found. The cypher endpoint, for example, accepts Cypher queries POSTed within a message payload and it executes these queries, returning the results in the HTTP response.

It is this REST API interface that has made it possible to build the wide variety of Neo4j drivers now available. Py2neo provides a light wrapper around these REST resources, which then allows Python application developers to use Neo4j without having to worry about the underlying client-server protocol.

A Simple Application

To demonstrate Py2neo in action, we are going to look at building a simple contact management system for storing names and email addresses. We will naturally use nodes to model each of these entities, but it is important to remember that Neo4j has no concept of type. Type is instead inferred from the surrounding relationships and properties.

The diagram below shows person nodes in red and email address nodes in blue. These are of course purely logical interpretations of the nodes, however, and the database itself is unaware of the distinction.


Our application will fulfill two functions: addition of new contact information and retrieval of a full list of contacts. For this, we will create a Person class that wraps a Py2neo Node object. This allows us to maintain a handle to the underlying implementation, while exposing user-level functionality. The root node in the diagram above refers to a fixed reference point in the graph from which we can begin navigation.

Let’s dive straight into some code. A full mini-application is listed below. This constructs a command line tool that allows adding new named contacts with one or more email addresses and also provides a facility to list these contact details. Running the script without arguments shows the usage patterns and the only dependency required is a local, unmodified instance of Neo4j.

The first piece of Py2neo-specific code is on line 09 and creates a GraphDatabaseService object. Through this, we get access to most of the functionality provided by the Neo4j server. Optionally, a URI can be passed to the constructor, although when none is provided, the local default is used instead. This means that the following two lines are directly equivalent:

Line 13 introduces a call to get_or_create_indexed_node, which provides a neat way to create a fixed reference point within the graph. Traditional Neo4j indexing allows nodes and relationships to be accessed via a key-value pair and, in this code, we are using an entry in the reference index with a key of contacts and a value of root. On first execution, a new node will be created, and on subsequent executions, it will be reused.

On line 17, we see the recommended notation for node and relationship abstracts as well as the create method that accepts and uses them. Any number of abstracts can be passed into this method and the entities are built within a single batch transaction and returned as a list in the same order they were specified. Abstract nodes are denoted by the node function and take a set of properties, whereas abstract relationships use the rel function and accept a start node, type and end node. When in a context with other abstracts, relationship start and end nodes may be integers referring to other nodes within that batch. In the case of our example, we are connecting the root node to the newly created person node, otherwise known as item 0.

We encounter relationships again on lines 24 and 38, this time in the form of the match method. This attempts to identify any relationships that fulfill a specified set of criteria and return them in a list. In these cases, the relationships matched are PERSON relationships, starting at the root node and EMAIL relationships starting from a given person node. For those familiar with Cypher, this uses a query containing the MATCH keyword behind the scenes.

The last point to note in the code above is the simple way by which node properties can be accessed. Py2neo overrides the standard python __getitem__ and __setitem__ methods to allow easy access to any property via square bracket notation. This can be seen on lines 34 and 38.


And there we have it. This shows how quick and easy it is to put together a Neo4j application outside of a Java environment and how Py2neo abstracts away most of the heavy lifting via the REST API. The example here does not deal with uniqueness although facilities are provided for both unique indexing and the Cypher CREATE UNIQUE statement. Django developers may also want to consider a layer such as Neomodel, which presents a Djangoesque ORM-style layer on top of Py2neo.

See below for sections covering Neo4j in resources from Safari Books Online.

Safari Books Online has the content you need

Spring Data shows you how Spring Data makes it relatively easy to build applications across a wide range of new data access technologies such as NoSQL and Hadoop. Read Neo4j: A Graph Database for some details on the graph database.
Cassandra: The Definitive Guide provides you with all of the details and practical examples you need to understand Cassandra’s non-relational database design and put it to work in a production environment.
Spring in Practice shows you how to tackle the challenges you face when you build Spring-based applications. The book empowers software developers to solve concrete business problems by mapping application-level issues to Spring-centric solutions. Read Creating a simple configuration item for more on Neo4j.

About the author

small Nigel began programming at an early age and has worked professionally in a variety of computing roles for over 15 years. His current areas of interest include Python, JavaScript, PostgreSQL, Neo4j and Linux. He has also founded a number of open source projects, most significantly py2neo, and is an active blogger, speaker and Neo4j community member and can be reached at @technige.

Tags: .NET, cURL, Cypher, Django, JSON, Neo4j, Node.js, php, Python, REST, Ruby,

Comments are closed.