Neo4j::Cypher Functions

Predicates

Predicates are commonly used to filter out subgraphs in the WHERE part of a query but can also be used on property arrays (!), see http://docs.neo4j.org/chunked/1.8/query-function.html

all?

Example: Return the path where all the predicate holds for all element of this collection:

(node(3)>'*1..3'>node(1)).nodes.all?{|n| n[:age] > 30} 

Generates: START v2=node(3),v3=node(1) MATCH v1 = (v2)-[*1..3]->(v3) WHERE all(x in nodes(v1) WHERE x.age > 30) RETURN nodes(v1)

single?

Returns true if the predicate holds for exactly one of the elements in the collection. Similar syntax to all?, see above.

any?

Tests whether a predicate holds for at least one element in the collection. Similar syntax to all?, see above.

none?

Returns true if the predicate holds for no element in the collection. Similar syntax to all?, see above.

Scalar functions

Scalar functions return a single value, see http://docs.neo4j.org/chunked/1.8/query-function.html

length

Example: To return or filter on the length of a collection, use the length method.

node(3) >> :b >> :c).length

Generates cypher: START v1=node(3) MATCH v2 = (v1)-->(b)-->(c) RETURN length(v2)

A more complex example

ret(:a, :b, :c, (node(3).as(:a) > ':KNOWS*0..1' > :b).length, (node(:b) > ':BLOCKS*0..1' > :c).length)

Is same as START a=node(3) MATCH v1 = (a)-[:KNOWS*0..1]->(b),v2 = (b)-[:BLOCKS*0..1]->(c) RETURN a,b,c,length(v1),length(v2)

rel_type

The rel_type returns a string representation of the relationship type, example:

node(3) > (r = rel) > node; r.rel_type

Generates: START v1=node(3) MATCH (v1)-[?]->(v2) RETURN type(v3)

neo_id

The neo_id method (same name as used in neo4j-core gem) returns the id of the relationship or node.

node(3,4,5).neo_id 

Generates START v1=node(3,4,5) RETURN ID(v1)

coalesce

Returns the first non-null value in the list of expressions passed to it, example:

n=node(3); coalesce(n[:hair_colour?], n[:eyes?]) }

Generates: START v1=node(3) RETURN coalesce(v1.hair_colour?, v1.eyes?)

head

Returns the first element in a collection, example:

node(2)[:array].head 

Generates: START v1=node(2) RETURN head(v1.array)

last

last returns the last element in a collection. Similar syntax to head, see above.

Collection functions

Collection functions return collections of things — nodes in a path, and so on. This is typically used on paths. Remember that the >, << (etc...) operators returns paths, but the outgoing, incoming returns the end nodes.

nodes

Returns all nodes in a path, example:

(node(3) >> :b >> node(2)).nodes

Generates: START v1=node(3),v2=node(2) MATCH v3 = (v1)-->(b)-->(v2) RETURN nodes(v3)

rels

Returns all relationships in a path.

node(3) >> :b >> node(2)).rels 

Generates: START v1=node(3),v2=node(2) MATCH v3 = (v1)-->(b)-->(v2) RETURN relationships(v3)

extract

To return a single property, or the value of a function from a collection of nodes or relationships, you can use extract. It will go through a collection, run an expression on every element, and return the results in an collection with these values. It works like the map method in Ruby, example:

(node(3) >> node(4) >> node(1)).nodes.extract{|n| n[:age]}}

Generates START v2=node(3),v3=node(4),v4=node(1) MATCH v1 = (v2)-->(v3)-->(v4) RETURN extract(x in nodes(v1) : x.age)

Using The Ruby Ampersand Colon Shortcut

Methods like extract can also use the ruby ambersand colon shortcut. The example above can also be written like:

(node(3) >> node(4) >> node(1)).nodes.extract(&:age)

filter

filter returns all the elements in a collection that comply to a predicate, example:

a=node(2).as(:a)
ret a[:array], a[:array].filter{|n| n.length == 3} }

Generates: START a=node(2) RETURN a.array,filter(x in a.array : length(x) = 3)

tail

tail returns all but the first element in a collection, example:

node(2)[:array].tail

=> "START v1=node(2) RETURN tail(v1.array)"

range

Not implemented yet.

Mathematical functions

These functions all operate on numerical expressions only, and will return an error if used on any other values.

abs

abs returns the absolute value of a number, example

(node(1)[:age] - node(2)[:age]).abs

Generates: START v1=node(1),v2=node(2) RETURN abs(v1.age - v2.age)

round

Similar syntax to abs, see above

sqrt

Similar syntax to abs, see above

sign

Similar syntax to abs, see above

Complex Example

match { node(1) > :merged_into > node(:c1) }
p = match{node(:c1) > ':merged_into*1..' > node(:b)}
with_match(node(:c1), p.length.max) { |c1, l| c1 > ':merged_into*1..' > node(:b); p.length == l }
ret p.nodes.extract(&:cluster_size)

Same as:

START v3=node(1) MATCH (v3)-[:`merged_into`]->(c1),v1 = (c1)-[:merged_into1..]->(b) WITH c1,max(length(v1)) as v2 MATCH (c1)-[:merged_into1..]->(b) WHERE length(v1) = v2 RETURN extract(x in nodes(v1) : x.cluster_size)

Notice the match{...} method above does nothing except maybe makes the code a bit more readable. You can skip that method.

Summary of Paths methods

A cypher path is return when using the operators like << (inlike outgoing, incoming) The path object has the following useful methods:

• where, example: (node(1) << :person).where{|path| path.nodes.all? { |x| x[:age] > 30 }}.ret(:person)
• where_not
• ret - the path will also be returned from the query
• all?
• extract, example (node(1) >> :b >> :c).nodes.extract{ |n| n[:age]}
• any?
• none?
• single?
• foreach, example: `(node(2) > rel > node(1)).nodes.foreach {|n| n[:marked] = true}
• shortest_path
• shortest_paths
• length