Mathematical functions - numeric

Numeric mathematical functions operate on numeric expressions only, and will return an error if used on any other values. See also Mathematical operators.

Example graph

The following graph is used for the examples below:

To recreate the graph, run the following query against an empty Neo4j database:

CREATE
  (alice:Developer {name:'Alice', age: 38, eyes: 'Brown'}),
  (bob:Administrator {name: 'Bob', age: 25, eyes: 'Blue'}),
  (charlie:Administrator {name: 'Charlie', age: 53, eyes: 'Green'}),
  (daniel:Adminstrator {name: 'Daniel', age: 54, eyes: 'Brown'}),
  (eskil:Designer {name: 'Eskil', age: 41, eyes: 'blue', likedColors: ['Pink', 'Yellow', 'Black']}),
  (alice)-[:KNOWS]->(bob),
  (alice)-[:KNOWS]->(charlie),
  (bob)-[:KNOWS]->(daniel),
  (charlie)-[:KNOWS]->(daniel),
  (bob)-[:MARRIED]->(eskil)

abs()

Details
Syntax	`abs(input)`
Description	Returns the absolute value of an `INTEGER` or `FLOAT`.
Arguments	Name	Type	Description
	`input`	`INTEGER \| FLOAT`	A numeric value from which the absolute number will be returned.
Returns	`INTEGER \| FLOAT`

Considerations
`abs(null)` returns `null`.
If `input` is negative, `-(input)` (i.e. the negation of `input`) is returned.

Example 1. abs()

Query

MATCH (a), (e) WHERE a.name = 'Alice' AND e.name = 'Eskil'
RETURN a.age, e.age, abs(a.age - e.age)

The absolute value of the age difference is returned.

Result
a.age	e.age	abs(a.age - e.age)
`38`	`41`	`3`
Rows: 1

ceil()

Details
Syntax	`ceil(input)`
Description	Returns the smallest `FLOAT` that is greater than or equal to a number and equal to an `INTEGER`.
Arguments	Name	Type	Description
	`input`	`FLOAT`	A value to be rounded to the nearest higher integer.
Returns	`FLOAT`

Considerations
`ceil(null)` returns `null`.

Example 2. ceil()

Query

RETURN ceil(0.1)

The ceil of 0.1 is returned.

Result
ceil(0.1)
`1.0`
Rows: 1

floor()

Details
Syntax	`floor(input)`
Description	Returns the largest `FLOAT` that is less than or equal to a number and equal to an `INTEGER`.
Arguments	Name	Type	Description
	`input`	`FLOAT`	A value to be rounded to the nearest lower integer.
Returns	`FLOAT`

Considerations
`floor(null)` returns `null`.

Example 3. floor()

Query

RETURN floor(0.9)

The floor of 0.9 is returned.

Result
floor(0.9)
`0.0`
Rows: 1

isNaN()

Details
Syntax	`isNaN(input)`
Description	Returns whether the given `INTEGER` or `FLOAT` is NaN.
Arguments	Name	Type	Description
	`input`	`INTEGER \| FLOAT`	A numeric value to be compared against `NaN`.
Returns	`BOOLEAN`

Considerations
`isNaN(null)` returns `null`.

Example 4. isNaN()

Query

RETURN isNaN(0/0.0)

true is returned since the value is NaN.

Result
isNaN(0/0.0)
`true`
Rows: 1

rand()

Details
Syntax	`rand()`
Description	Returns a random `FLOAT` in the range from 0 (inclusive) to 1 (exclusive).
Returns	`FLOAT`

Example 5. rand()

Query

RETURN rand()

A random number is returned.

Result
rand()
`0.5460251846326871`
Rows: 1

round()

Details
Syntax	`round(value[, precision, mode])`
Description	Returns the value of a rounded number, optionally using a specified precision and rounding mode.
Arguments	Name	Type	Description
	`value`	`FLOAT`	A value to be rounded.
	`precision`	`INTEGER \| FLOAT`	The rounding precision.
	`mode`	`STRING`	A precision rounding mode (`UP`, `DOWN`, `CEILING`, `FLOOR`, `HALF_UP`, `HALF_DOWN`, `HALF_EVEN`).
Returns	`FLOAT`

Modes
`mode`	Description
`UP`	Round away from zero.
`DOWN`	Round towards zero.
`CEILING`	Round towards positive infinity.
`FLOOR`	Round towards negative infinity.
`HALF_UP`	Round towards closest value of given precision, with ties always being rounded away from zero.
`HALF_DOWN`	Round towards closest value of given precision, with ties always being rounded towards zero.
`HALF_EVEN`	Round towards closest value of given precision, with ties always being rounded to the even neighbor.

Considerations
For the rounding modes, a tie means that the two closest values of the given precision are at the same distance from the given value. E.g. for precision 1, 2.15 is a tie as it has equal distance to 2.1 and 2.2, while 2.151 is not a tie, as it is closer to 2.2.
`round()` returns `null` if any of its input parameters are `null`.

Example 6. round()

Query

RETURN round(3.141592)

3.0 is returned.

Result
round(3.141592)
`3.0`
Rows: 1

