Functions
Aggregation
To calculate aggregated data, Cypher offers aggregation.
Count
The count function returns the number of result rows. The count function can print out the number of vertices, edges, or the number of properties, and can also be given an alias.
Examples
MATCH (v:person)
RETURN count(v);
MATCH (v:person)-[k:knows]->(p)
RETURN count(*);
MATCH (v:person)
RETURN count(v.name) AS CNT;
Sum
The sum function returns the sum of the numeric values. You must cast the property because it is the sum of the numeric values.
Examples
MATCH (v:person)
RETURN sum(v.age::int);
Average
The avg function returns the average of the numeric values. You must cast the property because it is the sum of the numeric values.
Examples
MATCH (v:person)
RETURN avg(v.age::float);
Minimum and Maximum
The min function returns the smallest value for the numeric value, and the max function returns the largest value.
Examples
MATCH (v:person)
RETURN min(v.age);
MATCH (v:person)
RETURN max(v.age);
Standard Deviation
The stdDev function is a function that returns the standard deviation. The stdDev function returns the standard deviation of the sample population and must cast the property.
Examples
MATCH (v:person)
RETURN stdDev(v.age::float);
Predicate
all( )
Checks whether a given predicate holds true for all elements in a list.
Syntax
all(var IN list WHERE predicate)
Arguments
var: A variable representing each element in the list.
list: The collection to be evaluated.
predicate: A boolean expression applied to each element.
Return Type
boolean: true if the predicate is true for all elements, false otherwise.
Example
-- Check if all numbers are greater than 10
RETURN all(x IN [11, 192, 13] WHERE x > 10);
Result
all
-----
t
any( )
Checks whether the predicate holds true for at least one element in a list.
Syntax
any(var IN list WHERE predicate)
Arguments
var: A variable representing each element in the list.
list: The collection to be evaluated.
predicate: A boolean expression applied to each element.
Return Type
boolean: true if the predicate is true for any elements, false otherwise.
Example
-- Check if any number is greater than 15
RETURN any(x IN [9, 12, 16] WHERE x > 15);
Result
any
-----
t
none( )
Checks whether no element in the list satisfies the predicate.
Syntax
none(var IN list WHERE predicate)
Arguments
var: A variable representing each element in the list.
list: The collection to be evaluated.
predicate: A boolean expression applied to each element.
Return Type
boolean: true if none of the elements satisfy the condition, false if at least one element does.
Example
-- Check if none of the numbers are negative
RETURN none(x IN [5, 11, 23] WHERE x < 0);
Result
none
------
t
single( )
Checks whether exactly one element in the list satisfies the predicate.
Syntax
single(var IN list WHERE predicate)
Arguments
var: A variable representing each element in the list.
list: The collection to be evaluated.
predicate: A boolean expression applied to each element.
Return Type
boolean: true if exactly one element matches, false otherwise.
Example
-- Check if exactly one number is even
RETURN single(x IN [3, 6, 7] WHERE x % 2 = 0);
Result
single
--------
t
Scalar
size( )
The size function returns the number of patterns specified as arguments. It is the same as the result of the count function that assigns a variable to the entire pattern and takes the variable as its argument.
Examples
MATCH (a:person {name: 'Jack'})
RETURN size((a)-[]->());
MATCH p=(a:person {name: 'Jack'})-[]->()
RETURN count(p);
length( )
The length function returns the length of a string or path. If the argument is specified as a character of a string or string type, the number of characters in the string is returned.
Examples
RETURN length('string');
MATCH (a:person)
WHERE length(a.name) > 4
RETURN a.name;
List
nodes()
The nodes function returns the vertices in the path passed as arguments. There are cautions when passing arguments to the nodes function. MATCH clause to find a path that matches the pattern, assign a variable, and pass that variable as an argument. You can not pass the path itself as an argument to the nodes function, but you should always pass it as variable. When used with the length function, the number of vertices in the path can be found.
Examples
MATCH p=(a)-[]->()-[]->(b)
WHERE a.name = 'Jack' and b.name = 'Rachel'
RETURN nodes(p);
RETURN nodes( ({name: 'Jack'})-[]->()-[]->({name: 'Rachel'}) ); (X)
MATCH p=(a)-[]->()-[]->(b)
WHERE a.name = 'Jack' and b.name = 'Rachel'
RETURN length(nodes(p));
relationships()
The relationships function returns the edges that exist in the path passed as an argument. There are cautions when passing arguments to the relationships function. MATCH clause to find a path that matches the pattern, assign a variable, and pass that variable as an argument. You can not pass the path itself as an argument to the relationships function, but you should always pass it as variable. When used with the count function, the number of edge in the path can be found.
Examples
MATCH p=(a)-[]->()-[]->(b)
WHERE a.name = 'Jack' and b.name = 'Rachel'
RETURN relationships(p);
RETURN relationships( ({name: 'Jack'})-[]->()-[]->({name: 'Rachel'}) ); (X)
MATCH p=(a)-[]->()-[]->(b)
WHERE a.name = 'Jack' and b.name = 'Rachel'
RETURN count(relationships(p));
label()
The label function returns the vlabel of the vertex passed as an argument. If the vlabel of that vertex inherits another vlabel, it also returns the parent vlabel. There are cautions when passing arguments to the label function. MATCH clause to find a vertex that matches the pattern, assign a variable, and pass that variable as an argument. The vertex itself can not be passed as an argument to the label function, but must always be passed as variable.
Examples
MATCH (a)
WHERE a.name='Jack'
RETURN label(a);
RETURN label(({name: 'Jack'})); (X)
type()
The type function returns the elabel of the edge passed as an argument. If the elabel of that edge inherits another elabel, it also returns the parent elabel. There is a caution when passing arguments to the type function. MATCH clause to find the edge that matches the pattern, assign the variable, and then pass the variable as an argument. The edge itself can not be passed as an argument to the type function, but must always be passed as variable.
Examples
MATCH ({name: 'Jack'})-[r]->({name:'Emily'})
RETURN type(r);
RETURN type(({name: 'Jack'})-[r]->({name:'Emily'})); (X)
start_id()
Returns the identifier of the starting (source) vertex of a given edge.
Syntax
start_id(edge)
Arguments
edge: The edge expression from which to retrieve the source vertex ID.
Return Type
graphid: The internal identifier of the source vertex.
Example
-- Retrieve source vertex IDs of all edges
MATCH ()-[e]->()
RETURN start_id(e);
Result
start_id
----------
3.1
3.2
end_id()
Returns the identifier of the ending (target) vertex of a given edge.
Syntax
end_id(edge)
Arguments
edge: The edge expression from which to retrieve the target vertex ID.
Return Type
graphid: The internal identifier of the target vertex.
Example
-- Retrieve target vertex IDs of all edges
MATCH ()-[e]->()
RETURN end_id(e);
Result
end_id
--------
5.10
5.34
Path
shortestpath()
Finds a single shortest path between two vertices. If multiple shortest paths exist, one arbitrary path is returned.
Syntax
shortestpath(path_pattern)
Arguments
path_pattern: A Cypher path expression between two nodes, optionally including direction and variable-length hops.
Return Type
path: The shortest path as a graph path object.
Example
-- Find the shortest path between person 3 and 5
MATCH (p:person {id: 3}), (f:person {id: 5})
RETURN nodes(shortestpath((p)-[:knows*]->(f))) AS ids;
Result
ids
---------
{3,4,5}
allshortestpaths()
Finds all shortest paths of equal minimal length between two vertices.
Syntax
allshortestpaths(path_pattern)
Arguments
path_pattern: A Cypher path expression between two nodes, optionally including direction and variable-length hops.
Return Type
setof path: A set of all shortest paths between the vertices.
Example
-- Count all shortest paths between person 1 and 5
MATCH (p:person {id: 1}), (f:person {id: 5})
RETURN length(allshortestpaths((p)-[:knows*]-(f))) AS cnt;
Result
cnt
-----
2
dijkstra()
The dijkstra() function computes the shortest path between two vertices in a graph using Dijkstra’s algorithm. It finds the path with the minimum total weight, where weights are defined by a property on the edges.
Syntax
dijkstra(pattern, weight)
dijkstra(pattern, weight, qual)
dijkstra(pattern, weight, LIMIT count)
dijkstra(pattern, weight, qual, LIMIT count)
Arguments
path_pattern: A Cypher path chain, e.g. (a)-[e:REL]->(b).
weight_expr: An edge property or expression that determines traversal cost (e.g. e.weight).
qual (optional): A boolean filter on edges (e.g. e.weight >= 5).
LIMIT count (optional): Restricts the number of returned paths.
Return Type
path if assigned to a variable (e.g. p = dijkstra(…)).
A tuple (path, cost) if returned in assignment (p, x) = dijkstra(…).
Example 1
-- Basic weighted shortest path
MATCH (v1:v {id: 0}), (v2:v {id: 3}),
p = dijkstra((v1)-[e:e]->(v2), e.weight)
RETURN nodes(p);
Result
nodes
---------
{0,4,6,3}
Example 2
-- Weighted shortest path with condition
MATCH (v1:v {id: 0}), (v2:v {id: 3}),
p = dijkstra((v1)-[e:e]->(v2), e.weight, e.weight >= 5)
RETURN nodes(p);
Result
nodes
---------
{0,1,5,3}
Example 3
-- Return path and total cost with LIMIT
MATCH (v1:v {id: 0}), (v2:v {id: 3}),
(p, x) = dijkstra((v1)-[e:e]->(v2), e.weight, LIMIT 2)
RETURN nodes(p), x;
Result
nodes | x
-----------+-----
{0,4,3} | 14
{0,1,2,3} | 13
Math
Number functions
abs()
The abs function returns an absolute value of the numeric value passed as an argument. You can pass a decimal number or a subtraction as an argument. The MATCH clause can be used to find a particular element and pass a subtraction of the properties, which are numeric values, among the properties of the elements.
Examples
RETURN abs(-3.14);
RETURN abs(20-45);
MATCH (a {name:'Jack'}), (b {name:'Emily'})
RETURN abs(a.age::int-b.age::int);
ceil(), floor(), round()
The ceil function returns the numeric value passed as an argument by rounding it to the first decimal place. The floor function returns the numeric value passed as an argument, rounded down to the first decimal place. The round function rounds the numeric value passed as an argument to the first decimal place.
Examples
RETURN ceil(3.1);
RETURN ceil(1);
RETURN ceil(-12.19);
RETURN floor(3.1);
RETURN floor(1);
RETURN floor(-12.19);
RETURN round(3.1);
RETURN round(3.6);
RETURN round(-12.19);
RETURN round(-12.79);
sign()
The sign function returns the sign of the numeric value passed as an argument. Returns ‘1’ if the argument passed is positive, ‘-1’ if negative, ‘0’ if zero.
Examples
RETURN sign(25);
RETURN sign(-19.93);
RETURN sign(0);
Logarithmic functions
exp()
The exp function returns a power value that exponents the numeric value passed as an argument, under the natural constant (e). That is, exp (1) returns e^1^ ≒ 2.71828182845905, exp (2) returns e^2^ ≒ 7.38905609893065 and exp (-1) returns e -1^ ≒ 0.367879441171442.
Examples
RETURN exp(1);
RETURN exp(2);
RETURN exp(-1);
sqrt()
The sqrt function returns the square root of the numeric value passed as an argument. The sqrt function can not pass a negative number as an argument.
Examples
RETURN sqrt(25);
RETURN sqrt(-16);
Trigonometric functions
sin()/cos()/tan()
The sine function returns the sine value of the numeric value passed as an argument, the cos function returns the cosine value of the numeric value passed as an argument, and the tan function returns the tangent value of the numeric value passed as an argument.
Examples
RETURN sin(0.5);
RETURN sin(-1.5);
RETURN cos(0);
RETURN cos(-1);
RETURN tan(0);
RETURN tan(15.2);
cot()
The cot function is the cotangent value (the inverse of the tangent) of the numeric value passed as an argument, the asin function is the arcsine value (inverse of sine) of the numeric value passed as the argument, and the acos function is the arccosine value of the numeric value passed as the argument (The inverse of cosine), and the atan and atan2 functions return the arctangent value (inverse of tangen) of the numeric value passed as an argument. The argument range of the asin and acos functions is a numeric value between -1 and 1. atan2 has two arguments in order to make the atan function more granular. Conceptually, atan2 (a, b) is equivalent to atan (a / b). However, it is not clear if atan (-5) is atan (-15/3) and atan (15 / (- 3)). The trigonometric function requires a definite distinction because the argument is a radian value. Therefore, using atan2 rather than atan makes it more accurate.
Examples
RETURN cot(1.5);
RETURN asin(1);
RETURN acos(0.5);
RETURN atan(-1);
RETURN atan2(-1.5, 1.3);
pi()/degrees()/radians()
The pi function returns pi as a number. The degrees function recognizes the passed arguments as radians and returns them to degrees (angles). The radians function converts the arguments passed to radians and returns them as radians.
Examples
RETURN pi();
RETURN degrees(12.3);
RETURN degrees(pi());
RETURN radians(180);
String
replace()
The replace function is a function that changes the second argument to the third if there is a second argument in the first argument.
Examples
RETURN replace('ABCDEFG', 'C', 'Z');
RETURN replace('ABCDEFG', 'CD', 'Z');
RETURN replace('ABCDEFG', 'C', 'ZX');
RETURN replace('ABCDEFG', 'CD', 'ZXY');
substring()
The substring function prints the first argument passed from the second argument. The third argument indicates how many characters to print. If there is no third argument and it is greater than the number of characters in the first argument, it is printed to the end.
Examples
RETURN substring('ABCDEFG', 2);
RETURN substring('ABCDEFG', 2, 3);
RETURN substring('ABCDEFG', 4, 10);
left()/right()
The left function prints the first argument from the left, and the right function prints the second number of characters from the right. If the value of the second argument is larger than the number of characters remaining, the number of characters remaining is output.
Examples
RETURN left('AAABBB', 3);
RETURN right('AAABBB', 3);
lTrim()/rTrim()
The lTrim function removes the left blank from the argument passed to it and the right blank from the rTrim function.
Examples
RETURN lTrim(' ABCD ');
RETURN rTrim(' ABCD ');
lower()/upper()
The lower function is a function that converts all passed arguments to lower case and the upper function to upper case.
Examples
RETURN lower('AbCdeFG');
RETURN upper('AbCdeFG');
reverse()
The reverse function is a function that reverses the passed arguments.
Examples
RETURN reverse('ABCDEFG');