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

# 聚合函数

本文描述悦数图数据库开发版中的聚合函数用法，适用于持久图和临时图。

GQL 中的聚合函数用于对一组数据进行计算并返回单一值。若要查看每个聚合函数所支持的数据类型，可使用 [SHOW FUNCTION](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-admin/show/show-functions/) 进行查询。

`DISTINCT`关键字可用于在聚合函数中去除重复值，确保计算仅基于唯一值。例如，`sum(DISTINCT x)`计算`x`的所有唯一值的总和。更多信息，请参见[聚合表达式](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/expressions/aggregate/)。

## avg()

返回一组值的平均值。

NULL 行为：忽略

### 函数签名

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

````

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

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN avg(i) GROUP BY ()

````

返回：

````
+--------------------+
| avg(i)             |
+--------------------+
| 3.3333333333333335 |
+--------------------+

````

示例 2：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN avg(DISTINCT i) GROUP BY ()

````

返回：

````
+-----------------+
| avg(DISTINCT i) |
+-----------------+
| 3.0             |
+-----------------+

````

示例 3：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN avg(e.rate) AS rate, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+-------------------+--------------------------+
| rate              | movie                    |
+-------------------+--------------------------+
| 3.879120879120879 | Star Trek: First Contact |
+-------------------+--------------------------+

````

## collect() 和 collect_list()

将一组值聚合到一个列表中。

NULL 行为：忽略

### 函数签名

````
collect(n: E) -> LIST

````

或

````
collect_list(n: E) -> LIST

````

`E`代表任意数据类型。

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN collect(i) GROUP BY ()

````

返回：

````
+---------------+
| collect(i)    |
+---------------+
| [1,2,3,4,5,5] |
+---------------+

````

示例 2：

````
FOR i IN LIST [LIST[1,2],LIST[2,3,4]] RETURN collect(i) GROUP BY ()

````

返回：

````
+-----------------+
| collect(i)      |
+-----------------+
| [[1,2],[2,3,4]] |
+-----------------+

````

示例 3：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN collect_list(DISTINCT i) GROUP BY ()

````

返回：

````
+--------------------------+
| collect_list(DISTINCT i) |
+--------------------------+
| [5,4,3,2,1]              |
+--------------------------+

````

示例 4：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:1}) 
ORDER BY e.rate ASC 
RETURN collect(e.rate) AS rate_collect, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+-----------------------------------------------------------------------------------+--------------+
| rate_collect                                                                      | movie        |
+-----------------------------------------------------------------------------------+--------------+
| [2.0,2.5,3.5,3.5,3.5,3.5,3.5,3.5,4.0,4.0,4.0,4.0,4.5,4.5,4.5,4.5,4.5,4.5,4.5,5.0] | Cowboy Bebop |
+-----------------------------------------------------------------------------------+--------------+

````

## count()

返回一组数据的数量统计。

- 如果`count()`的入参为`*`，则计数时记入`NULL`值。
- 如果`count()`的入参不为`*`，则计数时不记入`NULL`值。

### 函数签名

````
count(n: E) -> INT64

````

`E`：代表任意数据类型。

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN count(i) GROUP BY ()

````

返回：

````
+----------+
| count(i) |
+----------+
| 6        |
+----------+

````

示例 2：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN count(DISTINCT i) GROUP BY ()

````

返回：

````
+-------------------+
| count(DISTINCT i) |
+-------------------+
| 5                 |
+-------------------+

````

示例 3：

````
FOR i IN LIST [1,2,3,4,5,5,null] RETURN count(*) GROUP BY ()

````

返回：

````
+----------+
| count(*) |
+----------+
| 7        |
+----------+

````

示例 4：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN count(e.rate) AS rate_count, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+------------+--------------------------+
| rate_count | movie                    |
+------------+--------------------------+
| 91         | Star Trek: First Contact |
+------------+--------------------------+

````

## max()

返回一组数据中最大的数。

NULL 行为：忽略

### 函数签名

````
max(n: E) -> E

````

