Skip to main content

Functions

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

Predicate functions

FunctionDescription
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 <br> 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

FunctionDescription
coalesce(expr[, expr...])Returns the evaluation of the first argument that evaluates to a non-null value <br> Returns null when all arguments evaluate to null
endNode(relationship)Returns the destination node of a relationship <br> Returns null when relationship evaluates to null
hasLabels(node, labelsList) *Returns true when node contains all labels in labelsList, otherwise false <br> 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 <br> 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 <br> When expr evaluates to a map: Returns expr unchanged <br> Returns null when expr evaluates to null
randomUUID()Returns a random UUID (Universal Unique IDentifier)
startNode(relationship)Returns the source node of a relationship <br> 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 <br> 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 <br> Return value is one of Map, String, Integer, Boolean, Float, Node, Edge, List, Path, Point, or Null
prev(expr) *Stores the previous value and returns it on the next call; returns null on the first call. Useful for variable-length traversal filtering of edges based on the prior value.

* FalkorDB-specific extensions to Cypher

Aggregating functions

FunctionDescription
avg(expr)Returns the average of a set of numeric values. null values are ignored <br> 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 <br> 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 <br> 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 <br> 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 <br> 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 <br> Returns null when expr has no evaluations
stDev(expr)Returns the sample standard deviation over a set of numeric values. null values are ignored <br> Returns null when expr has no evaluations
stDevP(expr)Returns the population standard deviation over a set of numeric values. null values are ignored <br> Returns null when expr has no evaluations
sum(expr)Returns the sum of a set of numeric values. null values are ignored <br> Returns 0 when expr has no evaluations

List functions

FunctionDescription
head(expr)Returns the first element of a list <br> 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 <br> Returns null when expr evaluates to null
last(expr)Returns the last element of a list <br> 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 <br> Order is preserved, duplicates are removed from the end of the list <br> Returns null when list evaluates to null <br> 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 <br> idx is 0-based when non-negative, or from the end of the list when negative <br> Returns null when list evaluates to null <br> Returns list when val evaluates to null <br> Returns list when idx evaluates to an integer not in [-NumItems-1 .. NumItems] <br> When dups evaluates to FALSE: returns list when val evaluates to a value that is already an element of list <br> Emit an error when list does not evaluate to a list or to null <br> Emit an error when idx does not evaluate to an integer <br> 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 <br> idx is 0-based when non-negative, or from the end of the list when negative <br> Returns null when list evaluates to null <br> Returns list when list2 evaluates to null <br> Returns list when idx evaluates to an integer not in [-NumItems-1 .. NumItems] <br> 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 <br> Emit an error when list does not evaluate to a list or to null <br> Emit an error when list2 does not evaluate to a list or to null <br> Emit an error when idx does not evaluate to an integer <br> 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. <br> idx is 0-based when non-negative, or from the end of the list when negative <br> Returns null when list evaluates to null <br> Returns list when idx evaluates to an integer not in [-NumItems .. NumItems-1] <br> Returns list when count evaluates to a non-positive integer <br> Emit an error when list does not evaluate to a list or to null <br> Emit an error when idx does not evaluate to an integer <br> 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) <br> Returns null when list evaluates to null <br> Emit an error when list does not evaluate to a list or to null <br> 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 <br> Returns null with expr evaluates to null
tail(expr)Returns a sublist of a list, which contains all its elements except the first <br> Returns an empty list when expr contains less than 2 elements. <br> 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

FunctionDescription
+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

FunctionDescription
abs(expr)Returns the absolute value of a numeric value <br> Returns null when expr evaluates to null
ceil(expr) **When expr evaluates to an integer: returns its evaluation <br> When expr evaluates to floating point: returns a floating point equals to the smallest integer greater than or equal to expr <br> 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 <br> Returns null when expr evaluates to null
floor(expr) **When expr evaluates to an integer: returns its evaluation <br> When expr evaluates to a floating point: returns a floating point equals to the greatest integer less than or equal to expr <br> Returns null when expr evaluates to null
log(expr)Returns the natural logarithm of a numeric value <br> 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 <br> 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) <br> 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 <br> When expr evaluates to a floating point: returns a floating point equals to the integer closest to expr <br> 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 <br> Returns null when expr evaluates to null
sqrt(expr)Returns the square root of a numeric value <br> 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

