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.

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

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 FLOAT that is greater than or equal to the given number and equal to an INTEGER.

Syntax:

ceil(expression)

Returns:

FLOAT

Arguments:

Name Description

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 FLOAT that is less than or equal to the given number and equal to an INTEGER.

Syntax:

floor(expression)

Returns:

FLOAT

Arguments:

Name Description

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

isNaN()

isNaN() returns true if the given numeric value is NaN (Not a Number).

Syntax:

isNaN(expression)

Returns:

BOOLEAN

Arguments:

Name Description

expression

A numeric expression.

Considerations:

isNaN(null) returns null.

Example 4. isNaN()
Query
RETURN isNaN(0/0.0)

true is returned since the value is NaN.

Table 4. Result
isNaN(0/0.0)

true

Rows: 1

rand()

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

Syntax:

rand()

Returns:

FLOAT

Example 5. rand()
Query
RETURN rand()

A random number is returned.

Table 5. 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:

FLOAT

Arguments:

Name Description

expression

A numeric expression to be rounded.

Considerations:

round(null) returns null.

Example 6. round()
Query
RETURN round(3.141592)

3.0 is returned.

Table 6. 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.

Table 7. 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:

FLOAT

Arguments:

Name Description

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 8. round() with precision
Query
RETURN round(3.141592, 3)

3.142 is returned.

Table 8. 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.

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

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

FLOAT

Arguments:

Name Description

expression

A numeric expression to be rounded.

precision

A numeric expression specifying precision.

mode

A string expression specifying rounding mode.

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

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

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

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

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

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

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

Table 17. 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:

INTEGER

Arguments:

Name Description

expression

A numeric expression.

Considerations:

sign(null) returns null.

Example 18. sign()
Query
RETURN sign(-17), sign(0.1)

The signs of -17 and 0.1 are returned.

Table 18. Result
sign(-17) sign(0.1)

-1

1

Rows: 1