Skip to content
Developer Edition runs on one host and does not require a product license file. Need multi-host deployment or performance testing at scale? Explore Enterprise Edition

Math functions

GQL supports these categories of mathematical 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().

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

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

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

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

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