Functions

This section contains information on all functions in the Cypher® query language.

Related information may be found in Operators.

  • Functions in Cypher® return null if an input parameter is null.

  • Functions taking a string as input all operate on Unicode characters rather than on a standard char[]. For example, the size() function applied to any Unicode character will return 1, even if the character does not fit in the 16 bits of one char.
Example 1. List available functions

To list the available functions, run the following Cypher® query:

SHOW FUNCTIONS

These functions return either true or false for the given arguments.

Function Signature Description

all()

all(variable :: VARIABLE IN list :: LIST OF ANY? WHERE predicate :: ANY?) :: (BOOLEAN?)

Returns true if the predicate holds for all elements in the given list.

any()

any(variable :: VARIABLE IN list :: LIST OF ANY? WHERE predicate :: ANY?) :: (BOOLEAN?)

Returns true if the predicate holds for at least one element in the given list.

exists()

exists(input :: ANY?) :: (BOOLEAN?)

Returns true if a match for the pattern exists in the graph, or if the specified property exists in the node, relationship or map.

isEmpty()

isEmpty(input :: LIST? OF ANY?) :: (BOOLEAN?)

Checks whether a list is empty.

isEmpty(input :: MAP?) :: (BOOLEAN?)

Checks whether a map is empty.

isEmpty(input :: STRING?) :: (BOOLEAN?)

Checks whether a string is empty.

none()

none(variable :: VARIABLE IN list :: LIST OF ANY? WHERE predicate :: ANY?) :: (BOOLEAN?)

Returns true if the predicate holds for no element in the given list.

single()

single(variable :: VARIABLE IN list :: LIST OF ANY? WHERE predicate :: ANY?) :: (BOOLEAN?)

Returns true if the predicate holds for exactly one of the elements in the given list.

These functions return a single value.

Function Signature Description

coalesce()

coalesce(input :: ANY?) :: (ANY?)

Returns the first non-null value in a list of expressions.

endNode()

endNode(input :: RELATIONSHIP?) :: (NODE?)

Returns the end node of a relationship.

head()

head(list :: LIST? OF ANY?) :: (ANY?)

Returns the first element in a list.

id()

id(input :: NODE?) :: (INTEGER?)

Returns the id of a node.

id(input :: RELATIONSHIP?) :: (INTEGER?)

Returns the id of a relationship.

last()

last(list :: LIST? OF ANY?) :: (ANY?)

Returns the last element in a list.

length()

length(input :: PATH?) :: (INTEGER?)

Returns the length of a path.

properties()

properties(input :: MAP?) :: (MAP?)

Returns a map containing all the properties of a map.

properties(input :: NODE?) :: (MAP?)

Returns a map containing all the properties of a node.

properties(input :: RELATIONSHIP?) :: (MAP?)

Returns a map containing all the properties of a relationship.

randomUUID()

randomUUID() :: (STRING?)

Generates a random UUID.

size()

size(input :: LIST? OF ANY?) :: (INTEGER?)

Returns the number of items in a list.

size(input :: STRING?) :: (INTEGER?)

Returns the number of Unicode characters in a string.

startNode()

startNode(input :: RELATIONSHIP?) :: (NODE?)

Returns the start node of a relationship.

timestamp()

timestamp() :: (INTEGER?)

Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

toBoolean()

toBoolean(input :: STRING?) :: (BOOLEAN?)

Converts a string value to a boolean value.

toBoolean(input :: BOOLEAN?) :: (BOOLEAN?)

Converts a boolean value to a boolean value.

toBoolean(input :: INTEGER?) :: (BOOLEAN?)

Converts an integer value to a boolean value.

toBooleanOrNull()

toBooleanOrNull(input :: ANY?) :: (BOOLEAN?)

Converts a value to a boolean value, or null if the value cannot be converted.

toFloat()

toFloat(input :: NUMBER?) :: (FLOAT?)

Converts a number value to a floating point value.

toFloat(input :: STRING?) :: (FLOAT?)

Converts a string value to a floating point value.

toFloatOrNull()

toFloatOrNull(input :: ANY?) :: (FLOAT?)

Converts a value to a floating point value, or null if the value cannot be converted.

toInteger()

