The neo4cl Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The neo4cl Reference Manual

This is the neo4cl Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:19:26 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

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

What it doesn't do

What it runs on

It's been tested so far on

Dependencies

All available via Quicklisp:

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:

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'.

(defvar *server*
  (make-instance 'neo4cl:neo4j-rest-server))

;; First, we change the password.
;; It changes the password stored in *server* for you, so it continues to "just work."
(neo4cl:change-password *server* "foobar")

;; Create some bloke called Andre
(neo4cl:neo4j-transaction
 *server*
 `((:STATEMENTS
     ((:STATEMENT . "CREATE (n:Person { properties })")
      (:PARAMETERS .
       ((:properties . ((:name . "Andre")))))))))

;; This should return the following:
((:RESULTS ((:COLUMNS) (:DATA))) (:ERRORS))
200
"OK"

;; Is he there?
(neo4cl:neo4j-transaction
  *server*
  `((:STATEMENTS
      ((:STATEMENT . "MATCH (x:Person {name: 'Andre'}) RETURN x.name")))))

;; The result should look so:
((:RESULTS ((:COLUMNS "x.name") (:DATA ((:ROW "Andre") (:META NIL)))))
 (:ERRORS))
200
"OK"

;; We're bored with Andre; get rid of him
(neo4cl:neo4j-transaction
  *server*
  `((:STATEMENTS
      ((:STATEMENT . "MATCH (x:Person {name: 'Andre'}) DELETE x")))))

;; Finally, we should see this in response:
((:RESULTS ((:COLUMNS) (:DATA))) (:ERRORS))
200
"OK"

Error/condition handling

Three errors and one non-error condition are defined, following the Neo4J classifications:

They're further broken down into Category and Title, by simply splitting on the dot, and the Message is also included.

E.g, Neo.ClientError.Schema.ConstraintValidationFailed would be raised as

(error neo4cl:client-error
    :category "Schema"
    :title "ConstraintValidationFailed"
    :message "Node 126 already exists with label routers and property \"uid\"=[whitesands]")

The symbols category, title and message are exported so these fields can be read.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 neo4cl

Author

James Fleming <james@electronic-quill.net>

License

MIT license

Description

Basic library for interacting with Neo4J

Dependencies
Source

neo4cl.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 neo4cl.asd

Location

neo4cl.asd

Systems

neo4cl (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 neo4cl/package.lisp

Parent

neo4cl (system)

Location

package.lisp

Packages

neo4cl


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 neo4cl/neo4cl.lisp

Dependency

package.lisp (file)

Parent

neo4cl (system)

Location

neo4cl.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 neo4cl

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: change-password SERVER 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.

Package

neo4cl

Source

neo4cl.lisp (file)

Function: extract-data-from-get-request RESPONSE

Reach into the structure returned by a request that returns data, and return only the actual content.

Package

neo4cl

Source

neo4cl.lisp (file)

Function: extract-rows-from-get-request RESPONSE

Reach into the structure returned by a request that returns data,
and return only the actual content, in the form of a list of lists, each of the latter of which represents a row.

Package

neo4cl

Source

neo4cl.lisp (file)

Function: neo4j-transaction ENDPOINT STATEMENTS

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

Package

neo4cl

Source

neo4cl.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Generic functions

Generic Function: category CONDITION
Package

neo4cl

Methods
Method: category (CONDITION database-error)
Source

neo4cl.lisp (file)

Method: category (CONDITION transient-error)
Source

neo4cl.lisp (file)

Method: category (CONDITION client-notification)
Source

neo4cl.lisp (file)

Method: category (CONDITION client-error)
Source

neo4cl.lisp (file)

Generic Function: message CONDITION
Package

neo4cl

Methods
Method: message (CONDITION database-error)
Source

neo4cl.lisp (file)

Method: message (CONDITION transient-error)
Source

neo4cl.lisp (file)

Method: message (CONDITION client-notification)
Source

neo4cl.lisp (file)

Method: message (CONDITION client-error)
Source

neo4cl.lisp (file)

Generic Function: title CONDITION
Package

neo4cl

Methods
Method: title (CONDITION database-error)
Source

neo4cl.lisp (file)

Method: title (CONDITION transient-error)
Source

neo4cl.lisp (file)

Method: title (CONDITION client-notification)
Source

neo4cl.lisp (file)

Method: title (CONDITION client-error)
Source

neo4cl.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Conditions

Condition: client-error ()
Package

neo4cl

Source

neo4cl.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: category
Initargs

:category

Readers

category (generic function)

Slot: title
Initargs

:title

Readers

title (generic function)

Slot: message
Initargs

:message

Readers

message (generic function)

Condition: client-notification ()
Package

neo4cl

Source

neo4cl.lisp (file)

Direct superclasses

condition (condition)

Direct methods
Direct slots
Slot: category
Initargs

:category

Readers

category (generic function)

Slot: title
Initargs

:title

Readers

title (generic function)

Slot: message
Initargs

:message

Readers

message (generic function)

Condition: database-error ()
Package

neo4cl

Source

neo4cl.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: category
Initargs

:category

Readers

category (generic function)

Slot: title
Initargs

:title

Readers

title (generic function)

Slot: message
Initargs

:message

Readers

message (generic function)

Condition: transient-error ()
Package

neo4cl

Source

neo4cl.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: category
Initargs

:category

Readers

category (generic function)

Slot: title
Initargs

:title

Readers

title (generic function)

Slot: message
Initargs

:message

Readers

message (generic function)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: neo4j-rest-server ()

Neo4j REST API endpoint. Defines all the attributes needed for connecting to it.

Package

neo4cl

Source

neo4cl.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: protocol

String; the protocol by which we should connect to the Neo4J server. Default is ’http’, so you should only need to set this explicitly if you’re using HTTPS.

Initargs

:protocol

Initform

"http"

Readers

protocol (generic function)

Slot: hostname

String; the hostname to use when connecting to the Neo4J server. Defaults to ’localhost’.

Initargs

:hostname

Initform

"localhost"

Readers

hostname (generic function)

Slot: port

Integer; the port on which we connect to the Neo4J server. Defaults to 7474.

Initargs

:port

Initform

7474

Readers

port (generic function)

Slot: dbuser

Username with which we authenticate to the database.

Initargs

:dbuser

Initform

"neo4j"

Readers

dbuser (generic function)

Slot: dbpasswd

Password with which we authenticate to the database.

Initargs

:dbpasswd

Initform

"neo4j"

Readers

dbpasswd (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: decode-neo4j-json JSON

Parse the JSON returned by Neo4J into a CL structure

Package

neo4cl

Source

neo4cl.lisp (file)

Function: get-user-status SERVER

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.

Package

neo4cl

Source

neo4cl.lisp (file)

Function: neo4j-cypher-get-request ENDPOINT URI

Send a GET request to the legacy Cypher API, and return the parsed result. DEPRECATED: use neo4j-transaction instead, unless you have a specific reason not to.

Package

neo4cl

Source

neo4cl.lisp (file)

Function: neo4j-cypher-post-request ENDPOINT CONTENT &optional URI

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.

Package

neo4cl

Source

neo4cl.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Generic functions

Generic Function: base-url SERVER

Extract the base-url of a Neo4J server, from a neo4j-rest-server object.

Package

neo4cl

Source

neo4cl.lisp (file)

Methods
Method: base-url (SERVER neo4j-rest-server)
Generic Function: dbpasswd OBJECT
Package

neo4cl

Methods
Method: dbpasswd (NEO4J-REST-SERVER neo4j-rest-server)

Password with which we authenticate to the database.

Source

neo4cl.lisp (file)

Generic Function: dbuser OBJECT
Package

neo4cl

Methods
Method: dbuser (NEO4J-REST-SERVER neo4j-rest-server)

Username with which we authenticate to the database.

Source

neo4cl.lisp (file)

Generic Function: discover-rest-api ENDPOINT
Package

neo4cl

Methods
Method: discover-rest-api (ENDPOINT neo4j-rest-server)
Source

neo4cl.lisp (file)

Generic Function: hostname OBJECT
Package

neo4cl

Methods
Method: hostname (NEO4J-REST-SERVER neo4j-rest-server)

String; the hostname to use when connecting to the Neo4J server. Defaults to ’localhost’.

Source

neo4cl.lisp (file)

Generic Function: port OBJECT
Package

neo4cl

Methods
Method: port (NEO4J-REST-SERVER neo4j-rest-server)

Integer; the port on which we connect to the Neo4J server. Defaults to 7474.

Source

neo4cl.lisp (file)

Generic Function: protocol OBJECT
Package

neo4cl

Methods
Method: protocol (NEO4J-REST-SERVER neo4j-rest-server)

String; the protocol by which we should connect to the Neo4J server. Default is ’http’, so you should only need to set this explicitly if you’re using HTTPS.

Source

neo4cl.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   N  
Index Entry  Section

F
File, Lisp, neo4cl.asd: The neo4cl<dot>asd file
File, Lisp, neo4cl/neo4cl.lisp: The neo4cl/neo4cl<dot>lisp file
File, Lisp, neo4cl/package.lisp: The neo4cl/package<dot>lisp file

L
Lisp File, neo4cl.asd: The neo4cl<dot>asd file
Lisp File, neo4cl/neo4cl.lisp: The neo4cl/neo4cl<dot>lisp file
Lisp File, neo4cl/package.lisp: The neo4cl/package<dot>lisp file

N
neo4cl.asd: The neo4cl<dot>asd file
neo4cl/neo4cl.lisp: The neo4cl/neo4cl<dot>lisp file
neo4cl/package.lisp: The neo4cl/package<dot>lisp file

Jump to:   F   L   N  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   B   C   D   E   F   G   H   M   N   P   T  
Index Entry  Section

B
base-url: Internal generic functions
base-url: Internal generic functions

C
category: Exported generic functions
category: Exported generic functions
category: Exported generic functions
category: Exported generic functions
category: Exported generic functions
change-password: Exported functions

D
dbpasswd: Internal generic functions
dbpasswd: Internal generic functions
dbuser: Internal generic functions
dbuser: Internal generic functions
decode-neo4j-json: Internal functions
discover-rest-api: Internal generic functions
discover-rest-api: Internal generic functions

E
extract-data-from-get-request: Exported functions
extract-rows-from-get-request: Exported functions

F
Function, change-password: Exported functions
Function, decode-neo4j-json: Internal functions
Function, extract-data-from-get-request: Exported functions
Function, extract-rows-from-get-request: Exported functions
Function, get-user-status: Internal functions
Function, neo4j-cypher-get-request: Internal functions
Function, neo4j-cypher-post-request: Internal functions
Function, neo4j-transaction: Exported functions

G
Generic Function, base-url: Internal generic functions
Generic Function, category: Exported generic functions
Generic Function, dbpasswd: Internal generic functions
Generic Function, dbuser: Internal generic functions
Generic Function, discover-rest-api: Internal generic functions
Generic Function, hostname: Internal generic functions
Generic Function, message: Exported generic functions
Generic Function, port: Internal generic functions
Generic Function, protocol: Internal generic functions
Generic Function, title: Exported generic functions
get-user-status: Internal functions

H
hostname: Internal generic functions
hostname: Internal generic functions

M
message: Exported generic functions
message: Exported generic functions
message: Exported generic functions
message: Exported generic functions
message: Exported generic functions
Method, base-url: Internal generic functions
Method, category: Exported generic functions
Method, category: Exported generic functions
Method, category: Exported generic functions
Method, category: Exported generic functions
Method, dbpasswd: Internal generic functions
Method, dbuser: Internal generic functions
Method, discover-rest-api: Internal generic functions
Method, hostname: Internal generic functions
Method, message: Exported generic functions
Method, message: Exported generic functions
Method, message: Exported generic functions
Method, message: Exported generic functions
Method, port: Internal generic functions
Method, protocol: Internal generic functions
Method, title: Exported generic functions
Method, title: Exported generic functions
Method, title: Exported generic functions
Method, title: Exported generic functions

N
neo4j-cypher-get-request: Internal functions
neo4j-cypher-post-request: Internal functions
neo4j-transaction: Exported functions

P
port: Internal generic functions
port: Internal generic functions
protocol: Internal generic functions
protocol: Internal generic functions

T
title: Exported generic functions
title: Exported generic functions
title: Exported generic functions
title: Exported generic functions
title: Exported generic functions

Jump to:   B   C   D   E   F   G   H   M   N   P   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   C   D   H   M   P   S   T  
Index Entry  Section

C
category: Exported conditions
category: Exported conditions
category: Exported conditions
category: Exported conditions

D
dbpasswd: Exported classes
dbuser: Exported classes

H
hostname: Exported classes

M
message: Exported conditions
message: Exported conditions
message: Exported conditions
message: Exported conditions

P
port: Exported classes
protocol: Exported classes

S
Slot, category: Exported conditions
Slot, category: Exported conditions
Slot, category: Exported conditions
Slot, category: Exported conditions
Slot, dbpasswd: Exported classes
Slot, dbuser: Exported classes
Slot, hostname: Exported classes
Slot, message: Exported conditions
Slot, message: Exported conditions
Slot, message: Exported conditions
Slot, message: Exported conditions
Slot, port: Exported classes
Slot, protocol: Exported classes
Slot, title: Exported conditions
Slot, title: Exported conditions
Slot, title: Exported conditions
Slot, title: Exported conditions

T
title: Exported conditions
title: Exported conditions
title: Exported conditions
title: Exported conditions

Jump to:   C   D   H   M   P   S   T  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   D   N   P   S   T  
Index Entry  Section

C
Class, neo4j-rest-server: Exported classes
client-error: Exported conditions
client-notification: Exported conditions
Condition, client-error: Exported conditions
Condition, client-notification: Exported conditions
Condition, database-error: Exported conditions
Condition, transient-error: Exported conditions

D
database-error: Exported conditions

N
neo4cl: The neo4cl system
neo4cl: The neo4cl package
neo4j-rest-server: Exported classes

P
Package, neo4cl: The neo4cl package

S
System, neo4cl: The neo4cl system

T
transient-error: Exported conditions

Jump to:   C   D   N   P   S   T