FunctionDescription
acos(expr)Returns the arccosine, in radians, of a numeric value <br> 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 <br> 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 <br> 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) <br> Returns 0 when both expressions evaluate to 0 <br> Returns null when either expression evaluates to null
cos(expr)Returns the cosine of a numeric value that represents an angle in radians <br> Returns null when expr evaluates to null
cot(expr)Returns the cotangent of a numeric value that represents an angle in radians <br> Returns inf when expr evaluates to 0 and null when expr evaluates to null
degrees(expr)Converts a numeric value from radians to degrees <br> Returns null when expr evaluates to null
haversin(expr)Returns half the versine of a numeric value that represents an angle in radians <br> Returns null when expr evaluates to null
pi()Returns the mathematical constant pi
radians(expr)Converts a numeric value from degrees to radians <br> Returns null when expr evaluates to null
sin(expr)Returns the sine of a numeric value that represents an angle in radians <br> Returns null when expr evaluates to null
tan(expr)Returns the tangent of a numeric value that represents an angle in radians <br> Returns null when expr evaluates to null

String functions

FunctionDescription
left(str, len)Returns a string containing the len leftmost characters of str <br> Returns null when str evaluates to null, otherwise emit an error if len evaluates to null
lTrim(str)Returns str with leading whitespace removed <br> Returns null when str evaluates to null
replace(str, search, replace)Returns str with all occurrences of search replaced with replace <br> Returns null when any argument evaluates to null
reverse(str)Returns a string in which the order of all characters in str are reversed <br> Returns null when str evaluates to null
right(str, len)Returns a string containing the len rightmost characters of str <br> Returns null when str evaluates to null, otherwise emit an error if len evaluates to null
rTrim(str)Returns str with trailing whitespace removed <br> Returns null when str evaluates to null
split(str, delimiter)Returns a list of strings from splitting str by delimiter <br> Returns null when any argument evaluates to null
string.join(strList[, delimiter = '']) *Returns a concatenation of a list of strings using a given delimiter <br> Returns null when strList evaluates to null <br> Returns null when delimiter, if specified, evaluates to null <br> Emit an error when strList does not evaluate to a list or to null <br> Emit an error when an element of strList does not evaluate to a string <br> 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 <br> Returns an empty list when str evaluates to null <br> Returns an empty list when regex evaluates to null <br> Emit an error when str does not evaluate to a string or to null <br> 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 <br> Returns null when str evaluates to null <br> Returns null when regex evaluates to null <br> Returns null when replacement evaluates to null <br> Emit an error when str does not evaluate to a string or to null <br> Emit an error when regex does not evaluate to a valid regex string or to null <br> 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 <br> When len is not specified: returns a substring of str beginning with a 0-based index start and extending to the end of str <br> Returns null when str evaluates to null <br> Emit an error when start or len evaluate to null
toLower(str)Returns str in lowercase <br> Returns null when str evaluates to null
toJSON(expr) *Returns a JSON representation of a value <br> Returns null when expr evaluates to null
toUpper(str)Returns str in uppercase <br> Returns null when str evaluates to null
trim(str)Returns str with leading and trailing whitespace removed <br> Returns null when str evaluates to null
size(str)Returns the number of characters in str <br> Returns null when str evaluates to null
intern(str)Returns a deduplicated, memory-efficient representation of str <br> Returns null when str evaluates to null

Point functions

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

Type conversion functions

FunctionDescription
toBoolean(expr)Returns a Boolean when expr evaluates to a Boolean <br> Converts a string to Boolean ("true" (case insensitive) to true, "false" (case insensitive) to false, any other value to null) <br> Converts an integer to Boolean (0 to false, any other values to true) <br> Returns null when expr evaluates to null <br> 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 <br> Converts a string to Boolean ("true" (case insensitive) to true, "false" (case insensitive) to false, any other value to null) <br> Converts an integer to Boolean (0 to false, any other values to true) <br> Returns null when expr evaluates to null <br> Returns null for other types
toFloat(expr)Returns a floating point when expr evaluates to a floating point <br> Converts an integer to a floating point <br> Converts a string to a floating point or null <br> Returns null when expr evaluates to null <br> 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 <br> Converts an integer to a floating point <br> Converts a string to a floating point or null <br> Returns null when expr evaluates to null <br> Returns null for other types
toInteger(expr) *Returns an integer when expr evaluates to an integer <br> Converts a floating point to integer <br> Converts a string to an integer or null <br> Converts a Boolean to an integer (false to 0, true to 1) Returns null when expr evaluates to null <br> 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 <br> Converts a floating point to integer <br> Converts a string to an integer or null <br> Converts a Boolean to an integer (false to 0, true to 1) Returns null when expr evaluates to null <br> Returns null for other types
toString(expr)Returns a string when expr evaluates to a string <br> Converts an integer, float, Boolean, string, or point to a string representation <br> Returns null when expr evaluates to null <br> 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 <br> Converts an integer, float, Boolean, string, or point to a string representation <br> Returns null when expr evaluates to null <br> 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