toInteger(input :: NUMBER?) :: (INTEGER?)

Converts a number value to an integer value.

toInteger(input :: BOOLEAN?) :: (INTEGER?)

Converts a boolean value to an integer value.

toInteger(input :: STRING?) :: (INTEGER?)

Converts a string value to an integer value.

toIntegerOrNull()

toIntegerOrNull(input :: ANY?) :: (INTEGER?)

Converts a value to an integer value, or null if the value cannot be converted.

type()

type(input :: RELATIONSHIP?) :: (STRING?)

Returns the string representation of the relationship type.

These functions take multiple values as arguments, and calculate and return an aggregated value from them.

Function Signature Description

avg()

avg(input :: DURATION?) :: (DURATION?)

Returns the average of a set of duration values.

avg(input :: FLOAT?) :: (FLOAT?)

Returns the average of a set of floating point values.

avg(input :: INTEGER?) :: (INTEGER?)

Returns the average of a set of integer values.

collect()

collect(input :: ANY?) :: (LIST? OF ANY?)

Returns a list containing the values returned by an expression.

count()

count(input :: ANY?) :: (INTEGER?)

Returns the number of values or rows.

max()

max(input :: ANY?) :: (ANY?)

Returns the maximum value in a set of values.

min()

min(input :: ANY?) :: (ANY?)

Returns the minimum value in a set of values.

percentileCont()

percentileCont(input :: FLOAT?, percentile :: FLOAT?) :: (FLOAT?)

Returns the percentile of a value over a group using linear interpolation.

percentileDisc()

percentileDisc(input :: FLOAT?, percentile :: FLOAT?) :: (FLOAT?)

Returns the nearest floating point value to the given percentile over a group using a rounding method.

percentileDisc(input :: INTEGER?, percentile :: FLOAT?) :: (INTEGER?)

Returns the nearest integer value to the given percentile over a group using a rounding method.

stdev()

stdev(input :: FLOAT?) :: (FLOAT?)

Returns the standard deviation for the given value over a group for a sample of a population.

stdevp()

stdevp(input :: FLOAT?) :: (FLOAT?)

Returns the standard deviation for the given value over a group for an entire population.

sum()

sum(input :: DURATION?) :: (DURATION?)

Returns the sum of a set of durations

sum(input :: FLOAT?) :: (FLOAT?)

Returns the sum of a set of floats

sum(input :: INTEGER?) :: (INTEGER?)

Returns the sum of a set of integers

These functions return lists of other values. Further details and examples of lists may be found in Lists.

Function Signature Description

keys()

keys(input :: MAP?) :: (LIST? OF STRING?)

Returns a list containing the string representations for all the property names of a map.

keys(input :: NODE?) :: (LIST? OF STRING?)

Returns a list containing the string representations for all the property names of a node.

keys(input :: RELATIONSHIP?) :: (LIST? OF STRING?)

Returns a list containing the string representations for all the property names of a relationship.

labels()

labels(input :: NODE?) :: (LIST? OF STRING?)

Returns a list containing the string representations for all the labels of a node.

nodes()

nodes(input :: PATH?) :: (LIST? OF NODE?)

Returns a list containing all the nodes in a path.

range()

range(start :: INTEGER?, end :: INTEGER?) :: (LIST? OF INTEGER?)

Returns a list comprising all integer values within a specified range.

range(start :: INTEGER?, end :: INTEGER?, step :: INTEGER?) :: (LIST? OF INTEGER?)

Returns a list comprising all integer values within a specified range created with step length.

reduce()

reduce(accumulator :: VARIABLE = initial :: ANY?, variable :: VARIABLE IN list :: LIST OF ANY? | expression :: ANY) :: (ANY?)

Runs an expression against individual elements of a list, storing the result of the expression in an accumulator.

relationships()

relationships(input :: PATH?) :: (LIST? OF RELATIONSHIP?)

Returns a list containing all the relationships in a path.

reverse()

reverse(input :: LIST? OF ANY?) :: (LIST? OF ANY?)

Returns a list in which the order of all elements in the original list have been reversed.

tail()

tail(input :: LIST? OF ANY?) :: (LIST? OF ANY?)

Returns all but the first element in a list.

