Functions

This section contains information on all supported functions from the Cypher query language.

Predicate functions

Function Description
all(var IN list WHERE predicate) Returns true when predicate holds true for all elements in list
any(var IN list WHERE predicate) Returns true when predicate holds true for at least one element in list
exists(pattern) Returns true when at least one match for pattern exists
isEmpty(list|map|string) Returns true if the input list or map contains no elements or if the input string contains no characters
Returns null when the input evaluates to null
none(var IN list WHERE predicate) Returns true when predicate holds false for all elements in list
single(var IN list WHERE predicate) Returns true when predicate holds true for exactly one element in list

Scalar functions

Function Description
coalesce(expr[, expr…]) Returns the evaluation of the first argument that evaluates to a non-null value
Returns null when all arguments evaluate to null
endNode(relationship) Returns the destination node of a relationship
Returns null when relationship evaluates to null
hasLabels(node, labelsList) * Returns true when node contains all labels in labelsList, otherwise false
Return true when labelsList evaluates to an empty list
id(node|relationship) Returns the internal ID of a node or relationship (which is not immutable)
labels(node) Returns a list of strings: all labels of node
Returns null when node evaluates to null
properties(expr) When expr is a node or relationship: Returns a map containing all the properties of the given node or relationship
When expr evaluates to a map: Returns expr unchanged
Returns null when expr evaluates to null
randomUUID() Returns a random UUID (Universal Unique IDentifier)
startNode(relationship) Returns the source node of a relationship
Returns null when relationship evaluates to null
timestamp() Returns the current system timestamp (milliseconds since epoch)
type(relationship) Returns a string: the type of relationship
Returns null when relationship evaluates to null
typeOf(expr) * Returns a string: the type of a literal, an expression’s evaluation, an alias, a node’s property, or a relationship’s property
Return value is one of Map, String, Integer, Boolean, Float, Node, Edge, List, Path, Point, or Null

* FalkorDB-specific extensions to Cypher

Aggregating functions

Function Description
avg(expr) Returns the average of a set of numeric values. null values are ignored
Returns null when expr has no evaluations
collect(expr) Returns a list containing all non-null elements which evaluated from a given expression
count(expr|*) When argument is expr: returns the number of non-null evaluations of expr
When argument is *: returns the total number of evaluations (including nulls)
max(expr) Returns the maximum value in a set of values (taking into account type ordering). null values are ignored
Returns null when expr has no evaluations
min(expr) Returns the minimum value in a set of values (taking into account type ordering). null values are ignored
Returns null when expr has no evaluations
percentileCont(expr, percentile) Returns a linear-interpolated percentile (between 0.0 and 1.0) over a set of numeric values. null values are ignored
Returns null when expr has no evaluations
percentileDisc(expr, percentile) Returns a nearest-value percentile (between 0.0 and 1.0) over a set of numeric values. null values are ignored
Returns null when expr has no evaluations
stDev(expr) Returns the sample standard deviation over a set of numeric values. null values are ignored
Returns null when expr has no evaluations
stDevP(expr) Returns the population standard deviation over a set of numeric values. null values are ignored
Returns null when expr has no evaluations
sum(expr) Returns the sum of a set of numeric values. null values are ignored
Returns 0 when expr has no evaluations

List functions