Example 7. round() of negative number with tie

Query

RETURN round(-1.5)

Ties are rounded towards positive infinity, therefore -1.0 is returned.

Result
round(-1.5)
`-1.0`
Rows: 1

round() with precision

Example 8. round() with precision

Query

RETURN round(3.141592, 3)

3.142 is returned.

Result
round(3.141592, 3)
`3.142`
Rows: 1

Example 9. round() with precision 0 and tie

Query

RETURN round(-1.5, 0)

To align with round(-1.5), -1.0 is returned.

Result
round(-1.5, 0)
`-1.0`
Rows: 1

Example 10. round() with precision 1 and tie

Query

RETURN round(-1.55, 1)

The default is to round away from zero when there is a tie, therefore -1.6 is returned.

Result
round(-1.55, 1)
`-1.6`
Rows: 1

round() with precision and rounding mode

Example 11. round() with precision and UP rounding mode

Query

RETURN round(1.249, 1, 'UP') AS positive,
round(-1.251, 1, 'UP') AS negative,
round(1.25, 1, 'UP') AS positiveTie,
round(-1.35, 1, 'UP') AS negativeTie

The rounded values using precision 1 and rounding mode UP are returned.

Result
positive	negative	positiveTie	negativeTie
`1.3`	`-1.3`	`1.3`	`-1.4`
Rows: 1

Example 12. round() with precision and DOWN rounding mode

Query

RETURN round(1.249, 1, 'DOWN') AS positive,
round(-1.251, 1, 'DOWN') AS negative,
round(1.25, 1, 'DOWN') AS positiveTie,
round(-1.35, 1, 'DOWN') AS negativeTie

The rounded values using precision 1 and rounding mode DOWN are returned.

Result
positive	negative	positiveTie	negativeTie
`1.2`	`-1.2`	`1.2`	`+-1.3`
Rows: 1

Example 13. round() with precision and CEILING rounding mode

Query

RETURN round(1.249, 1, 'CEILING') AS positive,
round(-1.251, 1, 'CEILING') AS negative,
round(1.25, 1, 'CEILING') AS positiveTie,
round(-1.35, 1, 'CEILING') AS negativeTie

The rounded values using precision 1 and rounding mode CEILING are returned.

Result
positive	negative	positiveTie	negativeTie
`1.3`	`-1.2`	`1.3`	`-1.3`
Rows: 1

Example 14. round() with precision and FLOOR rounding mode

Query

RETURN round(1.249, 1, 'FLOOR') AS positive,
round(-1.251, 1, 'FLOOR') AS negative,
round(1.25, 1, 'FLOOR') AS positiveTie,
round(-1.35, 1, 'FLOOR') AS negativeTie

The rounded values using precision 1 and rounding mode FLOOR are returned.

Result
positive	negative	positiveTie	negativeTie
`1.2`	`-1.3`	`1.2`	`-1.4`
Rows: 1

Example 15. round() with precision and HALF_UP rounding mode

Query

RETURN round(1.249, 1, 'HALF_UP') AS positive,
round(-1.251, 1, 'HALF_UP') AS negative,
round(1.25, 1, 'HALF_UP') AS positiveTie,
round(-1.35, 1, 'HALF_UP') AS negativeTie

The rounded values using precision 1 and rounding mode HALF_UP are returned.

Result
positive	negative	positiveTie	negativeTie
`1.2`	`-1.3`	`1.3`	`-1.4`
Rows: 1

Example 16. round() with precision and HALF_DOWN rounding mode

Query

RETURN round(1.249, 1, 'HALF_DOWN') AS positive,
round(-1.251, 1, 'HALF_DOWN') AS negative,
round(1.25, 1, 'HALF_DOWN') AS positiveTie,
round(-1.35, 1, 'HALF_DOWN') AS negativeTie

The rounded values using precision 1 and rounding mode HALF_DOWN are returned.

Result
positive	negative	positiveTie	negativeTie
`1.2`	`-1.3`	`1.2`	`-1.3`
Rows: 1

Example 17. round() with precision and HALF_EVEN rounding mode

Query

RETURN round(1.249, 1, 'HALF_EVEN') AS positive,
round(-1.251, 1, 'HALF_EVEN') AS negative,
round(1.25, 1, 'HALF_EVEN') AS positiveTie,
round(-1.35, 1, 'HALF_EVEN') AS negativeTie

The rounded values using precision 1 and rounding mode HALF_EVEN are returned.

Result
positive	negative	positiveTie	negativeTie
`1.2`	`-1.3`	`1.2`	`-1.4`
Rows: 1

sign()

Details
Syntax	`sign(input)`
Description	Returns the signum of an `INTEGER` or `FLOAT`: 0 if the number is 0, -1 for any negative number, and 1 for any positive number.
Arguments	Name	Type	Description
	`input`	`INTEGER \| FLOAT`	A positive or negative number.
Returns	`INTEGER`

Considerations
`sign(null)` returns `null`.

Example 18. sign()

Query

RETURN sign(-17), sign(0.1)

The signs of -17 and 0.1 are returned.

Result
sign(-17)	sign(0.1)
`-1`	`1`
Rows: 1