Seraph.js

A terse & familiar binding to the Neo4j REST API that is idiomatic to node.js.

Install

npm install seraph

Quick Example

var db = require("seraph")("http://localhost:7474");

db.save({ name: "Test-Man", age: 40 }, function(err, node) {
  if (err) throw err;
  console.log("Test-Man inserted.");

  db.delete(node, function(err) {
    if (err) throw err;
    console.log("Test-Man away!");
  });
});

Documentation

Initialization

seraph - initialize the seraph client
changePassword - change the db user's password

Generic Operations

query - perform a cypher query and parse the results
queryRaw - perform a cypher query and return unparsed results

API Communication Operations

operation - create a representation of a REST API call
call - take an operation and call it
batch - perform a series of atomic operations with one api call.

Node Operations

save (node.save) - create or update a node
read (node.read) - read a node
find (node.find) - find a node using a predicate
delete (node.delete) - delete a node
relate (node.relate) - relate two nodes
relationships (node.relationships) - read the relationships of a node
legacyindex (node.legacyindex) - add a node to a legacy index
label (node.label) - add a label to a node
removeLabel (node.removeLabel) - remove a label from a node
nodesWithLabel (node.nodesWithLabel) - fetch all nodes with a label
readLabels (node.readLabels) - read the labels of a node or all available labels.

Relationship Operations

rel.create - create a relationship
rel.update - update the properties of a relationship
rel.read - read a relationship
rel.delete - delete a relationship

Constraint operations

constraints.list - list constraints
constraints.uniqueness.create - create a uniqueness constraint
constraints.uniqueness.createIfNone - create a uniqueness constraint if it doesn't already exist
constraints.uniqueness.list - list uniqueness constraints
constraints.uniqueness.drop - drop a uniqueness constraint

Indexing operations

index.create - create an index on a label and property name
index.createIfNone - create an index or return the old one
index.list - read out the indexes for a label
index.drop - drop an index

Legacy Index Operations

legacyindex.create - create an index
legacyindex.add - add a nodes/rels to an index
legacyindex.read - read nodes/rels from an index
legacyindex.remove - remove nodes/rels from an index
legacyindex.delete - delete an index
legacyindex.getOrSaveUnique - get or save a node using an index for uniqueness
legacyindex.saveUniqueOrFail - save a node using an index to enforce uniqueness

Compatibility

Seraph ~0.15 has been tested with with Neo4j 3.

Testing

You can test Seraph simply by running npm test. It will spin up its own neo4j instance for testing. Note that the first time you run your tests (or change neo4j version), a new version of neo4j will need to be downloaded. That can, of course, take a little time.

Initialization

seraph([server|options])

Creates and returns the Seraph instance. If no parameters are given, assumes the Neo4J REST API is running locally at the default location http://localhost:7474/db/data.

Arguments

options: an options object. You can use the following options:
- server (default = "http://localhost:7474"): the server to connect to (with protocol and port, not path).
- endpoint (default = "/db/data"): the path to Neo4j's rest API. You can leave this as the default if you have not changed it yourself in the neo4j settings.
- user (default = "neo4j"): the username to authenticate with.
- pass (default = "neo4j"): the password to authenticate with.
- id (default = "id"): the name of the attribute seraph will add to new nodes when they are created and that it will use to find nodes when performing updates with node.save and the like.
- agent (default = null): the http agent for requests to neo4j server. The same can be used for keep-alive connections to server. Can use agentkeepalive module to create a keep-alive agent. It's a recommended option for high performance and low latency client.
- xstream (default = false): if true, passes new X-Stream option to neo4j server. It's a recommended option for high performance and low latency client.
server (string) - Short form to specify server parameter only. "http://localhost:4747" is equivalent to { server: "http://localhost:4747" }.

Note that as of Neo4j 2.2.0, user authentication is required. You will not be able to access resources before supplying a username or password that is not the default. You can change the password using seraph#changePassword.

Example

