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<ANY> WHERE predicate :: ANY) :: BOOLEAN

Returns true if the predicate holds for all elements in the given LIST<ANY>.

any()

any(variable :: VARIABLE IN list :: LIST<ANY> WHERE predicate :: ANY) :: BOOLEAN

Returns true if the predicate holds for at least one element in the given LIST<ANY>.

exists()

exists(input :: ANY) :: BOOLEAN

Returns true if a match for the pattern exists in the graph.

isEmpty()

isEmpty(input :: LIST<ANY>) :: BOOLEAN

Checks whether a LIST<ANY> 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<ANY> WHERE predicate :: ANY) :: BOOLEAN

Returns true if the predicate holds for no element in the given LIST<ANY>.

single()

single(variable :: VARIABLE IN list :: LIST<ANY> WHERE predicate :: ANY) :: BOOLEAN

Returns true if the predicate holds for exactly one of the elements in the given LIST<ANY>.

These functions return a single value.

Function Signature Description

char_length()

char_length(input :: STRING) :: INTEGER

Returns the number of Unicode characters in a STRING. Introduced in 5.13

character_length()

character_length(input :: STRING) :: INTEGER

Returns the number of Unicode characters in a STRING. Introduced in 5.13

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<ANY>) :: ANY

Returns the first element in a LIST<ANY>.

id()

id(input :: NODE) :: INTEGER

Deprecated Returns the id of a NODE. Replaced by elementId()

id(input :: RELATIONSHIP) :: INTEGER

Deprecated Returns the id of a RELATIONSHIP. Replaced by elementId().

last()

last(list :: LIST<ANY>) :: ANY

Returns the last element in a LIST<ANY>.

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<ANY>) :: INTEGER

Returns the number of items in a LIST<ANY>.

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.

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 :: INTEGER | FLOAT) :: FLOAT

Converts an INTEGER value to a FLOAT value.

toFloat(input :: STRING) :: FLOAT

Converts a STRING value to a FLOAT value.

toFloatOrNull()

toFloatOrNull(input :: ANY) :: FLOAT

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

toInteger()

toInteger(input :: INTEGER | FLOAT) :: INTEGER

Converts a FLOAT 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 a STRING representation of the RELATIONSHIP type.

valueType()

valueType(input :: ANY) :: STRING

Returns a STRING representation of the most precise value type that the given expression evaluates to.

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 FLOAT values.

avg(input :: INTEGER) :: INTEGER

Returns the average of a set of INTEGER values.

collect()

collect(input :: ANY) :: LIST<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 FLOAT 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 DURATION values.

sum(input :: FLOAT) :: FLOAT

Returns the sum of a set of FLOAT values.

sum(input :: INTEGER) :: INTEGER

Returns the sum of a set of INTEGER values.

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<STRING>

Returns a LIST<STRING> containing the STRING representations for all the property names of a MAP.

keys(input :: NODE) :: LIST<STRING>

Returns a LIST<STRING> containing the STRING representations for all the property names of a NODE.

keys(input :: RELATIONSHIP) :: LIST<STRING>

Returns a LIST<STRING> containing the STRING representations for all the property names of a RELATIONSHIP.

labels()

labels(input :: NODE) :: LIST<STRING>

Returns a LIST<STRING> containing the STRING representations for all the labels of a NODE.

nodes()

nodes(input :: PATH) :: LIST<NODE>

Returns a LIST<NODE> containing all the NODE values in a PATH.

range()

range(start :: INTEGER, end :: INTEGER) :: LIST<INTEGER>

Returns a LIST<INTEGER> comprising all INTEGER values within a specified range.

range(start :: INTEGER, end :: INTEGER, step :: INTEGER) :: LIST<INTEGER>

Returns a LIST<INTEGER> comprising all INTEGER values within a specified range created with step length.

reduce()

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

Runs an expression against individual elements of a LIST<ANY>, storing the result of the expression in an accumulator.

relationships()

relationships(input :: PATH) :: LIST<RELATIONSHIP>

Returns a LIST<RELATIONSHIP> containing all the RELATIONSHIP values in a PATH.

reverse()

reverse(input :: LIST<ANY>) :: LIST<ANY>

Returns a LIST<ANY> in which the order of all elements in the given LIST<ANY> have been reversed.

tail()

tail(input :: LIST<ANY>) :: LIST<ANY>

