Functions
This section contains information on all supported functions from the Cypher query language.
- Predicate functions
- Scalar functions
- Aggregating functions
- List functions
- Mathematical operators
- Mathematical functions
- Trigonometric functions
- String functions
- Point functions
- Type conversion functions
- Node functions
- Path functions
- Vector functions
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]
arraycan be any expression that produces an array: a literal, a property reference, or a function call.WHERE conditionis 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 elemis 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)
}