toBooleanList()

toBooleanList(input :: LIST? OF ANY?) :: (LIST? OF BOOLEAN?)

Converts a list of values to a list of boolean values. If any values are not convertible to boolean they will be null in the list returned.

toFloatList()

toFloatList(input :: LIST? OF ANY?) :: (LIST? OF FLOAT?)

Converts a list of values to a list of floating point values. If any values are not convertible to floating point they will be null in the list returned.

toIntegerList()

toIntegerList(input :: LIST? OF ANY?) :: (LIST? OF INTEGER?)

Converts a list of values to a list of integer values. If any values are not convertible to integer they will be null in the list returned.

toStringList()

toStringList(input :: LIST? OF ANY?) :: (LIST? OF STRING?)

Converts a list of values to a list of string values. If any values are not convertible to string they will be null in the list returned.

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

Function Signature Description

abs()

abs(input :: FLOAT?) :: (FLOAT?)

Returns the absolute value of a floating point number.

abs(input :: INTEGER?) :: (INTEGER?)

Returns the absolute value of an integer.

ceil()

ceil(input :: FLOAT?) :: (FLOAT?)

Returns the smallest floating point number that is greater than or equal to a number and equal to a mathematical integer.

floor()

floor(input :: FLOAT?) :: (FLOAT?)

Returns the largest floating point number that is less than or equal to a number and equal to a mathematical integer.

rand()

rand() :: (FLOAT?)

Returns a random floating point number in the range from 0 (inclusive) to 1 (exclusive); i.e. [0,1).

round()

round(input :: FLOAT?) :: (FLOAT?)

Returns the value of a number rounded to the nearest integer.

round(value :: FLOAT?, precision :: NUMBER?) :: (FLOAT?)

Returns the value of a number rounded to the specified precision using rounding mode HALF_UP.

round(value :: FLOAT?, precision :: NUMBER?, mode :: STRING?) :: (FLOAT?)

Returns the value of a number rounded to the specified precision with the specified rounding mode.

sign()

sign(input :: FLOAT?) :: (INTEGER?)

Returns the signum of a floating point number: 0 if the number is 0, -1 for any negative number, and 1 for any positive number.

sign(input :: INTEGER?) :: (INTEGER?)

Returns the signum of an integer number: 0 if the number is 0, -1 for any negative number, and 1 for any positive number.

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

Function Signature Description

e()

e() :: (FLOAT?)

Returns the base of the natural logarithm, e.

exp()

exp(input :: FLOAT?) :: (FLOAT?)

Returns en, where e is the base of the natural logarithm, and n is the value of the argument expression.

log()

log(input :: FLOAT?) :: (FLOAT?)

Returns the natural logarithm of a number.

log10()

log10(input :: FLOAT?) :: (FLOAT?)

Returns the common logarithm (base 10) of a number.

sqrt()

sqrt(input :: FLOAT?) :: (FLOAT?)

Returns the square root of a number.

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

All trigonometric functions operate on radians, unless otherwise specified.

Function Signature Description

acos()

acos(input :: FLOAT?) :: (FLOAT?)

Returns the arccosine of a number in radians.

asin()

asin(input :: FLOAT?) :: (FLOAT?)

Returns the arcsine of a number in radians.

atan()

atan(input :: FLOAT?) :: (FLOAT?)

Returns the arctangent of a number in radians.

atan2()

atan2(y :: FLOAT?, x :: FLOAT?) :: (FLOAT?)

Returns the arctangent2 of a set of coordinates in radians.

cos()

cos(input :: FLOAT?) :: (FLOAT?)

Returns the cosine of a number.

cot()

cot(input :: FLOAT?) :: (FLOAT?)

Returns the cotangent of a number.

degrees()

degrees(input :: FLOAT?) :: (FLOAT?)

Converts radians to degrees.

haversin()

haversin(input :: FLOAT?) :: (FLOAT?)

Returns half the versine of a number.

pi()

pi() :: (FLOAT?)

Returns the mathematical constant pi.

radians()

radians(input :: FLOAT?) :: (FLOAT?)

Converts degrees to radians.

sin()

sin(input :: FLOAT?) :: (FLOAT?)

Returns the sine of a number.