`E`代表以下数据类型之一：[数值](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/numeric-type/)、[字符串](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/c-string-type/)、[日期和时间](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/)。返回值的数据类型与输入值的数据类型相同。关于不同数据类型的比较规则，请参见[比较运算符](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/comparison/#comp_op)。

Note

对于日期和时间类型为`DURATION`的数据，使用聚合函数`max()`和`min()`时，所有被比较的值必须属于同一单位组。例如，不能将基于年和月为单位的时间段单位组（如：P1Y2M）与基于天和时间为单位的时间段单位组（如：PT10H）进行比较。

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN max(i) GROUP BY ()

````

返回：

````
+--------+
| max(i) |
+--------+
| 5      |
+--------+

````

示例 2：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN max(DISTINCT i) GROUP BY ()

````

返回：

````
+-----------------+
| max(DISTINCT i) |
+-----------------+
| 5               |
+-----------------+

````

示例 3：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN max(e.rate) AS rate_max, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+----------+--------------------------+
| rate_max | movie                    |
+----------+--------------------------+
| 5.0      | Star Trek: First Contact |
+----------+--------------------------+

````

示例 4:

````
FOR i IN LIST ["apple", "banana", "apricot"] RETURN max(i) AS a GROUP BY ()

````

返回：

````
+------------+
| a          |
+------------+
| banana     |
+------------+

````

示例 5:

````
FOR i IN LIST [duration("P1Y2M"), duration("P1Y1M"), duration("P2Y")] RETURN max(i) AS a GROUP BY ()

````

返回：

````
+-----+
| a   |
+-----+
| P2Y |
+-----+

````

## min()

返回一组数据中最小的数。

NULL 行为：忽略

### 函数签名

````
min(n: E) -> E

````

`E`代表以下数据类型之一：[数值](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/numeric-type/)、[字符串](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/c-string-type/)以及[日期和时间](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/)。返回值的数据类型与输入值的数据类型相同。关于不同数据类型的比较规则，请参见[比较运算符](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/comparison/#comp_op)。

Note

对于日期和时间类型为`DURATION`的数据，使用聚合函数`max()`和`min()`时，所有被比较的值必须属于同一单位组。例如，不能将基于年和月为单位的时间段单位组（如：P1Y2M）与基于天和时间为单位的时间段单位组（如：PT10H）进行比较。

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN min(i) GROUP BY ()

````

返回：

````
+--------+
| min(i) |
+--------+
| 1      |
+--------+

````

示例 2：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN min(DISTINCT i) GROUP BY ()

````

返回：

````
+-----------------+
| min(DISTINCT i) |
+-----------------+
| 1               |
+-----------------+

````

示例 3：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN min(e.rate) AS rate_min, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+----------+--------------------------+
| rate_min | movie                    |
+----------+--------------------------+
| 0.5      | Star Trek: First Contact |
+----------+--------------------------+

````

示例 4:

````
FOR i IN LIST ["user", "username", "usergroup"] RETURN min(i) AS a GROUP BY ()

````

返回：

````
+------------+
| a          |
+------------+
| user       |
+------------+

````

示例 5:

````
FOR i IN LIST [duration("P1Y6M"), duration("P1Y9M"), duration("P1Y2M")] RETURN min(i) AS a GROUP BY ()

````

返回：

````
+------------+
| a          |
+------------+
| P1Y2M      |
+------------+

````

## sum()

返回一组数据的总和。

NULL 行为：忽略

### 函数签名

````
sum(num: Numeric) -> UINT64 | INT64 | DOUBLE | DECIMAL

````

- 如果`num`是有符号整数，返回值的数据类型为`INT64`。
- 如果`num`是无符号整数，返回值的数据类型为`UINT64`。
- 如果`num`是浮点数，返回值的数据类型为`DOUBLE`。
- 如果`num`是任意精度数，返回值的数据类型为`DECIMAL`。

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN sum(i) GROUP BY ()

````

返回：

````
+--------+
| sum(i) |
+--------+
| 20     |
+--------+

````

示例 2：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN sum(DISTINCT i) GROUP BY ()

````

返回：

````
+-----------------+
| sum(DISTINCT i) |
+-----------------+
| 15              |
+-----------------+

````

示例 3：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN sum(e.rate) AS rate_sum, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+----------+--------------------------+
| rate_sum | movie                    |
+----------+--------------------------+
| 353.0    | Star Trek: First Contact |
+----------+--------------------------+

````

## stddev_pop()

返回一组数据的总体标准差。

NULL 行为：忽略

### 函数签名

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

````

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

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN stddev_pop(i) GROUP BY ()

````

返回：

````
+--------------------+
| stddev_pop(i)      |
+--------------------+
| 1.4907119849998596 |
+--------------------+

````

示例 2：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN stddev_pop(e.rate) AS rate_stddev_pop, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+--------------------+--------------------------+
| rate_stddev_pop    | movie                    |
+--------------------+--------------------------+
| 0.9843295797912273 | Star Trek: First Contact |
+--------------------+--------------------------+

````

## stddev_samp()

返回一组数据的样本标准差。

NULL 行为：忽略

### 函数签名

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

````

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

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN stddev_samp(i) GROUP BY ()

````

返回：

````
+-------------------+
| stddev_samp(i)    |
+-------------------+
| 1.632993161855452 |
+-------------------+

````

示例 2：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN stddev_samp(e.rate) AS rate_stddev_samp, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+--------------------+--------------------------+
| rate_stddev_samp   | movie                    |
+--------------------+--------------------------+
| 0.9897829709943133 | Star Trek: First Contact |
+--------------------+--------------------------+

````

## percentile_cont()

统计学中的逆分布函数。该函数接受一个 0 到 1 之间的百分位数，并返回在排序后的一组数据中对应该百分位数的位置的插值。

NULL 行为：忽略

### 函数签名

````
percentile_cont(num: Numeric, percentile: DOUBLE) -> DOUBLE | DECIMAL

````

- 当`num`的数据类型为`INT64`时，返回值的数据类型为`DOUBLE`。
- 当`num`的数据类型为`DECIMAL`时，返回值的数据类型为`DECIMAL`。
- 当`num`的数据类型为`DOUBLE`时，返回值的数据类型为`DOUBLE`。

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN percentile_cont(i, 0.5) GROUP BY ()

````

返回：

````
+-------------------------+
| percentile_cont(i, 0.5) |
+-------------------------+
| 3.5                     |
+-------------------------+

````

示例 2：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN percentile_cont(e.rate, 0.5) AS r_percentile_cont, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+-------------------+--------------------------+
| r_percentile_cont | movie                    |
+-------------------+--------------------------+
| 4.0               | Star Trek: First Contact |
+-------------------+--------------------------+

````

## percentile_disc()

统计学中的逆分布函数。该函数接受一个 0 到 1 之间的百分位数，并返回在排序后的一组数据中最接近指定百分位数的实际值，而不是插值。

NULL 行为：忽略

### 函数签名

````
percentile_disc(num: Numeric, percentile: DOUBLE) -> DOUBLE | DECIMAL

````

- 当`num`的数据类型为`INT64`时，返回值的数据类型为`DOUBLE`。
- 当`num`的数据类型为`DECIMAL`时，返回值的数据类型为`DECIMAL`。
- 当`num`的数据类型为`DOUBLE`时，返回值的数据类型为`DOUBLE`。

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN percentile_disc(i, 0.5) GROUP BY ()

````

返回：

````
+-------------------------+
| percentile_disc(i, 0.5) |
+-------------------------+
| 3.0                     |
+-------------------------+

````

示例 2：

````
'''
USE movie 
MATCH (v1)-[e:Watch]->(v2 {id:199}) 
RETURN percentile_disc(e.rate, 0.5) AS r_percentile_disc, v2.name AS movie GROUP BY movie
'''

````

返回：

````
+-------------------+--------------------------+
| r_percentile_disc | movie                    |
+-------------------+--------------------------+
| 4.0               | Star Trek: First Contact |
+-------------------+--------------------------+

````

## any_value()

返回一组值中的任意值。

NULL 行为：忽略

### 函数签名

````
any_value(n: E) -> E

````

`E`：代表任意数据类型。

### 示例

示例 1：

````
FOR i IN LIST [1,2,3,4,5,5] RETURN any_value(i) GROUP BY ()

````

返回：

````
+--------------+
| any_value(i) |
+--------------+
| 1            |
+--------------+

````

示例 2：

以下示例基于[示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)。

````
'''
USE movie MATCH (v@Actor) RETURN any_value(v) AS rr GROUP BY ()
'''

````

返回：

````
+--------------------------------------------------------------------------------------+
| rr                                                                                   |
+--------------------------------------------------------------------------------------+
| (288399322985267201@Actor:Person{birthDate:1967-08-12,id:85752,name:"Brent Sexton"}) |
+--------------------------------------------------------------------------------------+

````