Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/
Documentation version: v5.3.2

# 聚合值变量

聚合值变量用于定义对嵌套值的聚合操作。在引用聚合值变量时，必须在变量名前加上`@`符号，以区别于[原始值变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/value-variable/)。

对于数值相关的聚合值变量声明，支持显式的数值类型变体，包括`INT8`、`INT16`、`INT32`、`INT64`、`FLOAT`和`DOUBLE`（具体取决于聚合值变量类型）。

聚合值变量可细分为两种类型：

- 全局聚合值变量
- 点绑定聚合值变量

Caution

点绑定聚合值变量仅适用于[临时图](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/graph-projection/create/)，而全局聚合值变量适用于持久图和临时图。

## 全局聚合值变量

全局聚合值变量必须在全局范围内声明，在声明后可以在过程的任何部分访问。

## 点绑定聚合值变量

点绑定聚合值变量必须在全局范围内使用`NODE`关键字声明，在声明后只能在匹配计算语句的[`per_block`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/match-compute/#per_block)子句中进行聚合操作。

## 对比

下表总结了全局聚合值变量和点绑定聚合值变量之间的主要区别：

 |  | 全局聚合值变量 | 点绑定聚合值变量
 | 作用域 | 在整个计算过程中维护一份共享状态。 | 图中每个点各自维护一份独立状态。
 | 适用图类型 | 图和临时图均可使用。 | 仅适用于临时图。
 | 可访问上下文 | 声明后，可在过程的任意位置访问。 | 仅可在匹配计算语句的[`per_block`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/match-compute/#per_block)子句中访问。
 | 声明方式 | `VALUE var AggType<T> [= value_expression]` | `NODE VALUE var AggType<T> [= value_expression]`
 | 引用方式 | `@var` | `<node_var>.@var`（在`PER NODE` / `PER PATH`块中使用）
 | 内存占用 | 较小。无论图的规模多大，始终只维护一份聚合状态。 | 与点数量成正比。每个点各持有一份聚合状态。
 | 分布式模式注意事项 | 每轮计算需要在所有主机之间进行一次全局合并。应避免在全局聚合值变量中存放大型集合（尤其是容器类聚合器，如`ListAgg`、`SetAgg`、`MapAgg`），因为收集的数据量越大，内存占用和跨机传输开销也越大。 | `PER NODE`操作以本地计算为主，跨机通信较少。`PER PATH`操作可能需要更多跨机通信，尤其是连接数较多的点。

Caution

全局聚合值变量适合存放标量值（如`SumAgg`、`MaxAgg`、`MinAgg`、`AvgAgg`）。如果将容器类聚合器（`ListAgg`、`SetAgg`、`MapAgg`）用作全局聚合值变量，在分布式模式下可能导致较高的内存占用和跨机传输开销，因为每轮计算都需要在所有机器之间合并整个集合。如需收集点数据，建议使用点绑定聚合值变量，或将结果导出到[表变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/table-variable/)中。

选择指引

- 如需在整个计算过程中追踪一个汇总值（如总计数、累计求和、收敛标志等），使用全局聚合值变量。
- 如需为每个点维护各自的值（如距离、得分、连通分量 ID 等），使用点绑定聚合值变量。
- 在迭代式图算法中，通常两者配合使用：点绑定聚合值变量存储每轮迭代中更新的点的结果，全局聚合值变量追踪整体进度（例如，判断当前迭代中是否有点的值发生了变化，从而决定是否需要继续迭代）。

## 语法

语法图源码

 aggregator_value_variable_definition aggr_type  

````
aggregator_value_variable_definition ::=
    'NODE'? 'VALUE' aggregator_value_variable aggr_type ('=' value_expression)?

aggr_type ::=
    SumAgg 
    | AvgAgg
    | MaxAgg
    | MinAgg  
    | AndAgg  
    | OrAgg
    | ListAgg  
    | SetAgg   
    | MapAgg
    | TopKAgg

````

## 参数

### `NODE`

可选关键字`NODE`用于指定该变量与临时图中的点的绑定关系。每个点都有一个该变量的实例，用于存储与该点绑定的值。

### `aggregator_value_variable`

要定义的聚合值变量的名称。`aggregator_value_variable`可以是常规标识符或使用反引号(```)包围的分隔标识符。有关标识符的更多信息，请参见[标识符命名规则](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/keywords-identifiers/#_3)。

### `aggr_type`

对该变量持有的嵌套值执行的聚合类型。

下表简要介绍了支持的聚合类型：

 | 聚合类型 | 描述
 | SumAgg | 对所有输入`x`，保存值`sum(x)`。更多信息，请参见 [SumAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/)。
 | AvgAgg | 对所有输入`x`，保存平均值`avg(x)`，也即`sum(x)/count(x)`。更多信息，请参见 [AvgAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/avg_agg/)。
 | MaxAgg | 对所有输入`x`，保存最大值`max(x)`。更多信息，请参见 [MaxAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/max_agg/)。
 | MinAgg | 对所有输入`x`，保存最小值`min(x)`。更多信息，请参见 [MinAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/min_agg/)。
 | AndAgg | 对所有输入`x`，保存逻辑与操作的结果。更多信息，请参见 [AndAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/and_agg/)。
 | OrAgg | 对所有输入`x`，保存逻辑或操作的结果。更多信息，请参见 [OrAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/or_agg/)。
 | ListAgg | 将所有输入按照插入顺序聚合为一个列表。更多信息，请参见 [ListAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/list_agg/)。
 | SetAgg | 将所有输入聚合为不包含重复值的集合。更多信息，请参见 [SetAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/set_agg/)。
 | MapAgg | 对每个输入`TUPLE(key, value)`，维护一个键值对的映射，其中每个键映射到一个聚合值。更多信息，请参见 [MapAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/map_agg/)。
 | TopKAgg | 对所有输入，维护基于指定排序标准的前 K 个值。更多信息，请见 [TopKAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/topk_agg/)。

### `value_expression`

用于指定该变量初始值的可选值表达式。值表达式可以是常量、函数调用或返回单个值的子查询。更多信息，请参见[值表达式](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/#_6)。

仅`SumAgg`、`MaxAgg`、`MinAgg`、`AndAgg`、`OrAgg`支持`= value_expression`。对于`AvgAgg`、`ListAgg`、`TopKAgg`、`MapAgg`、`SetAgg`，声明时指定初始值无效。

## 示例

以下示例基于[示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)中创建的图`movie`和 [CREATE TEMPORARY GRAPH](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/graph-projection/create/) 中创建的临时图`#movie_temporary_graph`。

### 定义全局聚合值变量

````
'''
USE movie { 
  VALUE a SumAgg<INT> = 0 
  VALUE b MaxAgg<DOUBLE> = 0.0 
  VALUE c MinAgg<INT> = 100 
  VALUE d AvgAgg<DOUBLE> 
  VALUE e OrAgg = false 
  VALUE f AndAgg = true 
  VALUE g ListAgg<INT> 
  VALUE h ListAgg<RECORD{x INT, y STRING}> 
  RETURN @a, @b, @c, @d, @e, @f, @g, @h 
    }
'''

````

返回：

````
+----+-----+-----+-----+-------+------+----+----+
| @a | @b  | @c  | @d  | @e    | @f   | @g | @h |
+----+-----+-----+-----+-------+------+----+----+
| 0  | 0.0 | 100 | 0.0 | false | true | [] | [] |
+----+-----+-----+-----+-------+------+----+----+

````

### 定义点绑定聚合值变量

````
'''
USE #movie_temporary_graph { 
  NODE VALUE a ListAgg<INT> 
  MATCH (v@Actor) WHERE v.id > 271940 
  PER NODE (v) { 
    SET v.@a = LIST[v.id] 
    LOG_INFO("ID_List: ", v.@a) 
  } 
}
'''

````

返回：

````
Log:
2025-07-14T07:30:37.718732 INFO  - ID_List: [271941]
2025-07-14T07:30:37.718732 INFO  - ID_List: [271947]
2025-07-14T07:30:37.718732 INFO  - ID_List: [271945]
2025-07-14T07:30:37.718978 INFO  - ID_List: [271943]
2025-07-14T07:30:37.718978 INFO  - ID_List: [271946]
2025-07-14T07:30:37.718978 INFO  - ID_List: [271944]
2025-07-14T07:30:37.718978 INFO  - ID_List: [282659]
2025-07-14T07:30:37.719037 INFO  - ID_List: [271942]

````