Documentation

Graph Story provides graph databases as a service. It's what we do, and we're pretty good at it. Graph Story offers the latest version of Neo4j, the world's leading graph database.

Using a high-performance Neo4j graph database hosted on Graph Story, developers have access to a proven and scalable option to help manage complex, highly-connected data. Graph Story can help get answers in real-time, at a lower monthly cost, and without long-term contracts.

Creating your first graph database instance

As soon as you sign-up for a Graph Story account, a free trial instance is created. When it is available, you should receive an email, and it will appear in your Graph List. The username and password for the Neo4j instance will be shown there.

Graph Story Console

The Graph Story Console, available at console.graphstory.com, lets you add, remove, and manage you graph instances.

Creating a new instance

You can create a new instance at any time using the New Instance button:

"New Instance Button"

In the New Instance purchase screen, you can choose your cloud provider, region, and the size of your instance.

By default, instances come installed with Neo4j Enterprise Edition.

Deleting an existing instance

You can destroy an instance at any time by clicking on the Actions menu for the instance, and selecting Delete Graph Instance. You will be warned that this will permanently delete the instance and all data on it, and must confirm your request. Deleting an instance will also delete the subscription associated with it.

If you want to migrate data to a new instance, create the new instance first and migrate your data before deleting the old instance!

Imports and exports

At any time, you can import or export data from your Neo4j instance. Importing always requires Neo4j to restart, but exporting only requires a restart with Neo4j Community Edition.

"Import & Export"

Import instructions

  1. Create a ZIP file containing the contents of your Neo4j database folder. DO NOT ZIP UP THE FOLDER ITSELF. For example, if your database folder name is graph.db, you should select all the files within the graph.db folder and put them in the root of the ZIP file.
    "How to ZIP up the import data on OS X"
  2. On the instance's Action menu, select Import & Export
  3. Choose the ZIP file you created from your computer
  4. Click on the Upload Import File button
  5. Wait for the upload to complete (large files may take some time, based on your network upload speeds)
  6. You will receive an email indicating that the import finished in a few minutes.

Export instructions

  1. On the instance's Action menu, select Import & Export
  2. Click on the Start Export button.
  3. In a few minutes, you should receive an email containing a download link for you export file

The export file can be imported into a new instance as-is.

Moving data between instances

To move data from one instance to another, you should:

  1. Export data from the first instance
  2. Import the data to the second instance

Note that if the two Neo4j instances are not the same version, the data may need to be upgraded by the new instance. The new instance must be the same version or newer than the old instance. Contact us if you have any problems moving your data -- we are happy to help.

Backups

To do a manual backup, just export data from the database.

For automated backups, your options vary if you are running Neo4j Community Edition vs Enterprise Edition:

  1. If you are running Enterprise Edition, then we automatically do daily, weekly, and monthly hot backups (no downtime). We keep the last seven for each time period: 7 daily, 7 weekly, 7 monthly.
  2. If you are running Community Edition, Neo4j has to shut down to back-up, so we currently do not run automatic backups. Customers can use an alpha API we made to trigger exports on your own schedule, effectively lets you automate it. Let us know if you want access to this API.

Restoring Automated Backups

To restore automated backups:

  1. On the instance's Action menu, select Backup & Restore
  2. In the drop-down menu, select the backup you wish to restore
  3. Wait a few moments while your existing database is removed, and the backup is restored

Neo4j Basics

What's a Graph Database?

We wrote an article just for you: What Is A Graph DB?

Neo Technologies also has an excellent intro to graph database basics with Neo4j.

What is Cypher?

Cypher is an open graph query language that Neo4j uses. If you're familiar with SQL, you'll find Cypher to be similar. Neo Technologies has good resources on learning Cypher.

Enterprise vs Community Edition

By default our graph instances run Neo4j Enterprise Edition. The other edition is Community, which older customers may be running.

Both editions feature:

  • Property Graph Model
  • Native Graph Processing & Storage
  • ACID compliance
  • Cypher – Graph Query Language
  • REST API
  • High-Performance Native API ("Bolt")
  • HTTPS support

Enterprise Edition adds:

  • Clustered Replication (High-availability cluster support)
  • Hot Backups (Graph Story automatically backs-up Enterprise instances daily, weekly, and monthly)
  • Enterprise Lock Manager
  • Cache Sharding
  • Cypher Query Tracing
  • Property Existence Constraints

Enterprise Edition is not open source, and requires a license. Graph Story is a Neo4j Solution Partner, and licenses are included in the Graph Story subscription cost. License cost varies based on the size of the company.

Language-specific documentation

There are Neo4j libraries for many languages and platforms. Here, we'll cover some of the most popular.

Ruby

Neography

From the github repo:

Neography is a thin Ruby wrapper to the Neo4j Rest API

To install:

gem install 'neography'

To use in your Ruby code:

require 'rubygems'
require 'neography'

neo = Neography::Rest.new("http://username:password@your-domain.provider.graphstory.com:7473")
neo.execute_query("MATCH (person:Person) RETURN person LIMIT 10")
node = neo.create_node("age" => 31, "name" => "Max")

Other Ruby libraries

  • Neo4j.rb

    An ActiveRecord-inspired OGM (Object Graph Mapping, like ORM) for Ruby

  • neo4j-core

    A simple unified API that can access both the server and embedded Neo4j database

More information on using Neo4j with Ruby

Node.js

The official JavaScript driver is neo4j-driver. You can install it with npm:

npm install neo4j-driver@1.0.2

Now you can use it to connect to your Graph Story instance:

var neo4j = require('neo4j-driver').v1;