Function Description
head(expr) Returns the first element of a list
Returns null when expr evaluates to null or an empty list
keys(expr) Returns a list of strings: all key names for given map or all property names for a given node or edge
Returns null when expr evaluates to null
last(expr) Returns the last element of a list
Returns null when expr evaluates to null or an empty list
list.dedup(list) * Given a list, returns a similar list after removing duplicate elements
Order is preserved, duplicates are removed from the end of the list
Returns null when list evaluates to null
Emit an error when list does not evaluate to a list or to null
list.insert(list, idx, val[, dups = TRUE]) * Given a list, returns a list after inserting a given value at a given index
idx is 0-based when non-negative, or from the end of the list when negative
Returns null when list evaluates to null
Returns list when val evaluates to null
Returns list when idx evaluates to an integer not in [-NumItems-1 .. NumItems]
When dups evaluates to FALSE: returns list when val evaluates to a value that is already an element of list
Emit an error when list does not evaluate to a list or to null
Emit an error when idx does not evaluate to an integer
Emit an error when dups, if specified, does not evaluate to a Boolean
list.insertListElements(list, list2, idx[, dups = TRUE]) * Given a list, returns a list after inserting the elements of a second list at a given index
idx is 0-based when non-negative, or from the end of the list when negative
Returns null when list evaluates to null
Returns list when list2 evaluates to null
Returns list when idx evaluates to an integer not in [-NumItems-1 .. NumItems]
When dups evaluates to FALSE: If an element of list2 evaluates to an element of list it would be skipped; If multiple elements of list2 evaluate to the same value - this value would be inserted at most once to list
Emit an error when list does not evaluate to a list or to null
Emit an error when list2 does not evaluate to a list or to null
Emit an error when idx does not evaluate to an integer
Emit an error when dups, if specified, does not evaluate to a Boolean
list.remove(list, idx[, count = 1]) * Given a list, returns a list after removing a given number of consecutive elements (or less, if the end of the list has been reached). starting at a given index.
idx is 0-based when non-negative, or from the end of the list when negative
Returns null when list evaluates to null
Returns list when idx evaluates to an integer not in [-NumItems .. NumItems-1]
Returns list when count evaluates to a non-positive integer
Emit an error when list does not evaluate to a list or to null
Emit an error when idx does not evaluate to an integer
Emit an error when count, if specified, does not evaluate to an integer
list.sort(list[, ascending = TRUE]) * Given a list, returns a list with similar elements, but sorted (inversely-sorted if ascending is evaluated to FALSE)
Returns null when list evaluates to null
Emit an error when list does not evaluate to a list or to null
Emit an error when ascending, if specified, does not evaluate to a Boolean
range(first, last[, step = 1]) Returns a list of integers in the range of [start, end]. step, an optional integer argument, is the increment between consecutive elements
size(expr) Returns the number of elements in a list
Returns null with expr evaluates to null
tail(expr) Returns a sublist of a list, which contains all its elements except the first
Returns an empty list when expr contains less than 2 elements.
Returns null when expr evaluates to null
reduce(…) Returns a scalar produced by evaluating an expression against each list member

* FalkorDB-specific extensions to Cypher

Mathematical operators

Function Description
+ Add two values
- Subtract second value from first
* Multiply two values
/ Divide first value by the second
^ Raise the first value to the power of the second
% Perform modulo division of the first value by the second

Mathematical functions

Function Description
abs(expr) Returns the absolute value of a numeric value
Returns null when expr evaluates to null
ceil(expr) ** When expr evaluates to an integer: returns its evaluation
When expr evaluates to floating point: returns a floating point equals to the smallest integer greater than or equal to expr
Returns null when expr evaluates to null
e() Returns the constant e, the base of the natural logarithm
exp(expr) Returns e^expr, where e is the base of the natural logarithm
Returns null when expr evaluates to null
floor(expr) ** When expr evaluates to an integer: returns its evaluation
When expr evaluates to a floating point: returns a floating point equals to the greatest integer less than or equal to expr
Returns null when expr evaluates to null
log(expr) Returns the natural logarithm of a numeric value
Returns nan when expr evaluates to a negative numeric value, -inf when expr evaluates to 0, and null when expr evaluates to null
log10(expr) Returns the base-10 logarithm of a numeric value
Returns nan when expr evaluates to a negative numeric value, -inf when expr evaluates to 0, and null when expr evaluates to null
pow(base, exponent) * Returns base raised to the power of exponent (equivalent to base^exponent)
Returns null when either evaluates to null
rand() Returns a random floating point in the range [0,1]
round(expr) ** *** When expr evaluates to an integer: returns its evaluation
When expr evaluates to a floating point: returns a floating point equals to the integer closest to expr
Returns null when expr evaluates to null
sign(expr) Returns the signum of a numeric value: 0 when expr evaluates to 0, -1 when expr evaluates to a negative numeric value, and 1 when expr evaluates to a positive numeric value
Returns null when expr evaluates to null
sqrt(expr) Returns the square root of a numeric value
Returns nan when expr evaluates to a negative value and null when expr evaluates to null