Returns all but the first element in a LIST<ANY>.

toBooleanList()

toBooleanList(input :: LIST<ANY>) :: LIST<BOOLEAN>

Converts a LIST<ANY> of values to a LIST<BOOLEAN> values. If any values are not convertible to BOOLEAN they will be null in the LIST<BOOLEAN> returned.

toFloatList()

toFloatList(input :: LIST<ANY>) :: LIST<FLOAT>

Converts a LIST<ANY> to a LIST<FLOAT> values. If any values are not convertible to FLOAT they will be null in the LIST<FLOAT> returned.

toIntegerList()

toIntegerList(input :: LIST<ANY>) :: LIST<INTEGER>

Converts a LIST<ANY> to a LIST<INTEGER> values. If any values are not convertible to INTEGER they will be null in the LIST<INTEGER> returned.

toStringList()

toStringList(input :: LIST<ANY>) :: LIST<STRING>

Converts a LIST<ANY> to a LIST<STRING> values. If any values are not convertible to STRING they will be null in the LIST<STRING> 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 FLOAT.

abs(input :: INTEGER) :: INTEGER

Returns the absolute value of an INTEGER.

ceil()

ceil(input :: FLOAT) :: FLOAT

Returns the smallest FLOAT that is greater than or equal to a number and equal to an INTEGER.

floor()

floor(input :: FLOAT) :: FLOAT

Returns the largest FLOAT that is less than or equal to a number and equal to an INTEGER.

isNaN()

isNaN(input :: FLOAT) :: BOOLEAN

Returns true if the floating point number is NaN.

isNaN(input :: INTEGER) :: BOOLEAN

Returns true if the integer number is NaN.

rand()

rand() :: FLOAT

Returns a random FLOAT in the range from 0 (inclusive) to 1 (exclusive).

round()

round(input :: FLOAT) :: FLOAT

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

round(value :: FLOAT, precision :: INTEGER | FLOAT) :: FLOAT

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

