neoorm.js
It's an basic Neo4j ORM designed to work in an asynchronous enviroment.
Limitations
This is an early version, so there are some limitations you need to known before:
- Neo4j 2.0: neoorm.js works only with Neo4j 2+ and uses Cypher
- Schema: it's not implemented yet (I would write something like mongoose.js)
- Nodes: a node can have only a label
- Relationships: you can't save multiple relationship of the same type between two nodes
- Models: You need to declare all the Node and Relationship models before use it
Goals
With the next releases I would:
- have a well working schema implementation for Nodes and Relationships
- be able to ensure declared relationships between nodes
- allow connections to Neo4j using HTTP authentication (usefull if you've a proxy in front of the Neo4j REST API)
I will be very happy if:
- someone could help me making this library better
- I can use multiple labels for each node
Installation
First install node.js and neo4j. Then:
$ npm install neoogm
Example
First, we need to configure a database connection neoogm.config
neoogm;
Read more about neoogm.config
Now you need to define a model for every nodes you need to use in the application:
Actor = neoogm;Movie = neoogm;
Read more about neoogm.node
Then we have to declare a model for every relations:
RelPlayed = neoogm;
Read more about neoogm.relationship
Now you're ready to create actors and movies:
neo = first_name: 'Keanu' last_name: 'Reeves';matrix = name: 'The matrix';
...and create relationships between nodes:
neoAct = _start: neo _end: matrix role: 'Neo';neoAct;
Summary
- Configuration
- neoogm.config(options = {})
- Node model
- Model = neoogm.node(name, [options = {}])
- create(data = {}, callback)
- update(options = {}, callback)
- delete(options = {}, callback)
- find(options = {}, callback)
- findById(id, callback)
- findByIdAndRemove(id, callback)
- findByIdAndUpdate(id, data = {}, callback)
- new Model(data = {})
- save(callback)
- remove(callback)
- findOutgoing(options = {}, callback)
- findIncoming(options = {}, callback)
- findRelates(options = {}, callback)
- getId()
- getLabel()
- Model = neoogm.node(name, [options = {}])
- Node utils
- neoogm.findNodeById(id, callback)
- Relationship model
- Rel = neoogm.relationship(name, [options = {}])
findOutgoing(options = {}, callback)to be enhancedfindIncoming(options = {}, callback)to be enhancedfindRelates(options = {}, callback)to be enhancedcreate()to be implementedupdate()to be implementeddelete()to be implemented
- new Rel(data = {})
- save(callback)
- remove(callback)
- getId()
- getType()
- getStart(callback)
- getEnd(callback)
- Rel = neoogm.relationship(name, [options = {}])
- Relationship utils
- neoogm.findRelationshipById(id, callback)
- Cypher query
- neoogm.cypher(options = {}, callback)
Configuration
neoogm.config(options = {})
You can configure the library behavior.
Examples:
neoogm;
Options Hash (options):
- host (String) — Hostname of the remote Neo4j database. Default is
localhost
- port (Integer) — Port number of the remote Neo4j database. Default is
7474
- secure (Boolean) — Enable or disable HTTPS. Default is
false
- node (Object) — Default behavior for node models:
- created_at (Boolean or String) — create and save an
created_at
Date.now() property. Whentrue
neoorm.js create a property namedcretated_at
, but you can change this name passing an string - updated_at (Boolean or String) — create and save an
updated_at
Date.now() property. Whentrue
the library create a property namedupdated_at
, but you can change this name passing an string
- created_at (Boolean or String) — create and save an
- relationship (Object) - Default behavior for relationship models
- created_at (Boolean or String) — see
node.created_at
- updated_at (Boolean or String) — see
node.updated_at
- created_at (Boolean or String) — see
Node model
neoogm.model(name, [options = {}])
Used to define or retrieve a ORM model.
Examples:
Actor = neoogm;ActorTest = neoogm; console;
Options Hash (options):
- schema (Object) — have to be completed, if you're in
strict
mode, neoorm.js save into the remote database only the declared keys found in the schema. - scrict (Boolean) — partially implemented right now
- created_at (Boolean or String) — overwrite the default
node.created_at
property defined withneoorm.config()
- updated_at (Boolean or String) — overwrite the default
node.updated_at
property defined withneoorm.config()
Model.create(data = {}, callback)
Create one or more models and save it in the database.
Examples:
Actor;
Properties:
- data (Object or Array of Objects) — Item or items to save in the database
Callback (callback):
{};
Model.update(options = {}, callback)
Update one or more nodes.
Example:
Actor;Actor;
Parameters:
- options (Object)
- query (String, Array or Object) — filter rules, can be:
- String — a Cypher query string to append after the WHERE clause; this string can have params like
{sex}
(seeparams
) - Array — with complex query can be usefull pass an array of strings; their are joined together
- Object — when you want alter all the models with a
=
match rule, you can pass an hash of key (field name) and values)
- String — a Cypher query string to append after the WHERE clause; this string can have params like
- params (Object) — list of keys (param name) and values to replace in a query string.
- data (Object) - list of keys (field name) and values to replace into the found models
- query (String, Array or Object) — filter rules, can be:
Callback (callback):
{};
Model.delete(options = {}, callback)
Delete one or more nodes.
Example:
Actor;
Parameters:
- options (Object)
- query (String, Array or Object) — same of
Model.update()
- params (Object) — list of keys (param name) and values to replace in a query string.
- query (String, Array or Object) — same of
Callback (callback):
{};
## Model.find(options = {}, callback)
Find one or more nodes.
**Example:**
```javascript
Actor.find({
query: {
first_name: 'Johnny',
last_name: 'Depp'
}
}, function (err, items) {
if (err)
return console.error("Error: ", err);
console.log("Found ", items.length, " actors: ", items);
});
Parameters:
- options (Object)
- query (String, Array or Object) — same of
Model.update()
* params (Object) — list of keys (param name) and values to replace in a query string.
- query (String, Array or Object) — same of
Callback (callback):
{};
Model.findById(id, callback)
Find a node by Id.
Example:
Actor;
Parameters:
- id (Integer) — node Id
Callback (callback):
{};
## Model.findByIdAndRemove(id, callback)
Find a node by Id and remove.
**Example:**
```javascript
Actor.findByIdAndRemove(12, function (err, item) {
if (err)
return console.error("Error: ", err);
console.log("Removed: ", item);
});
Parameters:
- id (Integer) — node Id
Callback (callback):
{};
Model.findByIdAndUpdate(id, data = {}, callback)
Find a node by Id and update.
Example:
Actor;
Parameters:
- id (Integer) — node Id
- data (Object) — keys to update
Callback (callback):
{};
model = new Model(data = {})
Create a new model instance
Example:
first_name: "Johnny" last_name: "Depp";
Parameters:
- data (Object) — list of properties
Return:
A new Relationship model instance
model.save(callback)
Create or update model properties in the database
Example:
model;
Callback (callback):
{};
model.remove(callback)
Remove item from the database
Example:
model;
Callback (callback):
{};
model.findOutgoing(options = {}, callback)
Find all outgoing relationships
Example:
model;
Parameters:
- options (Object)
- type (String) — Relationship type to be found
- query (String, Array or Object) — same of
Model.update()
- params (Object) — list of keys (param name) and values to replace in a query string.
Callback (callback):
{};
model.findIncoming(options = {}, callback)
Find all incoming relationships
Parameters:
- options (Object)
- type (String) — Relationship type to be found
- query (String, Array or Object) — same of
Model.update()
- params (Object) — list of keys (param name) and values to replace in a query string.
Callback (callback):
{};
model.findRelates(options = {}, callback)
Find all incoming and outgoing relationships
Parameters:
- options (Object)
- type (String) — Relationship type to be found
- query (String, Array or Object) — same of
Model.update()
- params (Object) — list of keys (param name) and values to replace in a query string.
Callback (callback):
{};
model.getId()
Get the current item Id
model.getLabel()
Get the name of the label/model appley to the the current item
Node utils
neoogm.findNodeById(id, callback)
Find an node by Id and get back a node model instance.
Example:
neoogm;
Parameters:
- id (Integer) — node Id
Callback (callback):
{};
Relationship model
neoogm.relationship(name, [options = {}])
Used to define or retrieve a ORM relationship.
Examples:
RelPlayed = neoogm;
Options Hash (options):
- relates (Array of strings) — List of outgoing relationships between nodes
- schema (Object) — have to be completed, if you're in
strict
mode, neoorm.js save into the remote database only the declared keys found in the schema. - scrict (Boolean) — partially implemented right now
- created_at (Boolean or String) — overwrite the default
relationship.created_at
property defined withneoorm.config()
- updated_at (Boolean or String) — overwrite the default
relationship.updated_at
property defined withneoorm.config()
rel = new Rel(data = {})
Create a new model instance
Example:
async;
Parameters:
- data (Object) — list of properties
- _start (Integer or Node Model) — List of outgoing relationships between nodes
- _end (Integer or Node Model) — have to be completed, if you're in
strict
mode, neoorm.js save into the remote database only the declared keys found in the schema.
Return:
A new Relationship model instance
rel.save(callback)
Create or update relationship properties in the database
Example:
neo;
Callback (callback):
{};
rel.remove(callback)
Remove relationship from the database
Example:
neo;
Callback (callback):
{};
model.getId()
Get the current item Id
model.getType()
Get the type of the relationship/model appley to the the current item
model.getStart(callback)
Get the related node
Callback (callback):
{};
model.getEnd(callback)
Get the related node
Callback (callback):
{};
Relationship utils
neoogm.findRelationshipById(id, callback)
Find an relationship by Id and get back a relationship model instance.
Example:
neoogm;
Parameters:
- id (Integer) — relationship Id
Callback (callback):
{};
Cypher query
neoogm.cypher(options = {}, callback)
Send a cypher query to the remote database
Examples:
neoogm;
Options Hash (options):
- one (Boolean) — Limit query to one item (callback will return an object insted of an array of objects)
- query (String, Array or Object) — filter rules, can be:
- String — a Cypher query string to append after the WHERE clause; this string can have params like
{name}
(seeparams
) - Array — with complex query can be usefull pass an array of strings; their are joined together
- Object — when you want alter all the models with a
=
match rule, you can pass an hash of key (field name) and values)
- String — a Cypher query string to append after the WHERE clause; this string can have params like
- params (Object) — list of keys (param name) and values to replace in a query string.
- model (Array) — list of model names to wrap RETURN values
Callback (callback):
{};