borneo.core

Clojure wrapper for Neo4j, a graph database.

See project page (http://github.com/wagjo/borneo) for usage instructions,
documentation and examples.

Notes:
- Using official Neo4j bindings.
- Not using Blueprints interface.
- neo-db holds the current db instance, so that users do not have
  to supply db instance at each call to db operations. This approach has
  of course some drawbacks , but I've found it suitable for my purposes.
- All mutable functions are by default wrapped in transactions. That
  means you don't have to explicitly put them in transactions. The Neo4j
  transaction model allows for fast transaction nesting, so you can easily
  have your own transaction if you have a group of mutable functions.
  In that case just wrap your functions inside with-tx.
- NullPointerException is thrown if there is no open connection to the db.

*exec-eng*

dynamic

Holds an execution engine around the graph database to use for Cypher queries.

*neo-db*

dynamic

Holds the current database instance.

add-label!

(add-label! node name)
Adds the given label to the node.

all-nodes

(all-nodes)
Returns lazy-seq of all nodes in the db.

all-nodes-with-label

(all-nodes-with-label label-name)
Returns lazy-seq of all nodes with the given label.

all-rel-types

(all-rel-types)
Returns lazy seq of all relationship types currently in database.

create-child!

(create-child! node type props)
Creates a node that is a child of the specified parent node
along the specified relationship.
props is a map that defines the properties of the node.
This is a convenience function.

create-labeled-node!

(create-labeled-node! & label-names)
create-node!
(create-node!)(create-node! props & label-names)
Creates a new node, not linked with any other nodes.
Labels can optionally be provided to add to the node.
create-rel!
(create-rel! from type to)
Creates relationship of a supplied type between from and to nodes.

cypher
(cypher query)(cypher query params)
Returns lazy-seq of results from a Cypher query

delete!
(delete! item)
Deletes node or relationship.
Only node which has no relationships attached to it can be deleted.
delete-node!
(delete-node! node)
Delete node and all its relationships.
This is a convenience function.
dynamic-label
(dynamic-label name)
Creates a label with the supplied name

end-node
(end-node r)
Returns end node for given relationship.

find-nodes
(find-nodes label-name key val)
Finds nodes with the supplied label and predicate

get-id
(get-id item)
Returns id for a given node or relationship.
Note that ids are not very good as unique identifiers.
get-path
(get-path)
Returns path to where the database is stored.

index
(index)
Returns the IndexManager paired with this graph database service.

label?
(label? node label-name)
Returns true if the given node
has a label with the supplied name
labels
(labels node)
Lists all labels attached to this node.

node-by-id
(node-by-id id)
Returns node with a given id, or nil if no such node exists.
Note that ids are not very good as unique identifiers.
other-node
(other-node r node)
Returns other node for given relationship.
This is a convenience function.
prop
(prop c k)
Returns property value based on its key.
If property is not found, returns nil.
If property value is string which starts with colon,
it is converted to keyword.
prop?
(prop? c k)
Returns true if given node or relationship contains
property with a given key.
props
(props c)
Returns map of properties for a given node or relationship.
Fetches all properties and can be very resource consuming if node
contains many large properties. This is a convenience function.
If property value is string which starts with colon,
is is converted to keyword.
purge!
(purge!)
Deletes all nodes from database together with all relationships.

read-only?
(read-only?)
Returns true if database is read only.

rel-by-id
(rel-by-id id)
Returns relationship with a given id, or nil if no such relationship exists.
Note that ids are not very good as unique identifiers.
rel-nodes
(rel-nodes r)
Returns the two nodes attached to the given relationship.
This is a convenience function.
rel-type
(rel-type r)
Returns type of given relationship.

rel?
(rel? node)(rel? node type-or-types)(rel? node type direction)
Returns true if there are relationships attached to this node. Syntax:
[node]                - All relationships.
[node type-or-types]  - Relationships of any of specified types with
                        any direction.
[node type direction] - Relationships of specified type and
                        of specified direction. You can supply nil for
                        one of the arguments if you do not care for
                        either direction of relationship type.
Valid directions are :in :out and :both, parameter type can be any keyword.
Examples: (rel? node)                  ; All rels
          (rel? node :foo)             ; Rels of :foo type of any direction
          (rel? node [:foo :bar :baz]) ; Rels of any of specified types,
                                       ; any directions
          (rel? node :foo :in)         ; Rels of :foo type, :in direction
          (rel? node nil :in)          ; Rels of any type of :in direction
          (rel? node :foo nil)         ; Use (rel? node :foo) instead
rels
(rels node)(rels node type-or-types)(rels node type direction)
Returns relationships attached to this node. Syntax:
[node]                - All relationships.
[node type-or-types]  - Relationships of any of specified types with
                        any direction.
[node type direction] - Relationships of specified type and
                        of specified direction. You can supply nil for
                        one of the arguments if you do not care for
                        either direction of relationship type.
Valid directions are :in :out and :both, parameter type can be any keyword.
Examples: (rels node)                  ; All rels
          (rels node :foo)             ; Rels of :foo type of any direction
          (rels node [:foo :bar :baz]) ; Rels of any of specified types,
                                       ; any directions
          (rels node :foo :in)         ; Rels of :foo type, :in direction
          (rels node nil :in)          ; Rels of any type of :in direction
          (rels node :foo nil)         ; Use (rel node :foo) instead
remove-label!
(remove-label! node name)
Removes the supplied label from the node.

ReturnableEvaluator
protocol
Protocol for return evaluation. Used for graph traversing.
Functions:
(returnable-node? [this pos]) - Should return true if node should
                                be returned. pos will be current
                                position map.
members
returnable-node?
(returnable-node? this pos)
set-prop!
(set-prop! c key)(set-prop! c key value)
Sets or remove property for a given node or relationship.
The property value must be one of the valid property types
(see Neo4j docs) or a keyword.
If a property value is nil, removes this property from the given
node or relationship.
set-props!
(set-props! c props)
Sets properties for a given node or relationship.
The property value must be one of the valid property types
(see Neo4j docs) or a keyword.
If a property value is nil, removes this property from the given
node or relationship. This is a convenience function.
single-rel
(single-rel node type)(single-rel node type direction)
Returns the only relationship for the node of the given type and
direction.
Valid directions are :in :out and :both, defaults to :out.
start!
(start! path)
Establish a connection to the database.
Uses *neo-db* Var to hold the connection.
Uses *exec-eng* Var to reuse for Cypher queries.
Do not use this function, use with-db! or with-local-db! instead.
start-node
(start-node r)
Returns start node for given relationship.

stop!
(stop!)
Closes a connection stored in *neo-db*.
Do not use this function, use with-db! or with-local-db! instead.
StopEvaluator
protocol
Protocol for stop evaluation. Used for graph traversing.
Functions:
(stop-node? [this pos]) - Should return true if at stop node.
                          pos will be current position map.
members
stop-node?
(stop-node? this pos)
traverse
(traverse node rel)(traverse node return-eval rel)(traverse node stop-eval return-eval rel)(traverse node order stop-eval return-eval rel)
Traverses the graph. Starting at the given node, traverse the graph
in specified order, stopping based on stop-eval. The return-eval
decides which nodes make it into the result. The rel is used to
decide which edges to traverse.
order - :breadth, :depth. Will be :depth if nil supplied.
stop-eval accepts following values:
  - :end or nil - End of graph.
  - :1, :2, :X (X being any positive integer) - Depth of X.
  - Custom function which takes one argument, current position
    and should return true when at stop node.
return-eval accepts following values:
  - :all-but-start or nil  - all but start nodes.
  - :all - all nodes.
  - Custom function which takes one argument, current position map
    and should return true when node at current position should be returned.
  - Map defining key-value pairs that will be matched against
    properties of wanna-be returned nodes.
rel - Keyword representing relation type or a map where keys are
      relation type keywords and values are directions (:in or :out).
walk
(walk node & types)
Walks through the graph by following specified relations. Returns last node.
Throws NullPointerException if path is wrong.
Throws NotFoundException if path is ambiguous.
with-db!
macro
(with-db! path & body)
Establish a connection to the neo db.
Because there is an overhead when establishing connection, users should
not call this macro often. Also note that this macro is not threadsafe.
with-local-db!
macro
(with-local-db! path & body)
Establish a connection to the neo db. Connection is visible
only in current thread. Because there is an overhead when
establishing connection, users should not call this macro often.
This is a treadsafe version, which limits connection to
the current thread only. This allows you to have parallel
connections to different databases. It is not recommended to use
this function together with with-db! in one program.
with-tx
macro
(with-tx & body)
Establish a transaction. Use it for mutable db operations.
If you do not want to commit it, throw an exception.
All mutable functions use transactions by default, so you don't
have to use this macro. You should use this macro to group your
functions into a bigger transactions.