Getting Started Guide

From Neo4j Wiki

Jump to: navigation, search

This document will guide you through your very first Neo4j application. It assumes that you're familiar with Java development and with the basic Neo4j and graph database concepts (for example, as described on the Neo4j front page). If you're not familiar with Java development, see the Java Setup HowTo.

The whole tutorial will take roughly 10 minutes out of your life; at the end, you will have written, compiled, and run a simple but complete "hello world"-like application based on Neo4j. If you're impatient, check out the compressed Getting Started In One Minute Guide.

If you would like to get some commonly used Neo4j components bundled right away, check out the Getting Started With Apoc guide before moving on.

Let's get started!

Contents

[edit] Download the jar file and add it to your classpath

[edit] If you use Maven

If you use Maven2, simply add Neo4j kernel as a dependency after you've enabled the neo4j m2 repository in your POM. In your pom.xml, add the following: 

<project>
...
   <repositories>
      <repository>
         <id>neo4j-public-repository</id>
         <url>http://m2.neo4j.org </url>
      </repository>
   </repositories>
...
   <dependencies>
      <dependency>
         <groupId>org.neo4j</groupId>
         <artifactId>neo4j-kernel</artifactId>
         <version>1.0</version>
      </dependency>
      ...
   </dependencies>
...
</project>

See also a complete example. To see valid releases, check http://neo4j.org/download or browse to the m2 repository with your web browser.

The book Better Builds with Maven is a good starting point if you want to begin using Maven, but find the official documentation overwhelming.

[edit] If you don't use Maven

First, download the latest Neo4j kernel jar from the download page. Second, add it to your classpath in the appropriate manner for your environment:

  • Ant: add to a lib/ dir
  • Eclipse: right-click and add to build path
  • JDK tools: append to -classpath
  • ...

Neo4j kernel has a dependency on the Java Transaction API, so add the JTA jar to your classpath as well (it's included in the distro). This step is completed when you can import classes from the org.neo4j.graphdb package without any compilation errors.

[edit] Initialize and start an EmbeddedGraphDatabase instance

Neo4j is an embedded database, which means that it runs in the same JVM as your application. You the Neo4j database by creating an instance of the EmbeddedGraphDatabase class. The EmbeddedGraphDatabase constructor takes an argument of a directory for storing data files. The directory is simply a string defining a directory relative to the JVM's current working directory. It will be created if it doesn't already exist.

Remember, from the introduction, that a Neo4j graph consists of three basic elements:

  • nodes
  • relationships that connect nodes
  • properties attached to both nodes and relationships

All relationships have a type. For example, if the graph represents a social network, a relationship type could be KNOWS. If a relationship of the type KNOWS connects two nodes, that probably represents two people that know each other. A lot of the semantics (ie, the meaning) of a graph is encoded in the relationship types of the application. And although relationships are directed they are equally well traversed irregardless of which direction they are traversed.

For our small example, we need only one relationship type. Here's how we define it: 

public enum MyRelationshipTypes implements RelationshipType
{
    KNOWS
}

Then we should embed Neo4j into our application as follows: 

GraphDatabaseService graphDb = new EmbeddedGraphDatabase( "var/graphdb" );

When the constructor returns, Neo4j has started and immediately loaded the data files in the directory "var/graphdb" (if the directory doesn't exist, Neo4j will create and initialize it). All we need to remember is to shutdown Neo4j before exiting: 

graphDb.shutdown();

[edit] Wrap everything in a transaction

Are we set to go? Not yet.

In Neo4j any interaction with the graph has to be part of a transaction. This is a conscious design decision, since we believe transaction demarcation to be an important part of working with a real enterprise database. Note that read operations need to be in a transaction as well, not only write operations. Now, transaction handling in Neo4j is very easy: 

Transaction tx = graphDb.beginTx();
try
{
   // all Neo4j operations that work with the graph
   // ...
   tx.success();
}
finally
{
   tx.finish();
}

See more information about transactions.

We're set to go!

[edit] Create a small graph

Now, let's create a few nodes. The API is very intuitive. Feel free to have a look at the javadocs at http://api.neo4j.org/current (they're included in the distribution, as well). Here's how to create a small graph consisting of two nodes, connected with one relationship and some properties: 

Node firstNode = graphDb.createNode();
Node secondNode = graphDb.createNode();
Relationship relationship = firstNode.createRelationshipTo( secondNode, MyRelationshipTypes.KNOWS );

firstNode.setProperty( "message", "Hello, " );
secondNode.setProperty( "message", "world!" );
relationship.setProperty( "message", "brave Neo4j " );

We now have a graph that looks like this: 

(firstNode )---KNOWS--->(secondNode)

[edit] Print the result

After we've created our graph, let's read from it and print the result. 

System.out.print( firstNode.getProperty( "message" ) );
System.out.print( relationship.getProperty( "message" ) );
System.out.print( secondNode.getProperty( "message" ) );

Running this code will give the following output: 

Hello, brave Neo4j world!

[edit] Conclusion

Ok, our 10 minutes are up! The full source code for this short example is here. Now you are familiar with how to build a graph -- one of the two fundamentals of Neo4j (the other being the traverser framework). How to proceed from here?

  • Your next stop is definitely the basic code snippets PDF (old API), which through a few slides will give you a code-level introduction to the traverser framework.
  • There are some articles linked to from http://neo4j.org/doc that introduce the high level concepts of Neo4j. They're from 2 to 8 pages and they do a pretty good job of putting the concepts into perspective but also include some source code level details.
  • The Shell is an interactive command-line tool for browsing the graph. Very useful during development! Check out the Shell guide.
  • Sign up to the mailing list and ask questions. We love questions, particularly from Neo4j newcomers!
  • Lastly, the Main Page tries to gather most of our documentation in one place.
Retrieved from "http://wiki.neo4j.org/content/Getting_Started_Guide"
Personal tools