# Scalar functions

[Wiki](../README.md) / [Cypher query language](README.md)

**On this page**

- [String functions](#string-functions)
- [Type-conversion functions](#type-conversion-functions)
- [Numeric functions](#numeric-functions)
  - [Rounding](#rounding)
- [Logarithmic and trigonometric functions](#logarithmic-and-trigonometric-functions)
- [List functions](#list-functions)
- [Null-handling](#null-handling)
- [Graph / entity functions](#graph--entity-functions)
- [Spatial & temporal constructors](#spatial--temporal-constructors)

## String functions

| Function | Description | Example → result |
|---|---|---|
| `toUpper(s)` | Uppercase | `toUpper('ada')` → `'ADA'` |
| `toLower(s)` | Lowercase | `toLower('ADA')` → `'ada'` |
| `trim(s)` | Strip leading+trailing whitespace | `trim('  x ')` → `'x'` |
| `ltrim(s)` | Strip leading whitespace | `ltrim('  x ')` → `'x '` |
| `rtrim(s)` | Strip trailing whitespace | `rtrim('  x ')` → `'  x'` |
| `substring(s, start[, len])` | Substring from `start` (0-based), optional length | `substring('graph', 1, 3)` → `'rap'` |
| `replace(s, search, repl)` | Replace all occurrences | `replace('a.b.c', '.', '-')` → `'a-b-c'` |
| `split(s, delim)` | Split into a list of strings | `split('a,b,c', ',')` → `['a','b','c']` |
| `left(s, n)` | First `n` characters | `left('graph', 2)` → `'gr'` |
| `right(s, n)` | Last `n` characters | `right('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 error | `toString(42)` → `'42'` |
| `randomUUID()` | A new random (version 4) UUID for every row, lower case with hyphens. From version 2.1.3 | `randomUUID()` → `'9f1c…-4…'` |

## Type-conversion functions

| Function | Description | Notes |
|---|---|---|
| `toInteger(x)` | Convert to integer | integer strings and floats accepted; invalid strings return `null`, unsupported types error |
| `toFloat(x)` | Convert numbers or numeric strings | invalid strings return `null`; unsupported types error |
| `toBoolean(x)` | Convert to boolean | `'true'`/`'false'` (case-insensitive) → bool |
| `toString(x)` | Convert to string | see above |

```cypher
RETURN toInteger('42') AS i, toFloat('3.14') AS f, toBoolean('TRUE') AS b;
```

## Numeric functions

| Function | Description | Example → 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 [Rounding](#rounding) | `round(3.141592, 3)` → `3.142` |
| `sqrt(x)` | Square root | `sqrt(9)` → `3.0` |
| `sign(x)` | Sign: -1, 0, or 1 | `sign(-7)` → `-1` |
| `isNaN(x)` | Whether a float is NaN; integers are never NaN | `isNaN(0.0 / 0.0)` → `true` |
| `rand()` | Random float in `[0, 1)`, new for every row | `rand()` → `0.42…` |
| `range(start, end[, step])` | List of integers `start..=end` | `range(1, 5)` → `[1,2,3,4,5]` |

```cypher
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.

```cypher
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](../types/decimal.md#functions) `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.

| Function | Result |
|---|---|
| `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` |

```cypher
RETURN round(degrees(atan2(1, 1)), 1) AS angle,  // 45.0
       round(log10(1000)) AS digits;            // 3.0
```

## List functions

| Function | Description | Example → result |
|---|---|---|
| `size(x)` | Length of a list/string; use `size(keys(map))` for maps | `size([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 element | `tail([10,20,30])` → `[20,30]` |
| `reverse(list)` | Reverse | `reverse([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](expressions.md#list--map-operations).)

## Null-handling

| Function | Description |
|---|---|
| `coalesce(a, b, …)` | First non-null argument; `null` if all are null. Does **not** null-propagate. |

```cypher
MATCH (p:Person) RETURN coalesce(p.nick, p.name, 'anonymous') AS display;
```

## Graph / entity functions

| Function | Description |
|---|---|
| `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` |

```cypher
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](expressions.md#list--pattern-comprehensions).

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

## Spatial & temporal constructors

| Function | Description | See |
|---|---|---|
| `point({...})` | Construct a `Point` (cartesian or WGS-84) | [Spatial points](../types/spatial.md#spatial-point) |
| `distance(a, b)` / `point.distance(a, b)` | Distance between two points | [Spatial points](../types/spatial.md#spatial-point) |
| `spatial.fromWKT`, `spatial.fromWKB`, `spatial.fromGeoJSON` | Strict geometry/geography constructors | [Formats and drivers](../types/spatial-shapes.md#formats-validation-and-drivers) |
| `spatial.intersects`, `spatial.contains`, `spatial.covers` and other predicates | Test shape relationships | [Predicates and overlays](../types/spatial-shapes.md#predicates-and-overlays) |
| `spatial.union`, `spatial.intersection`, `spatial.difference`, `spatial.symDifference`, `spatial.clip`, `spatial.identity` | Combine, cut or partition shapes | [Predicates and overlays](../types/spatial-shapes.md#predicates-and-overlays) |
| `spatial.centroid` | Weighted centre, retaining domain and SRID | [Centroid](../types/spatial-shapes.md#centroid) |
| `datetime(...)` | Construct/parse/re-zone a zoned `DateTime` | [Temporal values and time zones](../types/temporal.md#temporal-datetime) |
| `date(...)` | Construct/parse a `DATE`; truncates a (local)datetime value or string (no arg = today, UTC) | [Temporal values and time zones](../types/temporal.md#the-other-temporal-types) |
| `localtime(...)` / `time(...)` | A local / zoned time-of-day | [Temporal values and time zones](../types/temporal.md#the-other-temporal-types) |
| `localdatetime(...)` | A zoneless date-time | [Temporal values and time zones](../types/temporal.md#the-other-temporal-types) |
| `duration(...)` | Construct/parse a `DURATION` (ISO-8601 or a component map) | [Temporal values and time zones](../types/temporal.md#the-other-temporal-types) |
| `duration.between(a, b)` | The duration between two temporals | [Temporal values and time zones](../types/temporal.md#the-other-temporal-types) |
| `timestamp()` | The current time as integer milliseconds since the Unix epoch (from 1.4.1) | [Temporal values and time zones](../types/temporal.md#construct-parse-and-re-zone) |

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](aggregates.md) for row-level grouping and
[APOC scalar functions](../apoc/functions.md) for additional collection operations.

## Related articles

[Indexes and constraints](../indexes/README.md) · [Procedure directory](../reference/procedures.md) · [Transactions and concurrency](../operations/transactions.md)