tan()

tan(input :: FLOAT?) :: (FLOAT?)

Returns the tangent of a number.

These functions are used to manipulate strings or to create a string representation of another value.

Function Signature Description

left()

left(original :: STRING?, length :: INTEGER?) :: (STRING?)

Returns a string containing the specified number of leftmost characters of the original string.

ltrim()

ltrim(input :: STRING?) :: (STRING?)

Returns the original string with leading whitespace removed.

replace()

replace(original :: STRING?, search :: STRING?, replace :: STRING?) :: (STRING?)

Returns a string in which all occurrences of a specified search string in the original string have been replaced by another (specified) replace string.

reverse()

reverse(input :: STRING?) :: (STRING?)

Returns a string in which the order of all characters in the original string have been reversed.

right()

right(original :: STRING?, length :: INTEGER?) :: (STRING?)

Returns a string containing the specified number of rightmost characters of the original string.

rtrim()

rtrim(input :: STRING?) :: (STRING?)

Returns the original string with trailing whitespace removed.

split()

split(original :: STRING?, splitDelimiter :: STRING?) :: (LIST? OF STRING?)

Returns a list of strings resulting from the splitting of the original string around matches of the given delimiter.

split(original :: STRING?, splitDelimiters :: LIST? OF STRING?) :: (LIST? OF STRING?)

Returns a list of strings resulting from the splitting of the original string around matches of any of the given delimiters.

substring()

substring(original :: STRING?, start :: INTEGER?) :: (STRING?)

Returns a substring of the original string, beginning with a 0-based index start.

substring(original :: STRING?, start :: INTEGER?, length :: INTEGER?) :: (STRING?)

Returns a substring of length 'length' of the original string, beginning with a 0-based index start.

toLower()

toLower(input :: STRING?) :: (STRING?)

Returns the original string in lowercase.

toString()

toString(input :: ANY?) :: (STRING?)

Converts an integer, float, boolean, point or temporal type (i.e. Date, Time, LocalTime, DateTime, LocalDateTime or Duration) value to a string.

toStringOrNull()

toStringOrNull(input :: ANY?) :: (STRING?)

Converts an integer, float, boolean, point or temporal type (i.e. Date, Time, LocalTime, DateTime, LocalDateTime or Duration) value to a string, or null if the value cannot be converted.

toUpper()

toUpper(input :: STRING?) :: (STRING?)

Returns the original string in uppercase.

trim()

trim(input :: STRING?) :: (STRING?)

Returns the original string with leading and trailing whitespace removed.

Values of the temporal types — Date, Time, LocalTime, DateTime, and LocalDateTime — can be created manipulated using the following functions:

Function Signature Description

date()

date(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATE?)

Create a Date instant.

date.realtime()

date.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATE?)

Get the current Date instant using the realtime clock.

date.statement()

date.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATE?)

Get the current Date instant using the statement clock.

date.transaction()

date.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATE?)

Get the current Date instant using the transaction clock.

date.truncate()

date.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (DATE?)

Truncate the input temporal value to a Date instant using the specified unit.

datetime()

datetime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATETIME?)

Create a DateTime instant.

datetime.fromepoch()

datetime.fromepoch(seconds :: NUMBER?, nanoseconds :: NUMBER?) :: (DATETIME?)

Create a DateTime given the seconds and nanoseconds since the start of the epoch.

datetime.fromepochmillis()

datetime.fromepochmillis(milliseconds :: NUMBER?) :: (DATETIME?)

Create a DateTime given the milliseconds since the start of the epoch.

datetime.realtime()

datetime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATETIME?)

Get the current DateTime instant using the realtime clock.

datetime.statement()

datetime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATETIME?)

Get the current DateTime instant using the statement clock.

datetime.transaction()

datetime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATETIME?)

Get the current DateTime instant using the transaction clock.

datetime.truncate()

datetime.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (DATETIME?)

Truncate the input temporal value to a DateTime instant using the specified unit.

localdatetime()

localdatetime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALDATETIME?)

Create a LocalDateTime instant.

localdatetime.realtime()

localdatetime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALDATETIME?)

Get the current LocalDateTime instant using the realtime clock.

localdatetime.statement()

