# 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: ## 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, therfore `-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