Neo4j REST API wrapper for Node.js

master branch:
develop branch:

---

Installation

npm install node-neo4j --save

Usage

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 start

Instantiate 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.

• labels String|Array[String] e.g.: '' or [] or 'User' or ['User', 'Student']
• 'oldProperties' Object e.g.: { userid: '124' }
• newProperties Object e.g.: { email: '[email protected]' }
• removeProperties Object e.g.: ['old_email', 'old_address'] (Optional)
• returnUpdatedNodes Boolean 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.

• labels String|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