localdatetime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALDATETIME?)

Get the current LocalDateTime instant using the statement clock.

localdatetime.transaction()

localdatetime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALDATETIME?)

Get the current LocalDateTime instant using the transaction clock.

localdatetime.truncate()

localdatetime.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (LOCALDATETIME?)

Truncate the input temporal value to a LocalDateTime instant using the specified unit.

localtime()

localtime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALTIME?)

Create a LocalTime instant.

localtime.realtime()

localtime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALTIME?)

Get the current LocalTime instant using the realtime clock.

localtime.statement()

localtime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALTIME?)

Get the current LocalTime instant using the statement clock.

localtime.transaction()

localtime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALTIME?)

Get the current LocalTime instant using the transaction clock.

localtime.truncate()

localtime.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (LOCALTIME?)

Truncate the input temporal value to a LocalTime instant using the specified unit.

time()

time(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (TIME?)

Create a Time instant.

time.realtime()

time.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (TIME?)

Get the current Time instant using the realtime clock.

time.statement()

time.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (TIME?)

Get the current Time instant using the statement clock.

time.transaction()

time.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (TIME?)

Get the current Time instant using the transaction clock.

time.truncate()

time.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (TIME?)

Truncate the input temporal value to a Time instant using the specified unit.

Duration values of the temporal types can be created manipulated using the following functions:

Function Signature Description

duration()

duration(input :: ANY?) :: (DURATION?)

Construct a Duration value.

duration.between()

duration.between(from :: ANY?, to :: ANY?) :: (DURATION?)

Compute the duration between the 'from' instant (inclusive) and the 'to' instant (exclusive) in logical units.

duration.inDays()

duration.inDays(from :: ANY?, to :: ANY?) :: (DURATION?)

Compute the duration between the 'from' instant (inclusive) and the 'to' instant (exclusive) in days.

duration.inMonths()

duration.inMonths(from :: ANY?, to :: ANY?) :: (DURATION?)

Compute the duration between the 'from' instant (inclusive) and the 'to' instant (exclusive) in months.

duration.inSeconds()

duration.inSeconds(from :: ANY?, to :: ANY?) :: (DURATION?)

Compute the duration between the 'from' instant (inclusive) and the 'to' instant (exclusive) in seconds.

These functions are used to specify 2D or 3D points in a geographic or cartesian Coordinate Reference System and to calculate the geodesic distance between two points.

Function Signature Description

point.distance()

point.distance(from :: POINT?, to :: POINT?) :: (FLOAT?)

Returns a floating point number representing the geodesic distance between any two points in the same CRS.

point() - Cartesian 2D

point(input :: MAP?) :: (POINT?)

Returns a 2D point object, given two coordinate values in the Cartesian coordinate system.

point() - Cartesian 3D

point(input :: MAP?) :: (POINT?)

Returns a 3D point object, given three coordinate values in the Cartesian coordinate system.

point() - WGS 84 2D

point(input :: MAP?) :: (POINT?)

Returns a 2D point object, given two coordinate values in the WGS 84 geographic coordinate system.

point() - WGS 84 3D

point(input :: MAP?) :: (POINT?)

Returns a 3D point object, given three coordinate values in the WGS 84 geographic coordinate system.

point.withinBBox()

point.withinBBox(point :: POINT?, lowerLeft :: POINT?, upperRight :: POINT?) :: (BOOLEAN?)

Returns true if the provided point is within the bounding box defined by the two provided points, lowerLeft and upperRight.

LOAD CSV functions can be used to get information about the file that is processed by LOAD CSV.

Function Signature Description

file()

file() :: (STRING?)

Returns the absolute path of the file that LOAD CSV is using.

linenumber()

linenumber() :: (INTEGER?)

Returns the line number that LOAD CSV is currently using.

User-defined functions are written in Java, deployed into the database and are called in the same way as any other Cypher® function. There are two main types of functions that can be developed and used:

Type Description Usage Developing

Scalar

For each row the function takes parameters and returns a result.

Using UDF

Extending Neo4j (UDF)

Aggregating

Consumes many rows and produces an aggregated result.

Using aggregating UDF

Extending Neo4j (Aggregating UDF)