Scalar functions

Wiki / Cypher query language

On this page

String functions

FunctionDescriptionExample → result
toUpper(s)UppercasetoUpper('ada') → 'ADA'
toLower(s)LowercasetoLower('ADA') → 'ada'
trim(s)Strip leading+trailing whitespacetrim(' x ') → 'x'
ltrim(s)Strip leading whitespaceltrim(' x ') → 'x '
rtrim(s)Strip trailing whitespacertrim(' x ') → ' x'
substring(s, start[, len])Substring from start (0-based), optional lengthsubstring('graph', 1, 3) → 'rap'
replace(s, search, repl)Replace all occurrencesreplace('a.b.c', '.', '-') → 'a-b-c'
split(s, delim)Split into a list of stringssplit('a,b,c', ',') → ['a','b','c']
left(s, n)First n charactersleft('graph', 2) → 'gr'
right(s, n)Last n charactersright('graph', 2) → 'ph'
reverse(s)Reverse a string (also works on lists)reverse('abc') → 'cba'
toString(x)Render supported scalars and spatial/temporal values; lists/maps/bytes errortoString(42) → '42'
randomUUID()A new random (version 4) UUID for every row, lower case with hyphens. From version 2.1.3randomUUID() → '9f1c…-4…'

Type-conversion functions

FunctionDescriptionNotes
toInteger(x)Convert to integerinteger strings and floats accepted; invalid strings return null, unsupported types error
toFloat(x)Convert numbers or numeric stringsinvalid strings return null; unsupported types error
toBoolean(x)Convert to boolean'true'/'false' (case-insensitive) → bool
toString(x)Convert to stringsee above
RETURN toInteger('42') AS i, toFloat('3.14') AS f, toBoolean('TRUE') AS b;

Numeric functions

FunctionDescriptionExample → result
abs(x)Absolute value (int or float)abs(-5) → 5
ceil(x)Round up (→ float)ceil(2.1) → 3.0
floor(x)Round down (→ float)floor(2.9) → 2.0
round(x[, precision[, mode]])Round to nearest (→ float); see Roundinground(3.141592, 3) → 3.142
sqrt(x)Square rootsqrt(9) → 3.0
sign(x)Sign: -1, 0, or 1sign(-7) → -1
isNaN(x)Whether a float is NaN; integers are never NaNisNaN(0.0 / 0.0) → true
rand()Random float in [0, 1), new for every rowrand() → 0.42…
range(start, end[, step])List of integers start..=endrange(1, 5) → [1,2,3,4,5]
UNWIND range(1, 5) AS x RETURN x, x * x AS square;

Rounding

round() returns a float and gives the same results as Neo4j. The precision and mode arguments are available from version 2.1.3.

  • round(x) rounds a half toward positive infinity: round(2.5) is 3.0 and round(-2.5) is -2.0. Results are held to the 64-bit integer range.
  • round(x, precision) keeps precision digits after the point and rounds a half away from zero: round(-2.55, 1) is -2.6. It works on the number's shortest decimal form, so round(1.005, 2) is 1.01 even though the stored float is a little below 1.005. round(x, 0) behaves like round(x).
  • round(x, precision, mode) rounds in mode, one of UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN or UNNECESSARY (upper case). UNNECESSARY fails if any digit would be lost.
RETURN round(2.5, 0, 'HALF_EVEN') AS even,    // 2.0
       round(1.21, 1, 'UP') AS up,            // 1.3
       round(-1.29, 1, 'DOWN') AS down;       // -1.2

A null argument gives null. A float precision is truncated (2.9 counts as 2). A negative precision and an unknown mode fail with Galactus.ClientError.Statement.ArgumentError, as does UNNECESSARY when rounding is needed. NaN and the infinities come back unchanged. For decimals round() returns a decimal.

Logarithmic and trigonometric functions

From version 2.1.3. All take and return floats (integers are accepted) and return null for a null argument. Angles are in radians.