round(value :: FLOAT, precision :: INTEGER | FLOAT, 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 FLOAT: 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: 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 FLOAT.

log10()

log10(input :: FLOAT) :: FLOAT

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

sqrt()

sqrt(input :: FLOAT) :: FLOAT

Returns the square root of a FLOAT.

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 FLOAT in radians.

asin()

asin(input :: FLOAT) :: FLOAT

Returns the arcsine of a FLOAT in radians.

atan()

atan(input :: FLOAT) :: FLOAT

Returns the arctangent of a FLOAT 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 FLOAT.

cot()

cot(input :: FLOAT) :: FLOAT

Returns the cotangent of a FLOAT.

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 FLOAT.

tan()

tan(input :: FLOAT) :: FLOAT

Returns the tangent of a FLOAT.

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 (INTEGER) of leftmost characters in the given STRING.

ltrim()

ltrim(input :: STRING) :: STRING

Returns the given 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 given STRING have been replaced by another (specified) replacement STRING.

reverse()

reverse(input :: STRING) :: STRING

Returns a STRING in which the order of all characters in the given STRING have been reversed.

right()

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

Returns a STRING containing the specified number of rightmost characters in the given STRING.

rtrim()

rtrim(input :: STRING) :: STRING

Returns the given STRING with trailing whitespace removed.

split()

split(original :: STRING, splitDelimiter :: STRING) :: LIST<STRING>

Returns a LIST<STRING> resulting from the splitting of the given STRING around matches of the given delimiter.

split(original :: STRING, splitDelimiters :: LIST<STRING>) :: LIST<STRING>

Returns a LIST<STRING> resulting from the splitting of the given STRING around matches of any of the given delimiters.

substring()

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

Returns a substring of the given STRING, beginning with a 0-based index start.

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

Returns a substring of a given length from the given STRING, beginning with a 0-based index start.

toLower()

toLower(input :: STRING) :: STRING

Returns the given STRING in lowercase.

toString()

toString(input :: ANY) :: STRING

Converts an INTEGER, FLOAT, BOOLEAN, POINT or temporal type (i.e. DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, LOCAL DATETIME or DURATION) value to a STRING.

toStringOrNull()

toStringOrNull(input :: ANY) :: STRING

Converts an INTEGER, FLOAT, BOOLEAN, POINT or temporal type (i.e. DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, LOCAL DATETIME or DURATION) value to a STRING, or null if the value cannot be converted.

toUpper()

toUpper(input :: STRING) :: STRING

Returns the given STRING in uppercase.

trim()

trim(input :: STRING) :: STRING

Returns the given STRING with leading and trailing whitespace removed.

Values of the temporal types — DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, and LOCAL DATETIME — can be created manipulated using the following functions:

Function Signature Description

date()

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

Creates a DATE instant.

date.realtime()

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

Returns the current DATE instant using the realtime clock.

date.statement()

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

Returns the current DATE instant using the statement clock.

date.transaction()

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

Returns the current DATE instant using the transaction clock.

date.truncate()

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

Truncates the given temporal value to a DATE instant using the specified unit.

datetime()

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

Creates a ZONED DATETIME instant.

datetime.fromepoch()

datetime.fromepoch(seconds :: INTEGER | FLOAT, nanoseconds :: INTEGER | FLOAT) :: ZONED DATETIME

Creates a ZONED DATETIME given the seconds and nanoseconds since the start of the epoch.

datetime.fromepochmillis()

datetime.fromepochmillis(milliseconds :: INTEGER | FLOAT) :: ZONED DATETIME

Creates a ZONED DATETIME given the milliseconds since the start of the epoch.

datetime.realtime()

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

Returns the current ZONED DATETIME instant using the realtime clock.

datetime.statement()

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

Returns the current ZONED DATETIME instant using the statement clock.

datetime.transaction()

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

Returns the current ZONED DATETIME instant using the transaction clock.

datetime.truncate()

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

Truncates the given temporal value to a ZONED DATETIME instant using the specified unit.

localdatetime()

localdatetime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL DATETIME

Creates a LOCAL DATETIME instant.

localdatetime.realtime()

localdatetime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL DATETIME

Returns the current LOCAL DATETIME instant using the realtime clock.

localdatetime.statement()

localdatetime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL DATETIME

Returns the current LOCAL DATETIME instant using the statement clock.

localdatetime.transaction()

localdatetime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL DATETIME

Returns the current LOCAL DATETIME instant using the transaction clock.

localdatetime.truncate()

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

Truncates the given temporal value to a LOCAL DATETIME instant using the specified unit.

localtime()

localtime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL TIME

Creates a LOCAL TIME instant.

localtime.realtime()

localtime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL TIME

Returns the current LOCAL TIME instant using the realtime clock.

localtime.statement()

localtime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL TIME

Returns the current LOCAL TIME instant using the statement clock.

localtime.transaction()

localtime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL TIME

Returns the current LOCAL TIME instant using the transaction clock.

localtime.truncate()

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

Truncates the given temporal value to a LOCAL TIME instant using the specified unit.

time()

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

Creates a ZONED TIME instant.

time.realtime()

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

Returns the current ZONED TIME instant using the realtime clock.

time.statement()

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

Returns the current ZONED TIME instant using the statement clock.

time.transaction()

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

Returns the current ZONED TIME instant using the transaction clock.

time.truncate()

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

Truncates the given temporal value to a ZONED 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

Constructs a DURATION value.

duration.between()

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

Computes the DURATION between the from instant (inclusive) and the to instant (exclusive) in logical units.

duration.inDays()

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

Computes the DURATION between the from instant (inclusive) and the to instant (exclusive) in days.

duration.inMonths()

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

Computes the DURATION between the from instant (inclusive) and the to instant (exclusive) in months.

duration.inSeconds()

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

Computes 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 FLOAT 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.

Graph functions provide information about the constituent graphs in composite databases.

Function Signature Description

graph.byElementId()

USE graph.byElementId(elementId :: STRING)

Resolves the constituent graph to which a given element id belongs. Introduced in Neo4j 5.13

graph.byName()

USE graph.byName(name :: STRING)

Resolves a constituent graph by name.

graph.names()

graph.names() :: LIST<STRING>

Returns a list containing the names of all graphs in the current composite database.

graph.propertiesByName()

graph.propertiesByName(name :: STRING) :: MAP

Returns a map containing the properties associated with the given graph.

Database functions Introduced in 5.12

Database functions provide information about databases.

Function Signature Description

db.nameFromElementId()

db.nameFromElementId(name :: STRING) :: STRING

Resolves the database name from the given element id. Introduced in 5.12

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)