Mathematical functions - numeric

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

Functions:

abs()
ceil()
floor()
rand()
round()
round(), with precision
round(), with precision and rounding mode
sign()

The following graph is used for the examples below:

graph numeric functions

abs()

abs() returns the absolute value of the given number.

Syntax:

abs(expression)

Returns:

The type of the value returned will be that of expression.

Arguments:

Name Description

Name	Description
`expression`	A numeric expression.

expression

A numeric expression.

Considerations:

abs(null) returns null.

If expression is negative, -(expression) (i.e. the negation of expression) 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.

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

ceil()

ceil() returns the smallest floating point number that is greater than or equal to the given number and equal to a mathematical integer.

Syntax:

ceil(expression)

Returns:

A Float.

Arguments:

Name Description

Name	Description
`expression`	A numeric expression.

expression

A numeric expression.

Considerations:

ceil(null) returns null.

Example 2. ceil()

Query

RETURN ceil(0.1)

The ceil of 0.1 is returned.

Table 2. Result
ceil(0.1)
`1.0`
Rows: 1

floor()

floor() returns the largest floating point number that is less than or equal to the given number and equal to a mathematical integer.

Syntax:

floor(expression)

Returns:

A Float.

Arguments:

Name Description

Name	Description
`expression`	A numeric expression.

expression

A numeric expression.

Considerations:

floor(null) returns null.

Example 3. floor()

Query

RETURN floor(0.9)

The floor of 0.9 is returned.

Table 3. Result
floor(0.9)
`0.0`
Rows: 1

rand()

rand() returns a random floating point number in the range from 0 (inclusive) to 1 (exclusive); i.e. [0,1). The numbers returned follow an approximate uniform distribution.

Syntax:

rand()

Returns:

A Float.

Example 4. rand()

Query

RETURN rand()

A random number is returned.

Table 4. Result
rand()
`0.5460251846326871`
Rows: 1

round()

round() returns the value of the given number rounded to the nearest integer, with ties always rounded towards positive infinity.

Syntax:

round(expression)

Returns:

A Float.

Arguments:

Name Description

Name	Description
`expression`	A numeric expression to be rounded.

expression

A numeric expression to be rounded.

Considerations:

round(null) returns null.

Example 5. round()

Query

RETURN round(3.141592)

3.0 is returned.

Table 5. Result
round(3.141592)
`3.0`
Rows: 1

Example 6. round() of negative number with tie

Query

RETURN round(-1.5)

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

Table 6. Result
round(-1.5)
`-1.0`
Rows: 1

round(), with precision

round() returns the value of the given number rounded to the closest value of given precision, with ties always being rounded away from zero (using rounding mode HALF_UP). The exception is for precision 0, where ties are rounded towards positive infinity to align with round() without precision.

Syntax:

round(expression, precision)

Returns:

A Float.

Arguments:

Name Description

Name	Description
`expression`	A numeric expression to be rounded.
`precision`	A numeric expression specifying precision.

expression

A numeric expression to be rounded.

precision

A numeric expression specifying precision.

Considerations:

round() returns null if any of its input parameters are null.

Example 7. round() with precision

Query

RETURN round(3.141592, 3)

3.142 is returned.

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

Example 8. round() with precision 0 and tie

Query

RETURN round(-1.5, 0)

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

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

Example 9. 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.

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

round(), with precision and rounding mode

round() returns the value of the given number rounded with the specified precision and the specified rounding mode.

Syntax:

round(expression, precision, mode)

Returns:

A Float.

Arguments:

Name Description

Name	Description
`expression`	A numeric expression to be rounded.
`precision`	A numeric expression specifying precision.
`mode`	A string expression specifying rounding mode.

expression

A numeric expression to be rounded.

precision

A numeric expression specifying precision.

mode

A string expression specifying rounding mode.

Modes:

Mode Description

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

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

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

Example 11. 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.

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

Example 12. 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.

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

Example 13. 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.

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

Example 14. 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.

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

Example 15. 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.

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

Example 16. 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.

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

sign()

sign() returns the signum of the given number: 0 if the number is 0, -1 for any negative number, and 1 for any positive number.

Syntax:

sign(expression)

Returns:

An Integer.

Arguments:

Name Description

Name	Description
`expression`	A numeric expression.

expression

A numeric expression.

Considerations:

sign(null) returns null.

Example 17. sign()

Query

RETURN sign(-17), sign(0.1)

The signs of -17 and 0.1 are returned.

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