Neo4j REST API wrapper for Node.js
master branch: 
develop branch:
Installation
npm install node-neo4j --saveUsage
In order to use the library you either have to create a heroku app and add the GrapheneDB Neo4j Addon or install it locally.
If you're using OS X I highly recommend installing Neo4j via Homebrew.
brew install neo4j
neo4j startInstantiate a wrapper instance
var neo4j = require('node-neo4j');
db = new neo4j('http://username:password@domain:port');
// when using token based authentication introduced in Neo4j v2.2
db = new neo4j('http://:your-authentication-token@domain:port');Run a cypher query
db.cypherQuery("START user = node(123) MATCH user-[:RELATED_TO]->friends RETURN friends", function(err, result){
if(err) throw err;
console.log(result.data); // delivers an array of query results
console.log(result.columns); // delivers an array of names of objects getting returned
});NOTE New features like labels, contraints and transactions are only supported by Neo4j 2.0.0.
Disclaimer
We try to update the module as fast as possible to adapt to any new version of Neo4j.
Don't be shy to give remarks, report bugs or send in pull requests.
You can contact use on Twitter https://twitter.com/Stofkn, https://twitter.com/philippkueng or send us some email via the address defined in the package.json.
New features
Note
Take a look at the test.main.js file in the test folder for many examples.
Labels and indexes
insertNode Now supports labels.
readLabels Get the labels of a node given the node id. It returns an array of strings.
insertLabelIndex Create a label index on ONE property.
deleteLabelIndex Delete a label index for a property.
listLabelIndexes List indexes for a label.
addLabelsToNode Adding one or multiple labels to a node.
replaceLabelsFromNode Replacing all labels on a node by new labels.
deleteLabelFromNode Removing a label from a node.
readNodesWithLabel Get all nodes with a label.
readNodesWithLabelsAndProperties Get nodes by labels and properties.
listAllLabels List all labels.
updateNodesWithLabelsAndProperties Update all nodes with labels and properties and update/remove properties.
deleteNodesWithLabelsAndProperties Delete all nodes with labels and properties.
Constraints
createUniquenessContstraint Create a uniqueness constraint on a property.
readUniquenessConstraint Get a specific uniqueness constraint for a label and a property.
listAllUniquenessConstraintsForLabel Get all uniqueness constraints for a label.
listContraintsForLabel Get all constraints for a label.
listAllConstraints List all constraints.
dropUniquenessContstraint Drop uniqueness constraint for a label and a property.
Transactions
beginTransaction Begin a new transaction.
addStatementsToTransaction Execute statements in an open transaction.
resetTimeoutTransaction Reset transaction timeout of an open transaction.
commitTransaction Commit an open transaction.
rollbackTransaction Rollback an open transaction.
beginAndCommitTransaction Begin and commit a transaction in one request.
Changes
Node id is now an integer not a string. cypherQuery Now supports parameters, Neo4j will cache query and reuse it with different parameters.
Node operations
Insert a Node
db.insertNode({
name: 'Darth Vader',
sex: 'male'
},function(err, node){
if(err) throw err;
// Output node properties.
console.log(node.data);
// Output node id.
console.log(node._id);
});
Read a Node
db.readNode(12, function(err, node){
if(err) throw err;
// Output node properties.
console.log(node.data);
// Output node id.
console.log(node._id);
});
Update a Node
Will remove any assigned properties and replace them with the ones given below.
db.updateNode(12, {name:'foobar2'}, function(err, node){
if(err) throw err;
if(node === true){
// node updated
} else {
// node not found, hence not updated
}
});
Update all nodes with labels and oldProperties, set the newProperties and remove removeProperties
Return nothing if returnUpdatedNodes is false. Default will return all updated nodes.
labelsString|Array[String] e.g.: '' or [] or 'User' or ['User', 'Student']- 'oldProperties' Object e.g.: { userid: '124' }
newPropertiesObject e.g.: { email: '[email protected]' }removePropertiesObject e.g.: ['old_email', 'old_address'] (Optional)returnUpdatedNodesBoolean e.g.:false(Optional, default:true)
Will change only the name and remove the old_address of user with userid '123'. The node will be returned in an array because returnUpdatedNodes is true. You can drop returnUpdatedNodes because it's optional and the default is true.
db.updateNodesWithLabelsAndProperties(['User'], { userid: '123' }, { name:'new_name' }, ['old_address'], true, function (err, updatedNodes){
if(err) throw err;
if(updatedNodes.length === 1){
// one node updated
} else {
// zero or multiple nodes were updated
}
});
Delete a Node
db.deleteNode(12, function(err, node){
if(err) throw err;
if(node === true){
// node deleted
} else {
// node not deleted because not found or because of existing relationships
}
});
Delete all nodes with labels and properties.
-
labelsString|Array[String] e.g.: '', [], 'User', ['User', 'Student'] -
'properties' Object e.g.: { userid: '124' } Returns the number of deleted nodes e.g.: 1.
db.deleteNodesWithLabelsAndProperties('User',{ firstname: 'Sam', male: true }, function(err, deletedNodesCount){}); db.deleteNodesWithLabelsAndProperties(['User','Admin'], { 'name': 'Sam'}, function(err, deletedNodesCount){});
Relationship operations
Insert a Relationship
db.insertRelationship(root_node_id, other_node_id, 'RELATIONSHIP_TYPE', {
age: '5 years',
sideeffects: {
positive: 'happier',
negative: 'less time'
}}, function(err, relationship){
if(err) throw err;
// Output relationship properties.
console.log(relationship.data);
// Output relationship id.
console.log(relationship._id);
// Output relationship start_node_id.
console.log(relationship._start);
// Output relationship end_node_id.
console.log(relationship._end);
});
Read a Relationship
db.readRelationship(relationship_id, function(err, relationship){
if(err) throw err;
// Same properties for relationship object as with InsertRelationship
});
Update a Relationship
Will remove any assigned properties and replace them with the ones given below.
db.updateRelationship(relationship_id, {
age: '6 years'
}, function(err, relationship){
if(err) throw err;
if(relationship === true){
// relationship updated
} else {
relationship not found, hence not updated.
}
});
Delete a Relationship
db.deleteRelationship(relationship_id, function(err, relationship){
if(err) throw err;
if(relationship === true){
// relationship deleted
} else {
// relationship not deleted because not found.
}
});
Index operations
This documentation only contains calls to Node specific index functions however to call those functions for Relationships, just replace Node with Relationship.
Insert an Index
db.insertNodeIndex('the_index_name', function(err, result){
if (err) throw err;
console.log(result); // return the index template and configuration
});
// insert an index with a custom configuration
db.insertNodeIndex({
index: 'the_index_name',
config: {
type: 'fulltext',
provider: 'lucene'
}
}, function(err, result){
if (err) throw err;
console.log(result); // return the index template with its custom configuration
});
Delete an Index
db.deleteNodeIndex('the_index_name', function(err, result){
if (err) throw err;
console.log(result) // will be true, if the deletion is successful
});
List all Indexes
db.listNodeIndexes(function(err, result){
if (err) throw err;
console.log(result); // an object with all indexes and their templates and configurations
});
Add a node to an index
db.addNodeToIndex(node_id, 'the_index_name', 'an_indexed_key', 'an_indexed_value', function(err, result){
if (err) throw err;
console.log(result); // will return the index
});
Advanced relationship operations
Get all relationship types used within the Neo4j database
Will also return types of those relationships that have been deleted.
db.readRelationshipTypes(function(err, result){
if(err) throw err;
console.log(result); // eg. ['RELATED_TO', 'LOVES', 'KNOWNS']
});
Get relationships of a node
Get all (incoming and outgoing) relationships of a node, or use the options object to filter for specifc types and directions.
db.readRelationshipsOfNode(node_id, {
types: ['RELATED_TO', ...] // optional
direction: 'in' // optional, alternative 'out', defaults to 'all'
}, function(err, relationships) {
if (err) throw err;
console.log(relationships); // delivers an array of relationship objects.
});
Run a cypher query against Neo4j
db.cypherQuery("START user = node(123) MATCH user-[:RELATED_TO]->friends RETURN friends", function(err, result){
if(err) throw err;
console.log(result.data); // delivers an array of query results
console.log(result.columns); // delivers an array of names of objects getting returned
});
Run a batch query against Neo4j
For more information about what queries are possible checkout the Neo4j REST API documentation.
db.batchQuery([
{
method: "GET",
to: "/node/100",
id: 0
},{
method: "GET",
to: "/node/102",
id: 1
}
], function(err, result){
if(err) throw err;
console.log(result); // delivers an array of query results
});
Tests
This API wrapper relies on mocha for testing, therefore when you want to run the tests follow the steps below.
$ git clone git://github.com/philippkueng/node-neo4j.git
$ cd node-neo4j/
$ npm install
$ npm test
Issues or Feature Requests?
In case you run into an issue while using the wrapper or you have a feature request please let me know by creating a new issue or contacting me via twitter.
Development
When making a pull request, please make sure to make it against the develop branch and make sure to install the git pre-commit hook which enforces a shared coding style.
ln -s ../../pre-commit.sh .git/hooks/pre-commit