var driver = neo4j.driver("bolt://your-domain.provider.graphstory.com", neo4j.auth.basic("username", "password"));
var session = driver.session();
session
  .run( "CREATE (a:Person {name:'Arthur', title:'King'})" )
  .then( function()
  {
    return session.run( "MATCH (a:Person) WHERE a.name = 'Arthur' RETURN a.name AS name, a.title AS title" )
  })
  .then( function( result ) {
    console.log( result.records[0].get("title") + " " + result.records[0].get("name") );
    session.close();
    driver.close();
  });

More information on using Neo4j with JavaScript

JavaScript

You can use the official Neo4j JS driver in the browser as well, but your instance credentials would be available in the source code, so we do not recommend this. See the GitHub project for more information.

Swift (iOS)

Graph Story created Theo, an open-source framework written in Swift that provides an interface for interacting with Neo4j. Theo offers CRUD-style operations for nodes and relationships, and transaction support, in addition to standard Cypher queries.

To install, follow these steps:

  • Add it as a submodule to your existing project.
    git submodule add git@github.com:GraphStory/neo4j-ios.git
    
  • Open the Theo folder, and drag Theo.xcodeproj into the file navigator of your Xcode project.
  • In Xcode, navigate to the target configuration window by clicking on the blue project icon, and selecting the application target under the "Targets" heading in the sidebar.
  • In the tab bar at the top of that window, open the "Build Phases" panel.
  • Expand the "Link Binary with Libraries" group, and add Theo.framework.
  • Click on the + button at the top left of the panel and select "New Copy Files Phase". Rename this new phase to "Copy Frameworks", set the "Destination" to "Frameworks", and add Theo.framework.

Use it in your code like so:

let theo: Client = Client(baseURL: "hostname.com", user: "username", pass: "password")

// create a node
let node = Node()
let randomString: String = NSUUID().UUIDString

node.setProp("propertyKey_1", propertyValue: "propertyValue_1" + randomString)
node.setProp("propertyKey_2", propertyValue: "propertyValue_2" + randomString)

theo.createNode(node, completionBlock: {(node, error) in
    print("new node \(node)")
});

// execute a Cypher query
let theo: Client = Client(baseURL: configuration.host, user: configuration.username, pass: configuration.password)
let cyperQuery: String = "MATCH (u:User {username: {user} }) WITH u MATCH (u)-[:FOLLOWS*0..1]->f WITH DISTINCT f,u MATCH f-[:LASTPOST]-lp-[:NEXTPOST*0..3]-p RETURN p.contentId as contentId, p.title as title, p.tagstr as tagstr, p.timestamp as timestamp, p.url as url, f.username as username, f=u as owner"
let cyperParams: Dictionary<String, AnyObject> = ["user" : "ajordan"]

theo.executeCypher(cyperQuery, params: cyperParams, completionBlock: {(cypher, error) in
    println("response from cyper \(cypher)")
})

PHP

GraphAware PHP Client

We use the GraphAware PHP Client at Graph Story for many applications. It's very powerful and well-supported.

You can install it with composer:

composer require graphaware/neo4j-php-client:^4.0

Use it in your code like so:

<?php
require_once "vendor/autoload.php";

use GraphAware\Neo4j\Client\ClientBuilder;

$client = ClientBuilder::create()
    ->addConnection("bolt", "bolt://username:password@your-domain.provider.graphstory.com:7687")
    ->build();
$query = "MATCH (n:Person)-[:FOLLOWS]->(friend) RETURN n.name, collect(friend) as friends";
$result = $client->run($query);

foreach ($result->getRecords() as $record) {
    echo sprintf(
        "Person name is : %s and has %d number of friends",
        $record->value('name'),
        count($record->value('friends'))
    );
}

Other PHP libraries

More information on using Neo4j with PHP

Python

There is an official Python driver for Neo4j, which you can install using pip:

pip install neo4j-driver

Usage example:

from neo4j.v1 import GraphDatabase, basic_auth

driver = GraphDatabase.driver("bolt://your-domain.provider.graphstory.com", auth=basic_auth("username", "password"))
session = driver.session()
session.run("CREATE (a:Person {name:'Bob'})")
result = session.run("MATCH (a:Person) RETURN a.name AS name")
for record in result:
    print(record["name"])
result.close()
session.close()

Other Python libraries

  • Py2neo

    A comprehensive toolkit for working with Neo4j from within Python applications or from the command line

  • Neomodel

    An Object Graph Mapper (OGM) for the neo4j graph database, built on the awesome py2neo

More information on using Neo4j with Python

.Net

There is an official .Net driver for Neo4j, which you can install using Nuget:

PM> Install-Package Neo4j.Driver -Pre

Usage example:

using(var driver = GraphDatabase.Driver( "bolt://localhost:7687", AuthTokens.Basic("username", "password") ))
using(var session = driver.Session())
{
    var result = session.Run("CREATE (n) RETURN n");
}

More information on using Neo4j with .Net

Java

There is an official Java driver for Neo4j. To use it, put the following in your Maven pom.xml file:

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
        <version>x.y.z</version>
    </dependency>
</dependencies>

Usage example:

Driver driver = ( "bolt://your-domain.provider.graphstory.com", AuthTokens.basic( "username", "password" ) );
Session session = driver.session();
StatementResult rs = session.run( "CREATE (n) RETURN n" );
session.close();
driver.close();

More information on using Neo4j with Java

Other Java libraries

  • Spring Data Neo4j

    This library provides convenient access to Neo4j including object mapping, Spring Data repositories, conversion, transaction handling, etc.

  • neo4j-ogm

    A fast object-graph mapping library for Neo4j

  • Clojure: Neocons

    An idiomatic, feature rich Clojure client for Neo4J REST API

  • Scala: AnormCypher

    Cypher-oriented Scala library for Neo4j Server (REST)