Willkommen zum zweiten Teil der Tutorialserie über Neo4j. In der letzten Ausgabe haben wir allgemein auf das Datenmodell von Graphdatenbanken geschaut und dessen Unterstützung in NoSQL-Graphdatenbanken betrachtet. Wir haben gesehen, welche dieser Ansätze das Leben eines Softwareentwicklers erleichtern, sowie erste Schritte in der Abfragesprache Cypher gemacht. In diesem Teil soll es nun um die konkrete Nutzung von Neo4j gehen.
Wir gehen diesmal die Schritte von der Installation, über einen Überblick über den eingebauten Neo4j-Browser bis zur Erzeugung der ersten Daten in der Datenbank. Datenimport und -export sind wichtig bei der Einführung einer neuen Datenbank. Den nächsten Schritt bildet die programmatische Nutzung des Neo4j-Servers. Wir werden uns die direkte Nutzung des transaktionalen Cypher-HTTP-API zu Gemüte führen und kurz auf einige Treiber für den Neo4j-Server zurückgreifen. Eine minimale Web-App zur Interaktion mit der Graphdatenbank inklusive CRUD-Operationen, Empfehlungsmaschine und sogar Visualisierung werden den Abschluss bilden, die wir dann auf Heroku deployen, und das GrapheneDB-Neo4j-Add-on benutzen.
Installation von Neo4j
Neo4j ist recht einfach zu installieren. Zum Entwickeln lädt man sich die aktuelle Version 2.0.0 von [1] herunter. Auf Windows enthält der Download einen Installer und eine Desktopanwendung, die das Management des Servers erlaubt. Für Mac OS und Linux/Unix kann man alternativ entweder auf Homebrew- bzw. Debian-/RPM-Packages zurückgreifen, oder man lädt sich einfach die Serverdistribution herunter und packt sie an geeigneter Stelle aus. Neo4j 2.0 benötigt Java 7. Der Server der Distribution wird mit <pfad/zu/neo>/bin/neo4j start gestartet und mit <pfad/zu/neo>/bin/neo4j stop angehalten. Falls es unerwartete Probleme bei der Installation geben sollte, kann man schnelle Hilfe auf http://stackoverflow.com/questions/tagged/neo4j oder über die Neo4j Google Group [2] erhalten.
Neo4j-Browser
Wie nach dem Start des Servers angegeben, steht unter http://localhost:7474 der Neo4j-Browser des Neo4j-Servers bereit. Er ist an ein Kommandozeileninterface angelehnt, aber in einem viel schickeren Gewand als z. B. SQL*Plus (Abb. 1).
Abb. 1: Neo4j-BrowserInitiale Tipps kann man leicht mittels :help, :play intro, :play graphs oder :play cypher erhalten. Im Browser kann man zum einen Cypher-Abfragen ausführen und die Ergebnisse sowohl visuell als auch tabellarisch darstellen. Zum anderen erlaubt er auch die Verwaltung häufig genutzter Abfragen in einer Favoritenliste. Die bisher genutzten Kommandos und Abfragen stehen in einer Eingabehistorie sowie in einem kontinuierlichen Verlauf von Ergebnissen zur Verfügung.
Am Anfang ist die Datenbank noch ein leeres Whiteboard, das auf unsere Eingaben wartet. Wie bekommen wir jetzt schnell ein paar sinnvolle Daten in Neo4j? Zum Glück können wir mit :play movies ein Datenset hervorzaubern, das man per Klick und Run in die Datenbank einfügen kann. Es ist die wohlbekannte Schauspieler-Film-Domäne aus dem Neo4j-Intro-Training, mit deren Verständnis niemand ein Problem haben sollte (Abb. 2).
Abb. 2: Schauspieler-Film-DomäneNachdem die Daten importiert sind, sollte man mit einer Cypher-Abfrage wie MATCH (n) RETURN n LIMIT 50 einen kleinen Ausschnitt der Datenbank angezeigt bekommen. Dieses Snippet ist auch in der Favoritenliste vorhanden, wie man in Abbildung 3 erkennen kann.
Abb. 3: FavoritenlisteIm Neo4j-Browser sind noch einige Goodies versteckt, wie z. B. das Stylen des angezeigten Graphen mittels eines Pop-ups, das das genutzte Graph-Style-Sheet (GRASS) anpasst.
Neo4js HTTP-API
Es können auch http-Kommandos direkt gegen den Neo4j-Server ausgeführt werden. Wie das funktioniert, erfährt man mittels :help REST. So können wir mittels :GET /db/data/ die Information (als JSON) sehen, die die verfügbaren Endpunkte des Servers auflisten. Für uns ist hier vor allem /db/data/transaction von Interesse.
Cypher-HTTP-Endpunkt
Das ist der nagelneue, transaktionale HTTP-Endpunkt für Cypher-Abfragen. Bisher war die Interaktion mit dem Neo4j-Server immer nur auf eine Transaktion pro HTTP-Request beschränkt. Der neue Endpunkt erlaubt es, auf eine geöffnete Transaktion bis zu deren Timeout, Rollback oder Commit weiterzulesen und zu schreiben. Mit jedem Request können mehrere Statements mit Parametern zum Server geschickt werden. In beiden Richtungen wird mittels Streaming der Speicherbedarf minimiert. Ebenso ist der neue Endpunkt deutlich effizienter in Bezug auf die Serialisierung der Ergebnismenge.
Neben den Endpunkten zum Offenhalten einer Transaktion über mehrere Requests, kann man auch direkt mehrere Abfragen innerhalb einer Transaktion ablaufen lassen und diese dann unmittelbar erfolgreich abschließen. Das wollen wir doch glatt einmal probieren. Die notwendige HTTP-Syntax zeigt Listing 1.
Listing 1
:POST /db/data/transaction/commit
{"statements": [
{"statement" :"MATCH (movie:Movie)<-[:ACTED_IN]-(actor)
WHERE movie.title = {title}
RETURN movie.title, collect(actor.name) AS cast",
"parameters":{"title":"The Matrix"}}
]}{"results":[{
"columns":["movie.title","cast"],
"data":[
{"row":["The Matrix",["Keanu Reeves","Carrie-Anne Moss",...]]}]}],
"errors":[]}
Damit kennen wir die wichtigsten API-Bestandteile, die wir benötigen, um den Neo4j-Server programmatisch zu nutzen:
-
Endpunkt /db/data/transaction[/commit]
-
Parameter-Struktur: {"statements": [ {"statement" :"abfrage...", "parameters":{"name":"wert"}},... ]}
-
Ergebnis-Struktur: {"results":[ {"columns":["Spalte1",...], "data":[ {"row":["Wert1",Wert2, ...]}, ... ]}], "errors":[...]}
Das Cypher-API verhält sich in diesem Fall wie SQL: Text mit Parameter zum Server schicken und tabellarische Ergebnisse zurückerhalten.
Transaktionale Nutzung
Der Unterschied bei der Nutzung von Transaktionen über mehrere Requests hinweg ist, dass man den /db/data/transaction-Endpunkt aufruft und dann als Teil des Ergebnisses einen Transaktions-URL als HTTP-Location-Header zurückbekommt (z. B. /db/data/transaction/42) und ein Feld mit dem Commit-URL als Teil des Ergebnis-JSONs (z. B. /db/data/transaction/42/commit). Zum Transaktions-URL würde man dann weitere lesende oder schreibende Abfragen senden und den Commit-URL zum erfolgreichen Abschluss aufrufen. Mehr Details im Neo4j-Handbuch [3].
Ein einfacher Neo4j-HTTP-Client
Wir bedienen uns direkt bei einer der vielen Java-HTTP-Bibliotheken wie Apache HttpClient. Zum Ausführen von Cypher-Statements können wir uns also ein kleines Interface deklarieren, dessen Implementierung dann auf die HTTP-Bibliothek abgebildet wird.
public interface CypherExecutor {
Iterator<Map<String,Object>> query(String statement, Map<~> params);
}
Ein ausführlicheres Design eines Treibers zeigt Listing 2, eine Referenzimplementierung ist auch verfügbar.
Listing 2
interface Driver {
Session connect(URL url);
}
interface Session {
Transaction newTransaction...