FunctionDescription
indegree(node [, reltype ...]) * <br> indegree(node [, reltypeList]) *When no relationship types are specified: Returns the number of node's incoming edges <br> When one or more relationship types are specified: Returns the number of node's incoming edges with one of the given relationship types <br> Return null when node evaluates to null
outdegree(node [, reltype ...]) * <br> outdegree(node [, reltypeList]) *When no relationship types are specified: Returns the number of node's outgoing edges <br> When one or more relationship types are specified: Returns the number of node's outgoing edges with one of the given relationship types <br> Return null when node evaluates to null

* FalkorDB-specific extensions to Cypher

Path functions

FunctionDescription
nodes(path)Returns a list containing all the nodes in path <br> Returns null if path evaluates to null
relationships(path)Returns a list containing all the relationships in path <br> Returns null if path evaluates to null
length(path)Return the length (number of edges) of path <br> Returns null if path evaluates to null
shortestPath(...) *Return the shortest path that resolves the given pattern
allShortestPaths(...) *Returns all the shortest paths between a pair of entities

* FalkorDB-specific extensions to Cypher

Vector functions

FunctionDescription
vecf32(array)Creates a new float 32 vector <br> 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.

Intern

The intern() function expects a single string argument:

"CREATE (:A {v:intern('VERY LONG STRING')})"

This function deduplicates the input string by storing a single internal copy across the database. It is especially useful for repeated string values—like country names, email domains, or tags—in large graphs. Interned strings can be stored as node or relationship properties, and behave identically to regular strings in queries, with the added benefit of reduced memory usage.

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.

About Path Functions

The following graph:

Road network

represents a road network with 7 cities (A, B, C, and so on) and 11 one-way roads. Each road has a distance (say, in kilometers) and trip time (say, in minutes).

shortestPath

shortestPath returns one of the shortest paths. If there is more than one, only one is retrieved.

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.

Example Usage: Find the shortest path (by number of roads) from A to G

$ GRAPH.QUERY g "MATCH (a:City{name:'A'}),(g:City{name:'G'}) WITH shortestPath((a)-[*]->(g)) as p RETURN length(p), [n in nodes(p) | n.name] as pathNodes"
1) 1) "length(p)"
2) "pathNodes"
2) 1) 1) (integer) 3
2) "[A, D, F, G]"

Road network

allShortestPaths

All allShortestPaths results have, by definition, the same length (number of roads).

Examples Usage: Find all the shortest paths (by number of roads) from A to G

$ GRAPH.QUERY g "MATCH (a:City{name:'A'}),(g:City{name:'G'}) WITH a,g MATCH p=allShortestPaths((a)-[*]->(g)) RETURN length(p), [n in nodes(p) | n.name] as pathNodes"
1) 1) "length(p)"
2) "pathNodes"
2) 1) 1) (integer) 3
2) "[A, D, F, G]"
2) 1) (integer) 3
2) "[A, C, F, G]"
3) 1) (integer) 3
2) "[A, D, E, G]"
4) 1) (integer) 3
2) "[A, B, E, G]"

Using the unbounded traversal pattern (a:City{name:'A'})-[*]->(g:City{name:'G'}), FalkorDB traverses all possible paths from A to G. ORDER BY length(p) LIMIT 5 ensures that you collect only [up to 5 shortest paths (minimal number of relationships). This approach is very inefficient because all possible paths would have to be traversed. Ideally, you would want to abort some traversals as soon as you are sure they would not result in the discovery of shorter paths.

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)
}

Variable length traverse filtering

Consider a logistics network where:

  • Nodes (Warehouse) represent distribution centers.
  • Edges (Shipment) represent routes where packages are shipped.
  • Each shipment has an increasing priority level.

Imagine a package tracking system where deliveries follow a priority-based routing:

  • Each shipment (Shipment) has a priority value (s.priority).
  • We want to ensure that package priority never decreases as it moves through the network.
  • The query filters paths where the previous shipment (prev(s.priority)) has a lower or equal priority than the current one (s.priority).
MATCH p=(:Warehouse)-[s:Shipment]->(:Warehouse)
WHERE coalesce(prev(s.priority), s.priority) <= s.priority
RETURN p
  • MATCH p=(:Warehouse)-[s:Shipment]->(:Warehouse) Finds shipment paths between warehouses.
  • WHERE coalesce(prev(s.priority)) <= s.priority Ensures that priority never decreases along the route.
  • RETURN p Returns valid paths where shipments maintain or increase priority.