Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/math/
Documentation version: v5.3.2

# 数学函数

本文介绍 GQL 支持的数学函数，分为以下几类：

- [基本函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/math/#general)

- [对数函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/math/#logs)

- [三角函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/math/#tri)

## 基本函数 []()

### abs()

返回一个数的绝对值。

该函数还支持向量数据类型。更多信息，请参见[向量函数`abs()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/vector/#abs)。

NULL 行为：默认

#### 函数签名

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

````

返回值的数据类型与`num`的数据类型相同。

#### 示例

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

````

返回：

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

````

### mod()

返回除法运算的余数。

#### 函数签名

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

````

- `dividend`和`divisor`必须是相同的数据类型。
- 返回值的数据类型与`dividend`的数据类型相同。

#### 示例

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

````

返回：

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

````

### floor()

返回小于或等于给定数的最大整数或小数（小数部分为0）。

NULL 行为：默认

#### 函数签名

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

````

返回值的数据类型与`num`的数据类型相同。

#### 示例

````
RETURN floor(1.3)

````

返回：

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

````

### ceil() 和 ceiling()

返回大于或等于给定数的最小整数或小数（小数部分为0）。

NULL 行为：默认

#### 函数签名

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

````

或

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

````

返回值的数据类型与`num`的数据类型相同。

#### 示例

````
RETURN ceil(1.3) AS a

````

或

````
RETURN ceiling(1.3) AS a

````

返回：

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

````

### round()

基于给定的精度对一个数进行四舍五入。

Null 行为：默认

#### 函数签名

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

````

如果`num`的数据类型为`DECIMAL`，则返回值的数据类型为`DECIMAL`；否则，返回值的数据类型为`DOUBLE`。

#### 参数

- `num`：要四舍五入的数。
- 

`precision`：四舍五入的精度。

  - 如果省略，则默认为`0`，表示四舍五入到整数。
  - 如果指定为正数，则表示四舍五入到小数点右侧的位数。
  - 如果指定为负数，则表示四舍五入到小数点左侧的位数。

#### 示例

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

````

返回：

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

````

### exp()

返回自然底数`e`的指定次幂。

该函数还支持向量数据类型。更多信息，请参见[向量函数`exp()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/vector/#exp)。

NULL 行为：默认

#### 函数签名

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

````

如果`num`的数据类型为`DECIMAL`，则返回值的数据类型为`DECIMAL`；否则，返回值的数据类型为`DOUBLE`。

#### 示例

````
RETURN exp(1)

````

返回：

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

````

### sign()

接受一个浮点数或整数作为输入，根据输入数值的正负性返回一个特定的整数值。如果输入为正数，返回值为`1`；如果输入为负数，返回值为`-1`；如果输入为`0`、`-0.0`或`0.0`，返回值为`0`。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

##### 输入为`0`

````
RETURN sign(0)

````

返回：

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

````

##### 输入为`0.0`

````
RETURN sign(-0.0)

````

返回：

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

````

##### 输入为负数

````
RETURN sign(-0.34)

````

返回：

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

````

##### 输入为正数

````
RETURN sign(34)

````

返回：

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

````

### pi()

返回数学常数`pi`。

#### 函数签名

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

````

#### 示例

````
RETURN pi()

````

返回：

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

````

### sqrt()

返回一个数的平方根。

该函数还支持向量数据类型。更多信息，请参见[向量函数`sqrt()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/vector/#sqrt)。

NULL 行为：默认

#### 函数签名

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

````

如果`num`的数据类型为`DECIMAL`，则返回值的数据类型为`DECIMAL`；否则，返回值的数据类型为`DOUBLE`。

#### 示例

````
RETURN sqrt(3)

````

返回：

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

````

### power()

返回一个数的幂次运算结果。

NULL 行为：默认

#### 函数签名

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

````

- `base`和`exponent`必须是相同的数据类型。
- 如果`base`的数据类型为`DECIMAL`，则返回值的数据类型为`DECIMAL`；否则，返回值的数据类型为`DOUBLE`。

#### 示例

````
RETURN power(3,4)

````

返回：

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

````

### isnan()

用于检查给定的数是否是`NaN`，是则返回`TRUE`，否则返回`FALSE`。`NaN`是一种特殊的浮点数值，用于表示未定义或不可表示的结果，例如，`0/0`或无效的数学操作。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

##### 输入不是`NaN`

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

````

返回：

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

````

##### 输入是`NaN`

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

````

返回：

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

````

上面的结果使用`asin(radians(180))`返回`NaN`，然后`isnan()`返回`true`。

### rand()

返回一个范围在`0`（包含）到`1`（不包含）之间的随机浮点数。

#### 函数签名

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

````

#### 示例

##### 返回一个随机数

````
RETURN rand() AS r

````

返回：

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

````

##### 检查随机数是否在`[0,1)`范围内

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

````

返回：

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

````

### rand_geo() 和 rand_geometric()

`rand_geo()`是`rand_geometric()`的别名，两者接受相同的参数且功能相同。它们根据几何分布随机生成一个非负整数。返回值表示在第一次成功之前失败的独立伯努利试验次数，其中每次试验的成功概率为`p`。

NULL 行为：默认

#### 函数签名

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

````

或

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

````

#### 参数

- 

`p`：每次试验成功的概率。

  - 当`p`小于或等于`0`时，函数返回`INT32`的最大值`2147483647`。
  - 当`p`大于或等于`1`时，函数返回`0`。
  - 当`p`大于`0`且小于`1`时，函数返回一个随机非负整数。

#### 示例

##### 边界值

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

````

返回：

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

````

##### 返回一个服从几何分布的随机数

````
RETURN rand_geometric(0.5) AS r

````

可能的返回结果如下：

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

````

## 对数函数 []()

### log()

返回一个数在特定底数下的对数值。

NULL 行为：默认

#### 函数签名

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

````

- `b`和`num`必须是相同的数据类型。
- 如果`b`的数据类型为`DECIMAL`，则返回值的数据类型为`DECIMAL`；否则，返回值的数据类型为`DOUBLE`。

#### 示例

````
RETURN log(7,7)

````

返回：

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

````

### log10()

返回一个数在以 10 为底数下的对数值。

该函数还支持向量数据类型。更多信息，请参见[向量函数`log10()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/vector/#log10)。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

````
RETURN log10(10)

````

返回：

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

````

### ln()

返回一个数在自然底数`e`下的对数值。自然底数`e`是一个无限不循环的小数，约等于 2.71828。

该函数还支持向量数据类型。更多信息，请参见[向量函数`ln()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/vector/#ln)。

NULL 行为：默认

#### 函数签名

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

````

如果`num`的数据类型为`DECIMAL`，则返回值的数据类型为`DECIMAL`；否则，返回值的数据类型为`DOUBLE`。

#### 示例

````
RETURN ln(271801.0/99990)

````

返回：

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

````

## 三角函数 []()

### sin()

返回一个数的正弦值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

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

````

返回：

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

````

### cos()

返回一个数的余弦值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

````
RETURN cos(0) AS a

````

返回：

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

````

### tan()

返回一个数的正切值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

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

````

返回：

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

````

### cot()

返回一个数的余切值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

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

````

返回：

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

````

### sinh()

返回一个数的双曲正弦值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

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

````

返回：

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

````

### cosh()

返回一个数的双曲余弦值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

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

````

返回：

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

````

### tanh()

返回一个数的双曲正切值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

````
RETURN tanh(1)

````

返回：

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

````

### asin()

返回一个数的反正弦值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

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

````

返回：

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

````

### acos()

返回一个数的反余弦值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

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

````

返回：

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

````

### atan()

返回一个数的反正切值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

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

````

返回：

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

````

### haversin()

返回一个数的半正矢值。

NULL 行为：默认

#### 函数签名

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

````

#### 示例

示例 1：

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

````

返回：

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

````

示例 2：

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

````

返回：

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

````