// To http://localhost:7474/db/data with user "local" and pass "test"
var dbLocal = require("seraph")({
  user: 'local',
  pass: 'test'
});

// To http://example.com:53280/neo with user "root" and pass "jf8%kLs#!"
var dbRemote = require("seraph")({ server: "http://example.com:53280",
                                   endpoint: "/neo",
                                   user: "root",
                                   pass: "jf8%kLs#!" });

// Copy node#13 from remote server
dbRemote.read({ id: 13 }, function(err, node) {
  if (err) throw err;
  delete node.id; // copy instead of overwriting local node#13
  dbLocal.save(node, function(err, nodeL) {
    if (err) throw err;
    console.log("Copied remote node#13 to " +
                "local node#" + nodeL.id.toString() + ".");
  });
});

changePassword(newPassword, callback)

Change's the current database user's password. This will automatically update seraph's options to contain the new password if it is successful

Arguments

newPassword (string) - the new password to set.
callback (function(err){}) - callback to call when the password has been changed.

Example

// connect to a local neo4j instance with default settings (user/pass is "neo4j" by default).
var db = require("seraph")();
db.changePassword('b2(jk:4@#', function(err) {
  //password is now changed, and `db`'s options have been updated with the new password
});

Generic Operations

query(query, [params,] callback), queryRaw(query, [params,] callback)

queryRaw performs a cypher query and returns the results directly from the REST API.
query performs a cypher query and map the columns and results together.

Note: if you're performing large queries it may be advantageous to use queryRaw, since query attempts to infer whole nodes and relationships that are returned (in order to transform them into a nicer format).

Arguments

query - Cypher query as a format string.
params (optional, default={}). Replace {key} parts in query string. See cypher documentation for details. note that if you want to send a list of ids as a parameter, you should send them as an array, rather than a string representing them ([2,3] rather than "2,3").
callback - (err, result). Result is an array of objects.

Example

Given database:

{ name: 'Jon', age: 23, id: 1 }
{ name: 'Neil', age: 60, id: 2 }
{ name: 'Katie', age: 29, id: 3 }
// 1 --knows--> 2
// 1 --knows--> 3

Return all people Jon knows:

var cypher = "START x = node({id}) "
           + "MATCH x -[r]-> n "
           + "RETURN n "
           + "ORDER BY n.name";

db.query(cypher, {id: 1}, function(err, result) {
  if (err) throw err;
  assert.deepEqual(result, [
    { name: 'Katie', age: 29, id: 3 },
    { name: 'Neil', age: 60, id: 2 }
  ]);
};

db.queryRaw(cypher, {id: 3}, function(err, result) {
  if (err) throw err;
  // result contains the raw response from neo4j's rest API. See
  // http://docs.neo4j.org/chunked/milestone/rest-api-cypher.html
  // for more info
});

operation(path, [method='get/post'], [data])

Create an operation object that will be passed to call.

Arguments

path - the path fragment of the request URL with no leading slash.
method (optional, default='GET'|'POST') - the HTTP method to use. When data is an object, method defaults to 'POST'. Otherwise, method defaults to GET.
data (optional) - an object to send to the server with the request.

Example

var operation = db.operation('node/4285/properties', 'PUT', { name: 'Jon' });
db.call(operation, function(err) {
  if (!err) console.log('Set `name` to `Jon` on node 4285!');
});

call(operation, callback)

Perform an HTTP request to the server.

If the body is some JSON, it is parsed and passed to the callback.If the status code is not in the 200's, an error is passed to the callback.

Arguments

`oper

Seraph

Install / Use

README

Seraph.js

Install

Quick Example

Documentation

Initialization

Generic Operations

API Communication Operations

Node Operations

Relationship Operations

Constraint operations

Indexing operations

Legacy Index Operations

Compatibility

Testing

Initialization

seraph([server|options])

changePassword(newPassword, callback)

Generic Operations

query(query, [params,] callback), queryRaw(query, [params,] callback)

operation(path, [method='get/post'], [data])

call(operation, callback)