1 Introduction

neo4cl - a CL library for interacting with Neo4J

Short description:

From the Neo4J website: "Neo4j is a highly scalable native graph database."

Graph databases emphasise the relationships between things, and the information to be found there, in contrast to the relational focus on the things themselves. They are typically much more flexible in their definitions of things than RDBMSes, which fits well with Lisp's fluid approach to functionality.

Neo4J is a very popular graph database that scales well. It implements a property graph, which means you can assign attributes to relationships as well as to nodes, and its query language (Cypher) is very expressive. It's an excellent transactional database which satisfies the ACID model, in contrast to something like RDF, which is better suited to data warehousing where responsiveness is traded off for more semantic richness.

Neo4CL is very simple library that sends Cypher queries to a Neo4J server, and decodes the responses into something useful for processing in CL. The queries and their responses take the form of alists. This library aims at compliance with Neo4J 3.0 via the HTTP API, based on the documentation in the Neo4J developer manual, and is intended as something to build applications on, more than for interactive use.

What it does

transforms alists into queries, sends them to a Neo4J server, and returns its responses as alists

very basic error reporting

What it doesn't do

anything involving Cypher itself. It forwards the query string, and assumes the server will know what to do with it.

the BOLT protocol. This may be added in the future.

any kind of object-graph mapping.

What it runs on

It's been tested so far on

sbcl

ccl

ccl64

Dependencies

All available via Quicklisp:

drakma

cl-ppcre

cl-json

flexi-streams

cl-base64

How it works

It's organised around a neo4j-rest-server object, which holds the details needed for connecting to a Neo4J server. Its initargs and defaults are:

:protocol - default = "http", but can be whatever Drakma will accept

:hostname - default = "localhost"

:port - default = 7474

:dbuser - default = "neo4j"

:dbpasswd - default = "neo4j"

It comes with a basic test-suite, in the package neo4cl-test, which requires the FiveAM framework.

Example usage:

We'll assume it's a default installation of Neo4J, so it's listening on http://localhost:7474, and the username and password are both 'neo4j'.

5.1 Exported definitions

5.1.1 Functions

Function: change-passwordSERVER NEW-PASSWORD

Change a Neo4J user’s password.
If the db operation is successful, update the server object so that this takes immediate effect within this server.
NB: remember to update whatever you’re using to initialise your db connection.

Execute one or more Cypher statements, wrapped in a transaction.
For now, we’re simply issuing all statements in a batch and then committing, instead of building it up over several HTTP requests.
Sample input:
’((:statements
((:statement . "MATCH (n:User {properties} ) RETURN n")
(:parameters (:properties (:name . "bob"))))))
If an error is detected, it will be signalled with whatever information was provided by Neo4J

5.2.1 Functions

Authenticate to the Neo4J server and confirm the status of the database user.
200/OK means the credentials are good.
401/Unauthorized means they’re not.
The presence of (:PASSWORD–CHANGE–REQUIRED . T) in the body of the reply, well, you get the hint.

Store something in Neo4j via the legagy Cypher API.
Expects content in the form of a list of lists, as input to cl-json:encode-json-alist-to-string.
DEPRECATED: use neo4j-transaction instead, unless you have a specific reason not to.