neograph

README

neograph

What

neograph is a Protocol Buffers library for handling arbitrary Cypher queries.

Why

Sometimes it makes sense for a client to send arbitrary queries. However, the problems with that are twofold: not only can assemblying Cypher queries be difficult (requires an ORM) it also means the backend server needs to parse the Cypher (huge red flag) to ensure it's safe to run.

A structured format (Protocol Buffers or JSON) provides an easy way for a client to assemble a Cypher query without an ORM. Additionally, it allows the backend server to do its own error checking. For example, given an arbitrary Cypher query how would one ensure that LIMIT isn't too large? With neograph all the backend needs to do is

// q is a ReadQuery, read off the wire
if q.Limit >= someBigNumber {
	q.Limit = someSmallerNumber
}

Other benefits include being able to cut and add parts of the query, as well as ensuring that only specific types of queries (create, merge, read, etc.) are run.

Benefits

Variables are parameterized and quoted for safety. Having separate Read, Merge, and Create queries means a malicious client can't, for example, send a write query when only a read is allowed. Unmarshaling the protobuf or structured JSON into native code allows the Go backend to manipulate the query before it turns it into Cypher. No Cypher parsing is required.

In addition to the JavaScript library, the Go code can be used directly to generate Cypher. (See graph_test.go.)

ORM

This library can be used as the backend for an ORM that wraps up the generated protobuf code and makes it more palatable.