* FalkorDB-specific extensions to Cypher

** FalkorDB-specific behavior: to avoid possible loss of precision, when expr evaluates to an integer - the result is an integer as well

*** FalkorDB-specific behavior: tie-breaking method is “half away from zero”

Trigonometric functions

Function Description
acos(expr) Returns the arccosine, in radians, of a numeric value
Returns nan when expr evaluates to a numeric value not in [-1, 1] and null when expr evaluates to null
asin(expr) Returns the arcsine, in radians, of a numeric value
Returns nan when expr evaluates to a numeric value not in [-1, 1] and null when expr evaluates to null
atan(expr) Returns the arctangent, in radians, of a numeric value
Returns null when expr evaluates to null
atan2(expr, expr) Returns the 2-argument arctangent, in radians, of a pair of numeric values (Cartesian coordinates)
Returns 0 when both expressions evaluate to 0
Returns null when either expression evaluates to null
cos(expr) Returns the cosine of a numeric value that represents an angle in radians
Returns null when expr evaluates to null
cot(expr) Returns the cotangent of a numeric value that represents an angle in radians
Returns inf when expr evaluates to 0 and null when expr evaluates to null
degrees(expr) Converts a numeric value from radians to degrees
Returns null when expr evaluates to null
haversin(expr) Returns half the versine of a numeric value that represents an angle in radians
Returns null when expr evaluates to null
pi() Returns the mathematical constant pi
radians(expr) Converts a numeric value from degrees to radians
Returns null when expr evaluates to null
sin(expr) Returns the sine of a numeric value that represents an angle in radians
Returns null when expr evaluates to null
tan(expr) Returns the tangent of a numeric value that represents an angle in radians
Returns null when expr evaluates to null

String functions

Function Description
left(str, len) Returns a string containing the len leftmost characters of str
Returns null when str evaluates to null, otherwise emit an error if len evaluates to null
lTrim(str) Returns str with leading whitespace removed
Returns null when str evaluates to null
replace(str, search, replace) Returns str with all occurrences of search replaced with replace
Returns null when any argument evaluates to null
reverse(str) Returns a string in which the order of all characters in str are reversed
Returns null when str evaluates to null
right(str, len) Returns a string containing the len rightmost characters of str
Returns null when str evaluates to null, otherwise emit an error if len evaluates to null
rTrim(str) Returns str with trailing whitespace removed
Returns null when str evaluates to null
split(str, delimiter) Returns a list of strings from splitting str by delimiter
Returns null when any argument evaluates to null
string.join(strList[, delimiter = ‘’]) * Returns a concatenation of a list of strings using a given delimiter
Returns null when strList evaluates to null
Returns null when delimiter, if specified, evaluates to null
Emit an error when strList does not evaluate to a list or to null
Emit an error when an element of strList does not evaluate to a string
Emit an error when delimiter, if specified, does not evaluate to a string or to null
string.matchRegEx(str, regex) * Given a string and a regular expression, returns a list of all matches and matching regions
Returns an empty list when str evaluates to null
Returns an empty list when regex evaluates to null
Emit an error when str does not evaluate to a string or to null
Emit an error when regex does not evaluate to a valid regex string or to null
string.replaceRegEx(str, regex, replacement) * Given a string and a regular expression, returns a string after replacing each regex match with a given replacement
Returns null when str evaluates to null
Returns null when regex evaluates to null
Returns null when replacement evaluates to null
Emit an error when str does not evaluate to a string or to null
Emit an error when regex does not evaluate to a valid regex string or to null
Emit an error when replacement does not evaluate to a string or to null
substring(str, start[, len]) When len is specified: returns a substring of str beginning with a 0-based index start and with length len
When len is not specified: returns a substring of str beginning with a 0-based index start and extending to the end of str
Returns null when str evaluates to null
Emit an error when start or len evaluate to null
toLower(str) Returns str in lowercase
Returns null when str evaluates to null
toJSON(expr) * Returns a JSON representation of a value
Returns null when expr evaluates to null
toUpper(str) Returns str in uppercase
Returns null when str evaluates to null
trim(str) Returns str with leading and trailing whitespace removed
Returns null when str evaluates to null
size(str) Returns the number of characters in str
Returns null when str evaluates to null