FunctionResult
e(), pi()The constants e and π
exp(x)e to the power x
log(x), log10(x)Natural and base-10 logarithm; log(0) is -Infinity, a negative argument gives NaN
sin(x), cos(x), tan(x), cot(x)Sine, cosine, tangent, cotangent; cot(0) is Infinity
asin(x), acos(x), atan(x)Inverse sine, cosine and tangent; outside [-1, 1] asin and acos give NaN
atan2(y, x)Angle of the point (x, y); null if either is null
degrees(x), radians(x)Convert radians to degrees and back
haversin(x)Half the versine, (1 - cos x) / 2
RETURN round(degrees(atan2(1, 1)), 1) AS angle,  // 45.0
       round(log10(1000)) AS digits;            // 3.0

List functions

FunctionDescriptionExample → result
size(x)Length of a list/string; use size(keys(map)) for mapssize([1,2,3]) → 3
head(list)First element (or null)head([10,20]) → 10
last(list)Last element (or null)last([10,20]) → 20
tail(list)All but the first elementtail([10,20,30]) → [20,30]
reverse(list)Reversereverse([1,2,3]) → [3,2,1]
range(a, b[, step])Integer list (see numeric)

(List indexing l[i] and slicing l[a..b] are operators — see Operators and expressions.)

Null-handling

FunctionDescription
coalesce(a, b, …)First non-null argument; null if all are null. Does not null-propagate.
MATCH (p:Person) RETURN coalesce(p.nick, p.name, 'anonymous') AS display;

Graph / entity functions

FunctionDescription
id(e)Internal integer id of a node or relationship
elementId(e)String form of the internal integer id; not stable across deletion/reuse
labels(n)List of a node's labels
type(r)A relationship's type (string)
startNode(r)The node a relationship starts from
endNode(r)The node a relationship ends at (startNode and endNode from version 2.4.0)
keys(e)List of an entity's (or map's) property keys
properties(e)The entity's properties as a map
nodes(p)The nodes of a path p, in order
relationships(p)The relationships of a path p, in order
length(p)Number of relationships in a path p
MATCH p = (a:Person {name: 'Ada'})-[:KNOWS*1..3]->(b)
RETURN b.name, length(p), [n IN nodes(p) | n.name] AS chain;

List and pattern comprehensions are supported; see comprehensions.

MATCH (n) RETURN id(n), labels(n), keys(n), properties(n) LIMIT 5;
MATCH ()-[r]->() RETURN type(r) LIMIT 5;

Spatial & temporal constructors

FunctionDescriptionSee
point({...})Construct a Point (cartesian or WGS-84)Spatial points
distance(a, b) / point.distance(a, b)Distance between two pointsSpatial points
spatial.fromWKT, spatial.fromWKB, spatial.fromGeoJSONStrict geometry/geography constructorsFormats and drivers
spatial.intersects, spatial.contains, spatial.covers and other predicatesTest shape relationshipsPredicates and overlays
spatial.union, spatial.intersection, spatial.difference, spatial.symDifference, spatial.clip, spatial.identityCombine, cut or partition shapesPredicates and overlays
spatial.centroidWeighted centre, retaining domain and SRIDCentroid
datetime(...)Construct/parse/re-zone a zoned DateTimeTemporal values and time zones
date(...)Construct/parse a DATE; truncates a (local)datetime value or string (no arg = today, UTC)Temporal values and time zones
localtime(...) / time(...)A local / zoned time-of-dayTemporal values and time zones
localdatetime(...)A zoneless date-timeTemporal values and time zones
duration(...)Construct/parse a DURATION (ISO-8601 or a component map)Temporal values and time zones
duration.between(a, b)The duration between two temporalsTemporal values and time zones
timestamp()The current time as integer milliseconds since the Unix epoch (from 1.4.1)Temporal values and time zones

Point and temporal fields are read by access syntax, not functions: p.x, p.y, p.z, p.longitude, p.latitude, p.height, p.srid, p.crs; dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.nanosecond, dt.epochSeconds, dt.epochMillis, dt.offsetSeconds, dt.offset, dt.timezone; a DURATION's .years, .months, .days, .hours, .minutes, .seconds, .milliseconds, .nanoseconds.

range includes both endpoints, accepts a negative step for descending ranges, and rejects a zero step. For example, RETURN range(5, 1, -2) returns [5,3,1]. See aggregates for row-level grouping and APOC scalar functions for additional collection operations.

Indexes and constraints · Procedure directory · Transactions and concurrency

Planning a deployment? Review compatibility and licence setup for your instance.