Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/
Documentation version: v5.3.2

# Math functions

GQL supports these categories of mathematical functions:

- [General](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/#general_functions)

- [Logarithmic](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/#logarithmic_functions)

- [Trigonometric](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/#trigonometric_functions)

## General functions

### abs()

Returns the absolute value of a number.

This function also supports vector data types. For details, see the [Vector function `abs()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/vector/#abs).

Null behavior: default

#### Function signature

````
abs(num: Numeric) -> Numeric

````

The return value is of the same data type as that of `num`.

#### Examples

````
RETURN abs(3) AS intAbs, abs(-3.3) AS floatAbs

````

Return:

````
+--------+----------+
| intAbs | floatAbs |
+--------+----------+
| 3      | 3.3      |
+--------+----------+

````

### mod()

Returns the modulus (remainder) of a division operation.

#### Function signature

````
mod(dividend: Numeric, divisor: Numeric) -> Numeric

````

- `dividend` and `divisor` must be of the same data type.
- The return value is of the same data type as that of `dividend`.

#### Examples

````
RETURN mod(7,3) AS m

````

Return:

````
+---+
| m |
+---+
| 1 |
+---+

````

### floor()

Returns the largest decimal whose fractional part is 0 or the largest integer that is less than or equal to a given number.

Null behavior: default

#### Function signature

````
floor(num: Numeric) -> Numeric

````

The return value is of the same data type as that of `num`.

#### Examples

````
RETURN floor(1.3)

````

Return:

````
+------------+
| floor(1.3) |
+------------+
| 1          |
+------------+

````

### ceil() and ceiling()

The `ceil()` and `ceiling` functions return the smallest decimal whose fractional part is 0 or the smallest integer that is greater than or equal to a given number.

Null behavior: default

#### Function signature

````
ceil(num: Numeric) -> Numeric

````

or

````
ceiling(num: Numeric) -> Numeric

````

The return value is of the same data type as that of `num`.

#### Examples

````
RETURN ceil(1.3) AS a

````

or

````
RETURN ceiling(1.3) AS a

````

Return:

````
+---+
| a |
+---+
| 2 |
+---+

````

### round()

Returns the value of a given number rounded to the closest value of a given precision.

Null behavior: default

#### Function signature

````
round(num: Numeric [, precision: INT32 ]) ->  DOUBLE | DECIMAL 

````

If `num` is of data type `DECIMAL`, the return value is of data type `DECIMAL`; otherwise, the return value is of data type `DOUBLE`.

#### Parameters

- `num`: The number to be rounded.
- 

`precision`: The precision to which the number is rounded.

  - If not specified, the default value is `0`, indicating that the number is rounded to the nearest integer.
  - If a positive integer is specified, the number is rounded to the specified number of decimal places to the right of the decimal point.
  - If a negative integer is specified, the number is rounded to the specified number of decimal places to the left of the decimal point.

#### Examples

````
RETURN round(4.5) AS a, round(4.55, 1) AS b, round(45, -1) AS c

````

Return:

````
+---+-----+----+
| a | b   | c  |
+---+-----+----+
| 5 | 4.6 | 50 |
+---+-----+----+

````

### exp()

Returns Euler's number `e` raised to the power of a number.

This function also supports vector data types. For details, see the [Vector function `exp()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/vector/#exp).

Null behavior: default

#### Function signature

````
exp(num: Numeric) ->  DOUBLE | DECIMAL 

````

If `num` is of data type `DECIMAL`, the return value is of data type `DECIMAL`; otherwise, the return value is of data type `DOUBLE`.

#### Examples

````
RETURN exp(1)

````

Return:

````
+-------------------+
| exp(1)            |
+-------------------+
| 2.718281828459045 |
+-------------------+

````

### sign()

Takes a floating-point number or integer as an input and returns a value indicating the sign of the input. The return value is `1` if the input is positive, `-1` if the input is negative, and `0` if the input is `0`, `-0.0`, or `0.0`.

Null behavior: default

#### Function signature

````
sign(num: Numeric) -> INT8

````

#### Examples

##### Input is `0`

````
RETURN sign(0)

````

Return:

````
+---------+
| sign(0) |
+---------+
| 0       |
+---------+

````

##### Input is `0.0`

````
RETURN sign(-0.0)

````

Return:

````
+------------+
| sign(-(0)) |
+------------+
| 0          |
+------------+

````

##### Input is a negative number

````
RETURN sign(-0.34)

````

Return:

````
+-------------+
| sign(-0.34) |
+-------------+
| -1          |
+-------------+

````

##### Input is a positive number

````
RETURN sign(34)

````

Return:

````
+----------+
| sign(34) |
+----------+
| 1        |
+----------+

````

### pi()

Returns the mathematical constant `pi`.

#### Function signature

````
pi() -> DOUBLE | FLOAT

````

#### Examples

````
RETURN pi()

````

Return:

````
+-------------------+
| pi()              |
+-------------------+
| 3.141592653589793 |
+-------------------+

````

### sqrt()

Returns the square root of a number.

This function also supports vector data types. For details, see the [Vector function `sqrt()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/vector/#sqrt).

Null behavior: default

#### Function signature

````
sqrt(num: Numeric) -> DOUBLE | DECIMAL

````

If `num` is of data type `DECIMAL`, the return value is of data type `DECIMAL`; otherwise, the return value is of data type `DOUBLE`.

#### Examples

````
RETURN sqrt(3)

````

Return:

````
+--------------------+
| sqrt(3)            |
+--------------------+
| 1.7320508075688772 |
+--------------------+

````

### power()

Returns the value of `base` raised to the power of `exponent`.

Null behavior: default

#### Function signature

````
power(base: Numeric, exponent: Numeric) -> DOUBLE | DECIMAL

````

- `base` and `exponent` must be of the same data type.
- If `base` is of data type `DECIMAL`, the return value is of data type `DECIMAL`; otherwise, the return value is of data type `DOUBLE`.

#### Examples

````
RETURN power(3,4)

````

Return:

````
+------------+
| power(3,4) |
+------------+
| 81.0       |
+------------+

````

### isnan()

Returns `true` if the given number is `NaN` (not a number), otherwise `false`. `NaN` is a special value that represents an undefined or unrepresentable value.

Null behavior: default

#### Function signature

````
isnan(num: Numeric) -> BOOLEAN

````

#### Examples

##### Input is not `NaN`

````
RETURN isnan(cosh(28))

````

Return:

````
+-----------------+
| isnan(cosh(28)) |
+-----------------+
| false           |
+-----------------+

````

##### Input is `NaN`

````
RETURN isnan(asin(radians(180)))

````

Return:

````
+---------------------------+
| isnan(asin(radians(180))) |
+---------------------------+
| true                      |
+---------------------------+

````

The preceding result uses `asin(radians(180))` to return `NaN`, and then `isnan()` returns `true`.

### rand()

Returns a random floating-point number in the range from `0` (inclusive) to `1` (exclusive).

#### Function signature

````
rand() -> DOUBLE | FLOAT

````

#### Examples

##### Return a random number

````
RETURN rand() AS r

````

Return:

````
+--------------------+
| r                  |
+--------------------+
| 0.8603127559959718 |
+--------------------+

````

##### Check if the random number falls within the range `[0,1)`

````
RETURN rand()>=0 and rand()<1 AS r

````

Return:

````
+------+
| r    |
+------+
| true |
+------+

````

### rand_geo() and rand_geometric()

`rand_geo()` is an alias of `rand_geometric()`. Both functions accept the same argument and have identical behavior. They generate a random non-negative integer based on a geometric distribution. The return value is the number of independent Bernoulli trials that fail before the first success, where each trial has a probability `p` of success.

Null behavior: default

#### Function signature

````
rand_geo(p: DOUBLE) -> INT32

````

or

````
rand_geometric(p: DOUBLE) -> INT32

````

#### Parameters

- 

`p`: The probability of success in each trial.

  - If `p` is less than or equal to `0`, the function returns the maximum `INT32` value, `2147483647`.
  - If `p` is greater than or equal to `1`, the function returns `0`.
  - If `p` is greater than `0` and less than `1`, the function returns a random non-negative integer.

#### Examples

##### Boundary values

````
RETURN rand_geo(0) AS a, rand_geometric(1) AS b

````

Return:

````
+------------+---+
| a          | b |
+------------+---+
| 2147483647 | 0 |
+------------+---+

````

##### Return a geometrically distributed random number

````
RETURN rand_geometric(0.5) AS r

````

One possible return is:

````
+---+
| r |
+---+
| 2 |
+---+

````

## Logarithmic functions

### log()

Returns the logarithm of a given number with a base.

Null behavior: default

#### Function signature

````
log(b: Numeric, num: Numeric) ->  DOUBLE | DECIMAL 

````

- `b` and `num` must be of the same data type.
- If `b` is of data type `DECIMAL`, the return value is of data type `DECIMAL`; otherwise, the return value is of data type `DOUBLE`.

#### Examples

````
RETURN log(7,7)

````

Return:

````
+-----------+
| log(7,7) |
+-----------+
| 1.0       |
+-----------+

````

### log10()

Returns the base-10 logarithm of a given number.

This function also supports vector data types. For details, see the [Vector function `log10()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/vector/#log10).

Null behavior: default

#### Function signature

````
log10(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN log10(10)

````

Return:

````
+-----------+
| log10(10) |
+-----------+
| 1.0       |
+-----------+

````

### ln()

Returns the natural logarithm (base `e`) of a given number. The base `e` is an irrational and transcendental number, approximately equal to 2.71828.

This function also supports vector data types. For details, see the [Vector function `ln()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/vector/#ln).

Null behavior: default

#### Function signature

````
ln(num: Numeric) ->  DOUBLE | DECIMAL 

````

If `num` is of data type `DECIMAL`, the return value is of data type `DECIMAL`; otherwise, the return value is of data type `DOUBLE`.

#### Examples

````
RETURN ln(271801.0/99990)

````

Return:

````
+------------------------+
| ln(271801.0/99990)     |
+------------------------+
| 0.99999999989838178269 |
+------------------------+

````

## Trigonometric functions

### sin()

Returns the sine of a number.

Null behavior: default

#### Function signature

````
sin(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN sin(radians(90)) AS a

````

Return:

````
+-----+
| a   |
+-----+
| 1.0 |
+-----+

````

### cos()

Returns the cosine of a number.

Null behavior: default

#### Function signature

````
cos(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN cos(0) AS a

````

Return:

````
+-----+
| a   |
+-----+
| 1.0 |
+-----+

````

### tan()

Returns the tangent of a number.

Null behavior: default

#### Function signature

````
tan(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN tan(0.25*radians(180)) AS a

````

Return:

````
+--------------------+
| a                  |
+--------------------+
| 0.9999999999999999 |
+--------------------+

````

### cot()

Returns the cotangent of a number.

Null behavior: default

#### Function signature

````
cot(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN cot(0.25*radians(180)) AS a

````

Return:

````
+--------------------+
| a                  |
+--------------------+
| 1.0000000000000002 |
+--------------------+

````

### sinh()

Returns the hyperbolic sine of a number.

Null behavior: default

#### Function signature

````
sinh(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN sinh(radians(180)) AS a

````

Return: 

````
+--------------------+
| a                  |
+--------------------+
| 11.548739357257748 |
+--------------------+

````

### cosh()

Returns the hyperbolic cosine of a number.

Null behavior: default

#### Function signature

````
cosh(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN cosh(radians(180)) AS a

````

Return:

````
+--------------------+
| a                  |
+--------------------+
| 11.591953275521519 |
+--------------------+

````

### tanh()

Returns the hyperbolic tangent of a number.

Null behavior: default

#### Function signature

````
tanh(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN tanh(1)

````

Return:

````
+--------------------+
| tanh(1)            |
+--------------------+
| 0.7615941559557649 |
+--------------------+

````

### asin()

Returns the arcsine of a number.

Null behavior: default

#### Function signature

````
asin(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN asin(radians(180))

````

Return:

````
+--------------------+
| asin(radians(180)) |
+--------------------+
| NaN                |
+--------------------+

````

### acos()

Returns the arccosine of a number.

Null behavior: default

#### Function signature

````
acos(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN acos(radians(0))

````

Return:

````
+--------------------+
| acos(radians(0))   |
+--------------------+
| 1.5707963267948966 |
+--------------------+

````

### atan()

Returns the arctangent of a number.

Null behavior: default

#### Function signature

````
atan(num: Numeric) -> DOUBLE

````

#### Examples

````
RETURN atan(radians(180))

````

Return:

````
+--------------------+
| atan(radians(180)) |
+--------------------+
| 1.2626272556789118 |
+--------------------+

````

### haversin()

Returns the haversine of a number.

Null behavior: default

#### Function signature

````
haversin(num: Numeric) -> DOUBLE

````

#### Examples

Example 1:

````
RETURN haversin(radians(0))

````

Return:

````
+----------------------+
| haversin(radians(0)) |
+----------------------+
| 0.0                  |
+----------------------+

````

Example 2:

````
RETURN haversin(radians(180))

````

Return:

````
+------------------------+
| haversin(radians(180)) |
+------------------------+
| 1.0                    |
+------------------------+

````