* FalkorDB-specific extensions to Cypher

Point functions

Function Description
point(map) Returns a Point representing a lat/lon coordinates
distance(point1, point2) Returns the distance in meters between the two given points
Returns null when either evaluates to null

Type conversion functions

Function Description
toBoolean(expr) Returns a Boolean when expr evaluates to a Boolean
Converts a string to Boolean ("true" (case insensitive) to true, "false" (case insensitive) to false, any other value to null)
Converts an integer to Boolean (0 to false, any other values to true)
Returns null when expr evaluates to null
Emit an error on other types
toBooleanList(exprList) Converts a list to a list of Booleans. Each element in the list is converted using toBooleanOrNull()
toBooleanOrNull(expr) Returns a Boolean when expr evaluates to a Boolean
Converts a string to Boolean ("true" (case insensitive) to true, "false" (case insensitive) to false, any other value to null)
Converts an integer to Boolean (0 to false, any other values to true)
Returns null when expr evaluates to null
Returns null for other types
toFloat(expr) Returns a floating point when expr evaluates to a floating point
Converts an integer to a floating point
Converts a string to a floating point or null
Returns null when expr evaluates to null
Emit an error on other types
toFloatList(exprList) Converts a list to a list of floating points. Each element in the list is converted using toFloatOrNull()
toFloatOrNull(expr) Returns a floating point when expr evaluates to a floating point
Converts an integer to a floating point
Converts a string to a floating point or null
Returns null when expr evaluates to null
Returns null for other types
toInteger(expr) * Returns an integer when expr evaluates to an integer
Converts a floating point to integer
Converts a string to an integer or null
Converts a Boolean to an integer (false to 0, true to 1) Returns null when expr evaluates to null
Emit an error on other types
toIntegerList(exprList) * Converts a list to a list of integer values. Each element in the list is converted using toIntegerOrNull()
toIntegerOrNull(expr) * Returns an integer when expr evaluates to an integer
Converts a floating point to integer
Converts a string to an integer or null
Converts a Boolean to an integer (false to 0, true to 1) Returns null when expr evaluates to null
Returns null for other types
toString(expr) Returns a string when expr evaluates to a string
Converts an integer, float, Boolean, string, or point to a string representation
Returns null when expr evaluates to null
Emit an error on other types
toStringList(exprList) Converts a list to a list of strings. Each element in the list is converted using toStringOrNull()
toStringOrNull(expr) Returns a string when expr evaluates to a string
Converts an integer, float, Boolean, string, or point to a string representation
Returns null when expr evaluates to null
Returns null for other types

* FalkorDB-specific behavior: rounding method when converting a floating point to an integer is “toward negative infinity (floor)”

Node functions

Function Description
indegree(node [, reltype …]) *
indegree(node [, reltypeList]) *
When no relationship types are specified: Returns the number of node’s incoming edges
When one or more relationship types are specified: Returns the number of node’s incoming edges with one of the given relationship types
Return null when node evaluates to null
outdegree(node [, reltype …]) *
outdegree(node [, reltypeList]) *
When no relationship types are specified: Returns the number of node’s outgoing edges
When one or more relationship types are specified: Returns the number of node’s outgoing edges with one of the given relationship types
Return null when node evaluates to null

* FalkorDB-specific extensions to Cypher

Path functions

Function Description
nodes(path) Returns a list containing all the nodes in path
Returns null if path evaluates to null
relationships(path) Returns a list containing all the relationships in path
Returns null if path evaluates to null
length(path) Return the length (number of edges) of path
Returns null if path evaluates to null
shortestPath(…) * Return the shortest path that resolves the given pattern

* FalkorDB-specific extensions to Cypher

Vector functions

Function Description
vecf32(array) Creates a new float 32 vector
all elements of input array must be of type float
vec.euclideanDistance(vector, vector) Returns the Euclidean distance between the two input vectors
vec.cosineDistance(vector, vector) Returns the Cosine distance between the two input vectors

List comprehensions

List comprehensions are a syntactical construct that accepts an array and produces another based on the provided map and filter directives.

They are a common construct in functional languages and modern high-level languages. In Cypher, they use the syntax:

[element IN array WHERE condition | output elem]
  • array can be any expression that produces an array: a literal, a property reference, or a function call.
  • WHERE condition is an optional argument to only project elements that pass a certain criteria. If omitted, all elements in the array will be represented in the output.
  • | output elem is an optional argument that allows elements to be transformed in the output array. If omitted, the output elements will be the same as their corresponding inputs.

The following query collects all paths of any length, then for each produces an array containing the name property of every node with a rank property greater than 10:

MATCH p=()-[*]->() RETURN [node IN nodes(p) WHERE node.rank > 10 | node.name]

Existential comprehension functions

The functions any(), all(), single() and none() use a simplified form of the list comprehension syntax and return a boolean value.

any(element IN array WHERE condition)

They can operate on any form of input array, but are particularly useful for path filtering. The following query collects all paths of any length in which all traversed edges have a weight less than 3:

MATCH p=()-[*]->() WHERE all(edge IN relationships(p) WHERE edge.weight < 3) RETURN p

Pattern comprehensions

Pattern comprehensions are a method of producing a list composed of values found by performing the traversal of a given graph pattern.

The following query returns the name of a Person node and a list of all their friends’ ages:

MATCH (n:Person)
RETURN
n.name,
[(n)-[:FRIEND_OF]->(f:Person) | f.age]

Optionally, a WHERE clause may be embedded in the pattern comprehension to filter results. In this query, all friends’ ages will be gathered for friendships that started before 2010:

MATCH (n:Person)
RETURN
n.name,
[(n)-[e:FRIEND_OF]->(f:Person) WHERE e.since < 2010 | f.age]

CASE WHEN

The case statement comes in two variants. Both accept an input argument and evaluates it against one or more expressions. The first WHEN argument that specifies a value matching the result will be accepted, and the value specified by the corresponding THEN keyword will be returned.

Optionally, an ELSE argument may also be specified to indicate what to do if none of the WHEN arguments match successfully.

In its simple form, there is only one expression to evaluate and it immediately follows the CASE keyword:

MATCH (n)
RETURN
CASE n.title
WHEN 'Engineer' THEN 100
WHEN 'Scientist' THEN 80
ELSE n.privileges
END

In its generic form, no expression follows the CASE keyword. Instead, each WHEN statement specifies its own expression:

MATCH (n)
RETURN
CASE
WHEN n.age < 18 THEN '0-18'
WHEN n.age < 30 THEN '18-30'
ELSE '30+'
END

Reduce

The reduce() function accepts a starting value and updates it by evaluating an expression against each element of the list:

RETURN reduce(sum = 0, n IN [1,2,3] | sum + n)

sum will successively have the values 0, 1, 3, and 6, with 6 being the output of the function call.

Point

The point() function expects one map argument of the form:

RETURN point({latitude: lat_value, longitude: lon_val})

The key names latitude and longitude are case-sensitive.

The point constructed by this function can be saved as a node/relationship property or used within the query, such as in a distance function call.

shortestPath

The shortestPath() function is invoked with the form:

MATCH (a {v: 1}), (b {v: 4}) RETURN shortestPath((a)-[:L*]->(b))

The sole shortestPath argument is a traversal pattern. This pattern’s endpoints must be resolved prior to the function call, and no property filters may be introduced in the pattern. The relationship pattern may specify any number of relationship types (including zero) to be considered. If a minimum number of edges to traverse is specified, it may only be 0 or 1, while any number may be used for the maximum. If 0 is specified as the minimum, the source node will be included in the returned path. If no shortest path can be found, NULL is returned.

JSON format

toJSON() returns the input value in JSON formatting. For primitive data types and arrays, this conversion is conventional. Maps and map projections (toJSON(node { .prop} )) are converted to JSON objects, as are nodes and relationships.

The format for a node object in JSON is:

{
  "type": "node",
  "id": id(int),
  "labels": [label(string) X N],
  "properties": {
    property_key(string): property_value X N
  }
}

The format for a relationship object in JSON is:

{
  "type": "relationship",
  "id": id(int),
  "relationship": type(string),
  "properties": {
    property_key(string): property_value X N
  }
  "start": src_node(node),
  "end": dest_node(node)
}