Fair warning: getting to the reasoning point of this process requires an extraordinary amount of hand waving. We're about to go down the rabbit hole.
An unfortunate part of this set up is that you're going to need to set up two different programs:
- Neo4j Server
- Lein/Clojure/Neocons Client
In principle, these can be on the same computer. What I found easiest for myself was to install the neo4j server on my Windows desktop and the clojure client on my CSL unix account. This unfortunately meant that I needed to know my IP, set up port forwarding (for port 7474), and enable remote connections in the neo4j server configuration. All but the latter are outside of the scope of this tutorial, but pretty straightforward with a bit of google-fu. Of course, if you are running linux or mac you may be comfortable running both the clojure client and the server on the same machine. You may even be comfortable doing so on Windows. YMMV.
After you install and start up Neo4j Community Edition, you'll need to pick a database location. The default will suffice. If you are accessing your server remotely then it's probably easiest to take care of Step 3 now by clicking on settings and editing the server settings.
Click Start and you should get a cheerfully green message that Neo4j is ready.
Open your browser and navigate to http://localhost:7474. Now isn't that snazzy?!
Neo4j is a massive piece of software. We're gonna cover the basic usage with respect to establishing graphs. The main thing you need to know the tinyest bit about is Cypher, the Neo4j querying language. If you've ever used a database querying language such as SQL then you should be in somewhat familiar territory. Thankfully Neo4j has tutorials built in to the database.
Click on Cypher on the Welcome screen, or just follow along with the commands below.
CREATE (ee:Person { name: "Emil", from: "Sweden", klout: 99 })
This first statement creates a new node in our graph database. The node is stored in a variable ee and have label Person. We assign some fields and that's all we need to add some data. Run the query and make sure you see something similar.
Note that from now on I'm going to talk about nodes as if they are objects - Neo4j is designed to be sorta-object-orientish so in an effort to maintain familiarity with the more common OO knowledge I'm going to adopt the OO terminology.
MATCH (ee:Person) WHERE ee.name = "Emil" RETURN ee;
This query is used to display objects in the database. In this case we are trying to match Person objects into a variable ee with field name equal to "Emil". The RETURN part tells Neo4j what we want to do with the results - we want to display them! Run the query and see the delightfully interactive output.
Emil is lonely, though. And a graph database is kind of pointless if there isn't any actual... graph! Let's add some new objects.
MATCH (ee:Person) WHERE ee.name = "Emil"
CREATE (js:Person { name: "Johan", from: "Sweden", learn: "surfing" }),
(ir:Person { name: "Ian", from: "England", title: "author" }),
(rvb:Person { name: "Rik", from: "Belgium", pet: "Orval" }),
(ally:Person { name: "Allison", from: "California", hobby: "surfing" }),
(ee)-[:KNOWS {since: 2001}]->(js),(ee)-[:KNOWS {rating: 5}]->(ir),
(js)-[:KNOWS]->(ir),(js)-[:KNOWS]->(rvb),
(ir)-[:KNOWS]->(js),(ir)-[:KNOWS]->(ally),
(rvb)-[:KNOWS]->(ally);
This monstrous query adds a number of new people to our database and also establishes some KNOWS relationships between people.
MATCH (ee:Person) RETURN ee;
Let's run our MATCH query again, this time dropping the WHERE clause. Now we can see all of the happy friends in our database.
This wouldn't be a tutorial if we didn't enable terrible security practices, right?! Uncomment this line in your neo4j settings file if you want it to be accessible to the world:
org.neo4j.server.webserver.address=0.0.0.0
Fortunately there is a tool called Leiningen that makes working with Clojure extra easy. I did the following steps on my CSL account - commandline stuff is always easiest on unix.
Grab the lein script. Easiest way to do that is just wget
wget https://raw.github.com/technomancy/leiningen/stable/bin/lein --no-check-certificate
This will grab the lein program from github. You will need to put it somewhere in your path. On the CSL servers I have ~/bin in my path so I dropped it there.
Next you need to run lein for the first time. This will do a lot of downloading and installation into your home directory. Good thing we have 5GB quotas now, right? :) It should only be about 13MB.
Once that is done it's time to make your project. Go where you want your project files (I chose ~/581/) and run
lein new app my-stuff
After some initialiation, you'll have your first project. cd to my-stuff and have a look at what's there. Let's run our first clojure program! Start with:
lein repl
REPL stands for read-eval-print loop. It gives us an interactive environment to run queries in. Note that this command will actually fire up a server, so give it a good number of seconds to get running. Now, run 'hello world':
(my-stuff.core/-main)
You should see "Hello, World!" and a bit more output. This is what my terminal looks like now:
[idunn01@unix14] ~/581/my-stuff $ lein repl
nREPL server started on port 56041 on host 127.0.0.1
REPL-y 0.3.0
Clojure 1.5.1
Docs: (doc function-name-here)
(find-doc "part-of-name-here")
Source: (source function-name-here)
Javadoc: (javadoc java-object-or-class-here)
Exit: Control+D or (exit) or (quit)
Results: Stored in vars *1, *2, *3, an exception in *e
my-stuff.core=> (my-stuff.core/-main)
Hello, World!
nil
my-stuff.core=>
I told you we were heading into the rabbit hole. Now we need to connect to our Neo4j server.
This next step is why we're using Lein. We need to use Neocons to connect to our Neo4j server. Thankfully all we need to do to get Neocons is add a dependency to our project.clj file in my-stuff. Open up the file and find the line that begins with :dependencies.
Add [clojurewerkz/necons "3.0.0"] to the list so that the line now looks like:
:dependencies [[org.clojure/clojure "1.5.1"] [clojurewerkz/neocons "3.0.0"]]
Next, get back into our lein repl (it'll take a while to download our new dependencies) and run the following two commands:
(ns neocons.docs.examples (:require [clojurewerkz.neocons.rest :as nr]))
(to import some neocons stuff into a convenient namespace) and...
(def conn (nr/connect "http://home.iondune.net:7474/db/data"))
(to establish connection to our server). Note that I am using the URL for my home server. You'll want to substitute localhost or maybe your IP here. You'll want to keep the :7474 and everything else though.